Skip to main content

​
Prerequisites

  • Docker Desktop with ≥8 GB RAM
  • Bun runtime
  • just command runner
  • Open ports: 5433, 7233, 8081, 9000, 9001, 3100

​
Installation Steps

​
1. Clone & initialize

git clone https://github.com/shipsecai/studio.git
cd studio
just init
macOS users: If you see native module errors, run:
export SDKROOT=$(xcrun --show-sdk-path)
bun install
The just init command automatically:
  • Installs project dependencies with Bun
  • Creates environment files from examples (backend/.env, worker/.env, frontend/.env)

​
2. Configure environment variables

Edit the generated .env files as needed: 
# Edit environment files
nano backend/.env
nano worker/.env
nano frontend/.env

​
3. Start development environment

just dev
The just dev command automatically:
  • Checks that environment files exist
  • Starts Docker infrastructure (Postgres, Temporal, MinIO, Loki)
  • Waits for services to be ready
  • Runs database migrations
  • Starts backend, worker, and frontend with hot-reload

​
Service Endpoints

ServiceURLNotes
Frontendhttp://localhost:5173Workflow builder
Backend APIhttp://localhost:3211REST API
Temporal UIhttp://localhost:8081Workflow management
PostgreSQLhttp://localhost:5433Database
MinIOhttp://localhost:9000Object storage
MinIO Consolehttp://localhost:9001Credentials: minioadmin/minioadmin
Lokihttp://localhost:3100Logs

​
Production Deployment

For production, use the Docker-based deployment: 
# Start production environment with cached images
just prod

# Or build and start
just prod build
Production endpoints:

​
Common Commands

​
Development

just dev          # Start development environment
just dev stop     # Stop everything
just dev logs     # View application logs
just dev status   # Check service status
just dev clean    # Stop and remove all data

​
Production

just prod          # Start with cached images
just prod build    # Rebuild and start
just prod stop     # Stop production
just prod logs     # View production logs
just prod status   # Check production status
just prod clean    # Remove all data

​
Infrastructure

just infra up     # Start infrastructure only
just infra down   # Stop infrastructure
just infra logs   # View infrastructure logs
just infra clean  # Remove infrastructure data

​
Utilities

just status       # Show status of all services
just db-reset     # Reset database (drops all data)
just build        # Build images only

​
Troubleshooting

​
macOS: Native module build errors

export SDKROOT=$(xcrun --show-sdk-path)
bun install

​
Services not starting

# Check status
just dev status

# Restart everything
just dev stop
just dev

​
Database connection failed

# Run migrations manually
bun run migrate

# Check database logs
just infra logs

​
PM2 processes failing

# Check environment files
ls -la */.env

# Restart everything
just dev stop
just dev

# Check logs
just dev logs

​
Frontend not loading

# Check if dev server is running
just dev status

# Start manually if needed
bun --cwd frontend dev

​
Temporal namespace missing

docker compose -p shipsec --profile setup up -d

​
Clean rebuild

just dev stop
just infra clean
just infra up
bun run migrate
just dev

​
Manual Setup (Optional)

If you need more control over the setup process:

​
Infrastructure only

just infra up
just status
just infra logs

​
Applications only

pm2 start pm2.config.cjs
pm2 status
pm2 logs

​
Getting Help