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

In development mode, all application services are accessible through nginx on port 80:
ServiceURLNotes
Frontendhttp://localhost/Workflow builder (via nginx)
Backend APIhttp://localhost/api/REST API (via nginx)
Analyticshttp://localhost/analytics/OpenSearch Dashboards (via nginx)
Temporal UIhttp://localhost:8081Workflow management
PostgreSQLhttp://localhost:5433Database
MinIOhttp://localhost:9000Object storage
MinIO Consolehttp://localhost:9001Credentials: minioadmin/minioadmin
Lokihttp://localhost:3100Logs
Individual service ports (5173, 3211, 5601) are available for debugging but should not be used in normal development. All traffic flows through nginx on port 80.

​
Analytics Stack (Optional)

ShipSec Studio includes an optional analytics stack powered by OpenSearch for indexing and visualizing workflow execution data.

​
Starting the Analytics Stack

The analytics services are included in the infrastructure docker-compose file: 
# Start infrastructure including OpenSearch
just infra up
This will start:
  • OpenSearch on port 9200 - Search and analytics engine
  • OpenSearch Dashboards on port 5601 - Visualization and query UI

​
Configuring Analytics

Add these environment variables to your backend and worker .env files: 
# Backend (.env)
OPENSEARCH_URL=http://localhost:9200
OPENSEARCH_USERNAME=admin
OPENSEARCH_PASSWORD=admin
OPENSEARCH_DASHBOARDS_URL=http://localhost/analytics

# Frontend (.env)
VITE_OPENSEARCH_DASHBOARDS_URL=http://localhost/analytics

​
Setting Up the Index Template

After starting OpenSearch, create the security findings index template: 
cd backend
bun run setup:opensearch
This creates the security-findings-* index template with proper mappings for workflow execution data.

​
Using Analytics

  1. Analytics Sink Component: Add the “Analytics Sink” component to your workflows to index output data
  2. Dashboards Link: Access OpenSearch Dashboards from the Studio sidebar
  3. Query API: Use the /api/analytics/query endpoint to query indexed data programmatically

​
Analytics Service Endpoints

ServiceURLNotes
OpenSearchhttp://localhost:9200Search engine API
OpenSearch Dashboardshttp://localhost/analytics/Visualization UI (via nginx)
The analytics stack is optional. If OpenSearch is not configured, the Analytics Sink component will gracefully skip indexing and log a warning.

​
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 (all via nginx on port 80):

​
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