> ## Documentation Index
> Fetch the complete documentation index at: https://docs.shipsec.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Installation

> Self-host ShipSec Studio on your infrastructure

## Prerequisites

* Docker Desktop with ≥8 GB RAM
* [Bun](https://bun.sh) runtime
* [just](https://github.com/casey/just) command runner
* Open ports: `5433`, `7233`, `8081`, `9000`, `9001`, `3100`

***

## Installation Steps

### 1. Clone & initialize

```bash theme={null}
git clone https://github.com/shipsecai/studio.git
cd studio
just init
```

<Note>
  **macOS users:** If you see native module errors, run:

  ```bash theme={null}
  export SDKROOT=$(xcrun --show-sdk-path)
  bun install
  ```
</Note>

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:

```bash theme={null}
# Edit environment files
nano backend/.env
nano worker/.env
nano frontend/.env
```

### 3. Start development environment

```bash theme={null}
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/](http://localhost/)                     | Workflow builder (via nginx)         |
| Backend API   | [http://localhost/api/](http://localhost/api/)             | REST API (via nginx)                 |
| Analytics     | [http://localhost/analytics/](http://localhost/analytics/) | OpenSearch Dashboards (via nginx)    |
| Temporal UI   | [http://localhost:8081](http://localhost:8081)             | Workflow management                  |
| PostgreSQL    | [http://localhost:5433](http://localhost:5433)             | Database                             |
| MinIO         | [http://localhost:9000](http://localhost:9000)             | Object storage                       |
| MinIO Console | [http://localhost:9001](http://localhost:9001)             | Credentials: `minioadmin/minioadmin` |
| Loki          | [http://localhost:3100](http://localhost:3100)             | Logs                                 |

<Note>
  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.
</Note>

***

## 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:

```bash theme={null}
# 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:

```bash theme={null}
# 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:

```bash theme={null}
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

| Service               | URL                                                        | Notes                        |
| --------------------- | ---------------------------------------------------------- | ---------------------------- |
| OpenSearch            | [http://localhost:9200](http://localhost:9200)             | Search engine API            |
| OpenSearch Dashboards | [http://localhost/analytics/](http://localhost/analytics/) | Visualization UI (via nginx) |

<Note>
  The analytics stack is optional. If OpenSearch is not configured, the Analytics Sink component will gracefully skip indexing and log a warning.
</Note>

***

## Production Deployment

For production, use the Docker-based deployment:

```bash theme={null}
# Start production environment with cached images
just prod

# Or build and start
just prod build
```

Production endpoints (all via nginx on port 80):

* Frontend: [http://localhost/](http://localhost/)
* Backend API: [http://localhost/api/](http://localhost/api/)
* Analytics: [http://localhost/analytics/](http://localhost/analytics/)
* Temporal UI: [http://localhost:8081](http://localhost:8081)

***

## Common Commands

### Development

```bash theme={null}
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

```bash theme={null}
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

```bash theme={null}
just infra up     # Start infrastructure only
just infra down   # Stop infrastructure
just infra logs   # View infrastructure logs
just infra clean  # Remove infrastructure data
```

### Utilities

```bash theme={null}
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

```bash theme={null}
export SDKROOT=$(xcrun --show-sdk-path)
bun install
```

### Services not starting

```bash theme={null}
# Check status
just dev status

# Restart everything
just dev stop
just dev
```

### Database connection failed

```bash theme={null}
# Run migrations manually
bun run migrate

# Check database logs
just infra logs
```

### PM2 processes failing

```bash theme={null}
# Check environment files
ls -la */.env

# Restart everything
just dev stop
just dev

# Check logs
just dev logs
```

### Frontend not loading

```bash theme={null}
# Check if dev server is running
just dev status

# Start manually if needed
bun --cwd frontend dev
```

### Temporal namespace missing

```bash theme={null}
docker compose -p shipsec --profile setup up -d
```

### Clean rebuild

```bash theme={null}
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

```bash theme={null}
just infra up
just status
just infra logs
```

### Applications only

```bash theme={null}
pm2 start pm2.config.cjs
pm2 status
pm2 logs
```

***

## Getting Help

* Check [GitHub Issues](https://github.com/shipsecai/studio/issues) for similar problems
* Review logs with `just dev logs` for error details
* Email support at [support@shipsec.ai](mailto:support@shipsec.ai)