Shipyard

A self-hosted deployment control plane for static sites. Shipyard clones GitHub repos, runs builds in isolated Docker containers, uploads output to Garage (S3-compatible storage), and routes traffic via Caddy.

Quick Start

cp .env.example .env
docker compose up --build

Service	Port
Web (Vite dev)	http://localhost:5173
API	http://localhost:3000
Postgres	localhost:5432
Redis	localhost:6379
Garage S3	http://localhost:3900
Caddy	http://localhost:80

Architecture

┌──────────┐ ┌──────────┐ ┌──────────┐
│ Web │────→│ API │────→│ Worker │
│ (React) │ │ (Express)│ │ (BullMQ) │
└──────────┘ └────┬─────┘ └────┬─────┘
│ │
┌──────┴────────────────┴───────┐
│ │
┌────┴─────┐ ┌────────┐ ┌──────┴──────┐
│ Postgres │ │ Redis │ │ Garage (S3) │
└──────────┘ └────────┘ └─────────────┘
│
┌────┴────┐
│ Caddy │
└─────────┘

• API — Express.js REST API. GitHub OAuth, session management, CRUD for apps/deployments.
• Worker — Background job processor. Pulls from BullMQ, runs builds in Docker, uploads to Garage.
• Web — React SPA served by Vite (dev) or nginx (production).
• Garage — Self-hosted S3-compatible object storage.
• Caddy — Reverse proxy with auto-HTTPS. Routes *.yourdomain.com to Garage.

Development

Hot Reload

Service	Mechanism
API	tsx watch — restarts on .ts changes
Worker	tsx watch — restarts on .ts changes
Web	Vite HMR — instant updates for .tsx/.css

Commands

docker compose up # Start all services (dev)
docker compose up --build # Rebuild and start
docker compose down # Stop all services
docker compose logs -f api # Tail API logs
pnpm db:generate # Generate Drizzle migrations
pnpm db:push # Push schema to database

Project Structure

├── packages/
│ ├── api/ # Express REST API
│ ├── worker/ # BullMQ build processor
│ ├── web/ # React SPA
│ └── shared/ # Drizzle schema, types, validators
├── infra/
│ ├── caddy/ # Caddy configuration
│ └── garage.toml # Garage S3 configuration
├── docs/
│ ├── adr/ # Architecture Decision Records
│ └── agents/ # Agent skill configuration
├── CONTEXT.md # Domain glossary
├── PRD.md # Product requirements
└── docker-compose.* # Docker Compose files

Production

Production uses multi-stage builds (TypeScript compiled, slim runtime image):

docker compose -f docker-compose.yaml up -d --build

The docker-compose.override.yaml is auto-loaded for development. Use -f docker-compose.yaml to skip dev overrides.

Tech Stack

• Runtime: Node.js 22 (Alpine)
• API: Express.js + Drizzle ORM + Zod validation
• Queue: BullMQ on Redis 7
• Database: PostgreSQL 16
• Storage: Garage (S3-compatible)
• Proxy: Caddy 2
• Frontend: React + Vite
• Monorepo: pnpm workspaces + Turborepo