Quick Start

Get Shipyard running locally in minutes

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

macOS

# 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:

Dashboard UI

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

kubectl

# List all pods in your namespace
kubectl get pods -n sandbox-dev-user

# View logs from a specific pod
kubectl logs -f <pod-name> -n sandbox-dev-user

Docker

# Find the Kind container
docker ps | grep kind

# Access the Kind cluster
docker exec -it kind-control-plane bash

# View logs inside the container
kubectl logs -f <pod-name> -n sandbox-dev-user

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

Server not starting

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

Cannot access deployments at .localhost

Ensure Traefik is running:

kubectl get pods -n traefik

Restart port forwarding:

kubectl port-forward -n traefik svc/traefik 8080:80

Kind cluster creation fails

Delete existing cluster and retry:

kind delete cluster --name shipyard
make dev-local

Images not building

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