Installation

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:

Service	URL	Notes
Frontend	http://localhost/	Workflow builder (via nginx)
Backend API	http://localhost/api/	REST API (via nginx)
Analytics	http://localhost/analytics/	OpenSearch Dashboards (via nginx)
Temporal UI	http://localhost:8081	Workflow management
PostgreSQL	http://localhost:5433	Database
MinIO	http://localhost:9000	Object storage
MinIO Console	http://localhost:9001	Credentials: `minioadmin/minioadmin`
Loki	http://localhost:3100	Logs

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

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

Analytics Service Endpoints

Service	URL	Notes
OpenSearch	http://localhost:9200	Search engine API
OpenSearch Dashboards	http://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

Check GitHub Issues for similar problems
Review logs with just dev logs for error details
Email support at support@shipsec.ai

Getting Started

Architecture

Components

Development

Prerequisites

Installation Steps

1. Clone & initialize

2. Configure environment variables

3. Start development environment

Service Endpoints

Analytics Stack (Optional)

Starting the Analytics Stack

Configuring Analytics

Setting Up the Index Template

Using Analytics

Analytics Service Endpoints

Production Deployment

Common Commands

Development

Production

Infrastructure

Utilities

Troubleshooting

macOS: Native module build errors

Services not starting

Database connection failed

PM2 processes failing

Frontend not loading

Temporal namespace missing

Clean rebuild

Manual Setup (Optional)

Infrastructure only

Applications only

Getting Help

​Prerequisites

​Installation Steps

​1. Clone & initialize

​2. Configure environment variables

​3. Start development environment

​Service Endpoints

​Analytics Stack (Optional)

​Starting the Analytics Stack

​Configuring Analytics

​Setting Up the Index Template

​Using Analytics

​Analytics Service Endpoints

​Production Deployment

​Common Commands

​Development

​Production

​Infrastructure

​Utilities

​Troubleshooting

​macOS: Native module build errors

​Services not starting

​Database connection failed

​PM2 processes failing

​Frontend not loading

​Temporal namespace missing

​Clean rebuild

​Manual Setup (Optional)

​Infrastructure only

​Applications only

​Getting Help

Prerequisites

Installation Steps

1. Clone & initialize

2. Configure environment variables

3. Start development environment

Service Endpoints

Analytics Stack (Optional)

Starting the Analytics Stack

Configuring Analytics

Setting Up the Index Template

Using Analytics

Analytics Service Endpoints

Production Deployment

Common Commands

Development

Production

Infrastructure

Utilities

Troubleshooting

macOS: Native module build errors

Services not starting

Database connection failed

PM2 processes failing

Frontend not loading

Temporal namespace missing

Clean rebuild

Manual Setup (Optional)

Infrastructure only

Applications only

Getting Help