Shipyard

A self-hosted internal deployment platform — think Vercel, running on your own Kubernetes cluster. Supports Next.js, Node.js, Spring Boot, PHP, and static sites with preview environments, one-click rollbacks, and a unified developer CLI. Projects can be organized into groups (e.g., "frontend", "backend") and tagged with labels for filtering and cost attribution.

Architecture

Every deployment flows through three async stages: build → deploy → live. Each stage is a separate BullMQ worker process. A fourth cleanup worker runs cron jobs for maintenance.

Queue Details

Cleanup Routines

Namespaces

URL Scheme

Secrets model

Two-tier encryption: project env vars are AES-256-GCM encrypted with a per-project DEK, itself encrypted with a platform-wide KEK stored only in the cluster Secret. The raw KEK never appears in logs, API responses, or application code paths beyond the single encrypt/decrypt call site. Git source OAuth tokens are encrypted at rest with the same KEK.

Authentication

JWT access tokens (15-minute expiry) + opaque refresh tokens (30-day expiry, rotated on each use). API tokens for CI/CD are prefixed ship_ and stored as SHA-256 hashes. Both clients (dashboard and CLI) auto-refresh silently on 401 before surfacing an error.

Local Development

Requirements

• Node 22 LTS (.nvmrc pins the version)
• pnpm ≥ 9.x
• Docker Desktop

Start the full stack

Copy# 1. Install all dependencies
pnpm install

# 2. Start Postgres, Redis, MinIO, and local registry
docker-compose -f docker-compose.dev.yml up -d

# 3. Run database migrations
pnpm --filter=@shipyard/db migrate

# 4. Seed local data
pnpm tsx scripts/seed.ts

# 5. Start the API (port 3001)
pnpm --filter=@shipyard/api dev

# 6. Start the dashboard (port 5173)
pnpm --filter=@shipyard/dashboard dev

Common commands

Copy# Build all packages
pnpm turbo build

# Type-check everything
pnpm turbo typecheck

# Lint everything
pnpm turbo lint

# Run all tests
pnpm turbo test

# Run tests for one package
pnpm turbo test --filter=packages/buildpack

# Run a single migration generation
pnpm --filter=@shipyard/db migrate:generate

Environment flags

All four default to false so the workers run in sim mode locally — deployments complete without needing a real cluster.

Completed Sprints

Each sprint is a focused feature slice shipped as a single commit.

Upcoming Sprints

Prioritised backlog — each is a self-contained sprint.

Production Deployment Guide

Deploying Shipyard itself to GKE on Google Cloud Platform. Target domain: shipyard.wake.co.ke.

Step 1 — GCP Setup

Install gcloud CLI

Copybrew install --cask google-cloud-sdk
gcloud init   # opens browser, log in, select project

Enable required APIs

Copygcloud services enable container.googleapis.com artifactregistry.googleapis.com compute.googleapis.com cloudbuild.googleapis.com --project=shipyard-254

Step 2 — GKE Cluster

Create a Standard (not Autopilot) cluster in africa-south1 (Johannesburg — lowest latency for Kenya). The --scopes=cloud-platform flag is critical: without it, nodes get only devstorage.read_only scope and cannot pull from Artifact Registry.

Copygcloud container clusters create shipyard-prod --project=shipyard-254 --region=africa-south1 --release-channel=stable --cluster-version=latest --num-nodes=2 --machine-type=e2-standard-4 --enable-autoscaling --min-nodes=2 --max-nodes=6 --workload-pool=shipyard-254.svc.id.goog --scopes=cloud-platform

Connect kubectl

Copygcloud components install gke-gcloud-auth-plugin
gcloud container clusters get-credentials shipyard-prod --region=africa-south1 --project=shipyard-254
kubectl get nodes   # should show 6 nodes (2 per zone × 3 zones)

Create namespaces

Copykubectl create namespace shipyard-system
kubectl create namespace shipyard-infra

Step 3 — Artifact Registry

Copygcloud artifacts repositories create shipyard --repository-format=docker --location=africa-south1 --project=shipyard-254 --description="Shipyard platform images"

# Authenticate Docker
gcloud auth configure-docker africa-south1-docker.pkg.dev

Image URL: africa-south1-docker.pkg.dev/shipyard-254/shipyard/platform:<tag>

Step 4 — Build and Push the Platform Image

The same image runs all four processes (API + 3 workers). The k8s Deployment command: selects which one starts.

Option A — Google Cloud Build (recommended)

Builds on Google infrastructure, natively linux/amd64, pushes straight to Artifact Registry. Enable the API once, then use this for all future builds:

Copygcloud services enable cloudbuild.googleapis.com --project=shipyard-254
gcloud builds submit --tag africa-south1-docker.pkg.dev/shipyard-254/shipyard/platform:1.0.0 --project=shipyard-254 .

Option B — Local cross-platform build

Copydocker buildx build --platform linux/amd64 -t africa-south1-docker.pkg.dev/shipyard-254/shipyard/platform:1.0.0 --push .

Dockerfile (repo root)

CopyFROM node:22-alpine AS builder
RUN corepack enable pnpm
WORKDIR /app
COPY . .
RUN pnpm install --frozen-lockfile
RUN pnpm turbo build

FROM node:22-alpine
RUN apk add --no-cache git docker-cli
RUN corepack enable pnpm
WORKDIR /app
COPY --from=builder /app/package.json /app/pnpm-lock.yaml /app/pnpm-workspace.yaml /app/turbo.json ./
COPY --from=builder /app/node_modules ./node_modules
COPY --from=builder /app/packages ./packages
COPY --from=builder /app/apps/api ./apps/api
COPY --from=builder /app/apps/cli ./apps/cli
RUN pnpm install --frozen-lockfile --prod --ignore-scripts
CMD ["node", "apps/api/dist/index.js"]

Patch the build worker for Docker socket access

Edit infra/helm/templates/deployment-worker-build.yaml and add under volumeMounts and volumes:

Copy          volumeMounts:
            - name: build-workspace
              mountPath: {{ .Values.workers.build.workdir }}
            - name: docker-socket
              mountPath: /var/run/docker.sock
      volumes:
        - name: build-workspace
          emptyDir: {}
        - name: docker-socket
          hostPath:
            path: /var/run/docker.sock
            type: Socket

Step 5 — Install Infrastructure Dependencies

Add Helm repos

Copyhelm repo add traefik https://traefik.github.io/charts
helm repo add bitnami https://charts.bitnami.com/bitnami
helm repo add minio https://charts.min.io/
helm repo update

Traefik v3

Uses a values file (infra/helm/traefik-values.yaml) to avoid shell line-continuation issues. Do not add ports.websecure.tls — Traefik v3 chart schema rejects that key; TLS on websecure is enabled by default.

Create the Cloudflare API token

In the Cloudflare dashboard → My Profile → API Tokens → Create Token → Custom token:

• Permissions: Zone → DNS → Edit
• Zone Resources: Include → Specific zone → wake.co.ke

Store the token as a k8s secret before installing Traefik:

Copykubectl create secret generic traefik-cloudflare-token \
  --from-literal=CF_DNS_API_TOKEN=<your-token> \
  -n shipyard-infra

Copy# infra/helm/traefik-values.yaml
providers:
  kubernetesCRD:
    enabled: true
    allowCrossNamespace: true
  kubernetesIngress:
    enabled: true

certificatesResolvers:
  letsencrypt:
    acme:
      email: alberto@zaoshinani.com
      storage: /data/acme.json
      dnsChallenge:
        provider: cloudflare
        resolvers:
          - "1.1.1.1:53"
          - "8.8.8.8:53"

env:
  - name: CF_DNS_API_TOKEN
    valueFrom:
      secretKeyRef:
        name: traefik-cloudflare-token
        key: CF_DNS_API_TOKEN

persistence:
  enabled: true
  size: 128Mi

podSecurityContext:
  fsGroup: 65532
  fsGroupChangePolicy: "OnRootMismatch"

Copyhelm upgrade --install traefik traefik/traefik --namespace shipyard-infra -f infra/helm/traefik-values.yaml

PostgreSQL 16

Copyhelm upgrade --install postgres bitnami/postgresql --namespace shipyard-infra --set auth.username=shipyard --set auth.password=f2de63dbdda2af7c90c813999a32605e --set auth.database=shipyard

Redis 7

Copyhelm upgrade --install redis bitnami/redis --namespace shipyard-infra --set auth.password=78d00185c6a72eb62f715daba56ae34f --set architecture=standalone

MinIO

Must set explicit resource limits — the default chart memory request is 16 GiB which will not schedule on standard e2-standard-4 nodes.

Copyhelm upgrade --install minio minio/minio --namespace shipyard-infra --set rootUser=shipyard --set rootPassword=77fdc7516052eb7d883b747b65e49b73 --set mode=standalone --set persistence.size=20Gi --set resources.requests.memory=512Mi --set resources.requests.cpu=250m --set resources.limits.memory=2Gi --set resources.limits.cpu=1

Step 6 — Secrets

The secrets generated for this deployment:

Step 7 — Deploy Shipyard via Helm

Run database migrations

Migrations are SQL files in packages/db/migrations/. Pipe them directly into the postgres pod — no migration job image required:

Copycat packages/db/migrations/0000_past_joseph.sql \
    packages/db/migrations/0001_true_landau.sql \
    packages/db/migrations/0002_milky_jamie_braddock.sql \
    packages/db/migrations/0003_open_nehzno.sql \
    packages/db/migrations/0004_audit_events.sql \
    packages/db/migrations/0005_add_bitbucket_provider.sql \
  | sed 's/--> statement-breakpoint/;/g' \
  | kubectl exec -i -n shipyard-infra postgres-postgresql-0 \
    -- env PGPASSWORD=f2de63dbdda2af7c90c813999a32605e psql -U shipyard -d shipyard

Create the platform secret

Secrets are stored in a separate k8s Secret that Helm references via existingSecret — never committed to git:

Copykubectl create secret generic shipyard-secrets --namespace shipyard-system --from-literal=jwtSecret="97dc32a1cb5fa01e157f44b330dcf9a1a9410fd8a67fde0eb218b8e069718d0a" --from-literal=encryptionKek="3eeb918a1c26ea8b86d741602b914ba6c6dfaa827518a34248d3e98b84bde38e" --from-literal=databaseUrl="postgres://shipyard:f2de63dbdda2af7c90c813999a32605e@postgres-postgresql.shipyard-infra.svc.cluster.local:5432/shipyard" --from-literal=redisUrl="redis://:78d00185c6a72eb62f715daba56ae34f@redis-master.shipyard-infra.svc.cluster.local:6379"

Production values file

Copy# infra/helm/values.production.yaml
image:
  repository: africa-south1-docker.pkg.dev/shipyard-254/shipyard/platform
  tag: "1.1.0"
  pullPolicy: IfNotPresent

namespace:
  create: false
  name: shipyard-system

api:
  replicaCount: 1
  extraEnv:
    - name: MINIO_ENDPOINT
      value: "http://minio.shipyard-infra.svc.cluster.local:9000"
    - name: MINIO_ACCESS_KEY
      value: "shipyard"
    - name: MINIO_SECRET_KEY
      value: "77fdc7516052eb7d883b747b65e49b73"
    - name: MINIO_INTERNAL_URL
      value: "http://minio.shipyard-infra.svc.cluster.local:9000"
    - name: STATIC_STORAGE_ENABLED
      value: "true"
    - name: CONTAINER_BUILD_ENABLED
      value: "false"
    - name: HARBOR_REGISTRY
      value: "africa-south1-docker.pkg.dev"
    - name: HARBOR_PROJECT
      value: "shipyard-254/shipyard"

config:
  platformDomain: deploy.shipyard.wake.co.ke
  internalDomain: apps.shipyard.wake.co.ke
  corsOrigin: https://shipyard.wake.co.ke
  k8sEnabled: "true"
  logLevel: info

secrets:
  existingSecret: "shipyard-secrets"

ingress:
  enabled: true
  certResolver: letsencrypt
  entryPoints:
    - websecure
  api:
    hostname: api.shipyard.wake.co.ke
  dashboard:
    hostname: shipyard.wake.co.ke

Helm install

Copyhelm upgrade --install shipyard ./infra/helm --namespace shipyard-system -f infra/helm/values.production.yaml --wait --timeout=3m

Fix image pull — GKE node pool scope limitation

Create the pull secret (run in GCP Cloud Shell to use your user credentials — gcloud auth print-access-token returns a token with full Artifact Registry access):

Copy# Run in GCP Cloud Shell — single line, no wrapping
kubectl create secret docker-registry artifact-registry-key --docker-server=africa-south1-docker.pkg.dev --docker-username=oauth2accesstoken --docker-password="$(gcloud auth print-access-token)" --namespace=shipyard-system

Patch all deployments to use it:

Copyfor d in shipyard-api shipyard-worker-build shipyard-worker-cleanup shipyard-worker-deploy; do kubectl patch deployment $d -n shipyard-system -p '{"spec":{"template":{"spec":{"imagePullSecrets":[{"name":"artifact-registry-key"}]}}}}'; done

Verify

Copykubectl get pods -n shipyard-system

Step 8 — DNS

Get Traefik's external IP:

Copykubectl get svc traefik -n shipyard-infra

In your DNS provider (for wake.co.ke), add these records pointing to that IP:

Step 9 — First Run

Register the first user

Copycurl -X POST https://api.shipyard.wake.co.ke/api/v1/auth/register \
  -H 'Content-Type: application/json' \
  -d '{"name":"Your Name","email":"you@example.com","password":"your-password"}'

Log in with the CLI

The CLI stores tokens in ~/.shipyard/config.json. If the interactive prompt doesn't work (e.g. in scripts), write the file directly after calling the register endpoint above.

Copyship login --api-url https://api.shipyard.wake.co.ke

Create your first project and deploy

Copy# From inside a git repo
ship deploy --follow

Configure GitHub webhooks

In your GitHub repo → Settings → Webhooks → Add webhook:

• Payload URL: https://api.shipyard.wake.co.ke/api/v1/webhooks/github
• Content type: application/json
• Secret: the webhookSecret returned when you created the git source
• Events: Pushes + Pull requests

Step 10 — CI/CD Pipeline

Every push to main automatically builds, migrates, and deploys the platform. Run time is ~3m30s. Auth uses Workload Identity Federation — no service account keys are stored anywhere.

How the pipeline works

One-time GCP setup

Run these once on the GCP project. They are already done for shipyard-254.

1. Create the CI/CD service account

Copygcloud iam service-accounts create shipyard-cicd --display-name="Shipyard CI/CD" --project=shipyard-254

2. Create the Workload Identity Pool and GitHub provider

Copygcloud iam workload-identity-pools create github-actions --location=global --display-name="GitHub Actions" --project=shipyard-254

gcloud iam workload-identity-pools providers create-oidc github --location=global --workload-identity-pool=github-actions --issuer-uri="https://token.actions.githubusercontent.com" --attribute-mapping="google.subject=assertion.sub,attribute.repository=assertion.repository,attribute.ref=assertion.ref" --attribute-condition="assertion.repository=='Alisao/shipyard'" --project=shipyard-254

3. Bind the pool to the SA and grant IAM roles

Copy# Allow GitHub Actions to impersonate the SA
gcloud iam service-accounts add-iam-policy-binding shipyard-cicd@shipyard-254.iam.gserviceaccount.com --role=roles/iam.workloadIdentityUser --member="principalSet://iam.googleapis.com/projects/346003678070/locations/global/workloadIdentityPools/github-actions/attribute.repository/Alisao/shipyard" --project=shipyard-254

# GCP roles: Artifact Registry writer, GKE access, token exchange
for role in roles/artifactregistry.writer roles/container.developer roles/iam.serviceAccountTokenCreator; do
  gcloud projects add-iam-policy-binding shipyard-254 --member="serviceAccount:shipyard-cicd@shipyard-254.iam.gserviceaccount.com" --role="$role" --condition=None
done

4. Grant Kubernetes cluster-admin to the SA

The Helm chart manages ClusterRoles and ClusterRoleBindings, so the CI/CD SA needs cluster-admin within Kubernetes (separate from GCP IAM):

Copykubectl create clusterrolebinding shipyard-cicd-cluster-admin --clusterrole=cluster-admin --user=shipyard-cicd@shipyard-254.iam.gserviceaccount.com

5. Add the GitHub repository secret

In GitHub → Alisao/shipyard → Settings → Secrets and variables → Actions, add:

Or via the CLI: gh secret set PG_PASSWORD --repo Alisao/shipyard --body "<value>"

Workflow file

The full pipeline is at .github/workflows/deploy.yml. Key variables at the top of the file — update these if the project ID, region, cluster name, or repository changes:

Copyenv:
  PROJECT: shipyard-254
  REGION: africa-south1
  REGISTRY: africa-south1-docker.pkg.dev
  IMAGE: africa-south1-docker.pkg.dev/shipyard-254/shipyard/platform
  CLUSTER: shipyard-prod
  WIF_PROVIDER: projects/346003678070/locations/global/workloadIdentityPools/github-actions/providers/github
  SA: shipyard-cicd@shipyard-254.iam.gserviceaccount.com

Migration tracking

The runner maintains a schema_migrations table in the shipyard database. On the very first pipeline run against a pre-existing database, it seeds the table with all already-applied migration filenames (detected by checking whether the users table exists). From that point on, only files not yet in the table are applied. Adding a new migration is as simple as dropping a new *.sql file in packages/db/migrations/ — the next push picks it up automatically.

Known constraints

CLI Reference

Install: npm install -g @shipyard/cli. All commands require ship login first.

Environment Variable Targets

Env vars can be scoped to production (default), preview, or all (applies to both environments). Preview-scoped vars are only injected into PR/MR preview deployments.

API Reference

Base URL: https://api.shipyard.wake.co.ke/api/v1. Full OpenAPI docs at /api/docs. All endpoints except /auth/* and /webhooks/* require Authorization: Bearer <token>.

Auth

Deployments

Webhooks

Teams & Members

API Tokens

API tokens for CI/CD authentication. Tokens are prefixed ship_ and stored as SHA-256 hashes. The raw value is shown only once at creation.

Tokens can be team-scoped (access to all team projects) or project-scoped (single project only). Set projectId when creating for project scope.

Git Sources & OAuth

DNS Providers

Cloudflare API token management for automatic DNS record creation.

RBAC Permissions

Four role levels control access to team and project resources.

Permission Matrix

Commit Status Reporting

Build and deployment status is reported back to GitHub and Bitbucket as commit status checks. Developers see ✓ or ✗ directly in PRs without visiting the dashboard.

Status Flow

Implementation

Status updates are sent via provider APIs:

• GitHub: POST /repos/{owner}/{repo}/statuses/{sha}
• Bitbucket: POST /2.0/repositories/{fullName}/commit/{hash}/statuses/build

Requires a connected git source with valid OAuth token. Statuses are updated in real-time as deployments progress through the queue.

DNS Providers & Custom Domains

Teams can configure Cloudflare API tokens for automatic DNS management. When configured, adding a custom domain automatically creates the required DNS records.

Setup

In Team Settings → DNS Providers, add a Cloudflare API token with these permissions:

• Zone: DNS → Edit
• Zone Resources: Include → Specific zone → your domain

Automatic DNS Management

When a DNS provider is configured:

1. Adding a domain auto-creates the TXT verification record (_shipyard-verify.<domain>)
2. Upon verification, an A record pointing to PLATFORM_EXTERNAL_IP is created
3. Domain status flows: pending → provisioning → active

Required Environment Variables

Audit Events

Security-relevant actions are recorded in the audit_events table with immutable timestamps. Accessible to team admins and owners via Team Settings.

Recorded Actions

API

GET /teams/:id/audit-log — Returns paginated audit events (admin/owner only).

Buildpack Detection

Detection runs on every build. Rules are evaluated in priority order — first match wins. A shipyard.json at the repo root overrides detection entirely.

shipyard.json override

Copy{
  "type": "nextjs",
  "port": 3000,
  "healthCheckPath": "/api/health",
  "buildCommand": "npm run build:prod",
  "outputDirectory": ".next"
}

PHP webRoot

For php-composer projects, Shipyard auto-detects the NGINX document root:

• public/ directory present → NGINX serves from /var/www/html/public (Laravel / Symfony convention)
• No public/ directory → NGINX serves from /var/www/html (flat structure)

Override explicitly in shipyard.json or via project buildConfig:

Copy{
  "type": "php-composer",
  "webRoot": "web"
}

Operational Notes