Skip to main content
This guide will get you up and running with Shipyard’s k8s-scheduler platform on your local machine using Kind (Kubernetes in Docker).

​
Prerequisites

Before you begin, ensure you have the following installed:

Docker

Required for running Kind cluster

kubectl

Kubernetes command-line tool

kind

Kubernetes in Docker

Helm

Kubernetes package manager
# Install using Homebrew
brew install docker kubectl kind helm

​
One-Command Setup

Clone the repository and start the local development environment: 
git clone https://github.com/ops-north/shipyard.git
cd shipyard/k8s-scheduler
make dev-local
This single command will:
1

Create Kind cluster

Creates a local Kubernetes cluster with port mappings for accessing services
2

Deploy PostgreSQL

Installs PostgreSQL for storing users, organizations, teams, and deployments
3

Build container images

Builds the Go server and operator Docker images
4

Deploy to Kubernetes

Deploys the server, operator, and all dependencies to the Kind cluster
5

Start Traefik ingress

Configures ingress routing for user deployments

​
Accessing the Platform

Once the setup completes (approximately 3-5 minutes), you can access:

​
Web Interface

Open your browser and navigate to: 
http://localhost:8081
In development mode, you’ll be automatically logged in as dev@localhost with no OAuth required.

​
What You’ll See

The dashboard displays:
  • Deployments: Your active and pending deployments
  • Teams: Team management and invitations
  • Templates: Available deployment templates
  • Secrets: Three-tier secrets management

​
Create Your First Deployment

1

Navigate to Deployments

Click Deployments in the sidebar to view your deployments page.
2

Click New Deployment

Click the New Deployment button in the top right.
3

Select a template

Choose from available templates:
  • nginx - Simple web server
  • postgres - PostgreSQL database
  • redis - Redis cache
  • LibreChat - AI chat platform (multi-service)
4

Configure and deploy

  • Enter a deployment name (e.g., my-nginx)
  • Set any required environment variables
  • Configure secrets (optional)
  • Click Deploy
5

Access your deployment

Once running, your deployment will be available at:
http://<deployment-name>.localhost:8080
For example: http://my-nginx.localhost:8080

​
Viewing Logs

Monitor your deployment logs in real-time:
  1. Click on your deployment in the dashboard
  2. Navigate to the Logs tab
  3. View live streaming logs from all services

​
Development Workflow

​
Making Changes to the Server

# Edit code in internal/server/ or cmd/server/

# Rebuild and reload
make dev-reload

# Server will restart with your changes

​
Making Changes to the Operator

# Edit code in internal/operator/ or cmd/operator/

# Rebuild and redeploy operator
make dev-reload-operator

​
Making Changes to the UI

# Navigate to the UI directory
cd ui

# Start the Vite dev server with hot reload
npm run dev

# UI will be available at http://localhost:5173
# with API proxied to http://localhost:8081

​
Cleanup

When you’re done, tear down the local environment: 
make dev-local-down
This removes:
  • The Kind cluster
  • All deployed resources
  • Container images (optional: use make dev-local-clean to also remove images)
This will delete all data in the local PostgreSQL database. Deployments and configurations will be lost.

​
Troubleshooting

Check the server logs:
kubectl logs -f deployment/server -n default
Common issues:
  • Database connection failed: Ensure PostgreSQL is running
  • Port 8081 already in use: Stop other services using this port
Ensure Traefik is running:
kubectl get pods -n traefik
Restart port forwarding:
kubectl port-forward -n traefik svc/traefik 8080:80
Delete existing cluster and retry:
kind delete cluster --name shipyard
make dev-local
Clean Docker build cache:
docker system prune -a
make dev-local

​
Next Steps

Architecture

Understand Shipyard’s system architecture

Local Development

Deep dive into local development workflows

Deployment Guide

Deploy to production on AWS

API Reference

Explore the REST API

Build docs developers (and LLMs) love

Get started for freeTalk to us