Skip to content

The only tool you need to know what is happening and how to fix it.

8.4 KB
Raw Blame
# Docker Compose

Runs Traceway, ClickHouse, and PostgreSQL as separate services using the [Minimal Container](/server/minimal) image.

## Quick Start

No build required. Use the pre-built image from GitHub Container Registry with this `docker-compose.yml`:

```yaml
services:
  traceway:
    image: ghcr.io/tracewayapp/traceway:minimal
    ports:
      - "80:80"
    environment:
      CLICKHOUSE_SERVER: "clickhouse:9000"
      CLICKHOUSE_DATABASE: "traceway"
      CLICKHOUSE_USERNAME: "default"
      CLICKHOUSE_PASSWORD: clickhouse
      CLICKHOUSE_TLS: "false"
      POSTGRES_HOST: "postgres"
      POSTGRES_PORT: "5432"
      POSTGRES_DATABASE: "traceway"
      POSTGRES_USERNAME: "traceway"
      POSTGRES_PASSWORD: traceway
      POSTGRES_SSLMODE: "disable"
      JWT_SECRET: change-this-to-a-secure-secret-at-least-32-chars
    volumes:
      - traceway-storage:/app/storage
    depends_on:
      clickhouse:
        condition: service_healthy
      postgres:
        condition: service_healthy
    restart: unless-stopped

  clickhouse:
    image: clickhouse/clickhouse-server:24.8-alpine
    environment:
      CLICKHOUSE_DB: traceway
      CLICKHOUSE_PASSWORD: clickhouse
    volumes:
      - clickhouse-data:/var/lib/clickhouse
    healthcheck:
      test: ["CMD", "clickhouse-client", "--password", "clickhouse", "--query", "SELECT 1"]
      interval: 5s
      timeout: 3s
      start_period: 10s
      retries: 10
    restart: unless-stopped

  postgres:
    image: postgres:17
    environment:
      POSTGRES_USER: traceway
      POSTGRES_PASSWORD: traceway
      POSTGRES_DB: traceway
    volumes:
      - postgres-data:/var/lib/postgresql/data
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U traceway"]
      interval: 5s
      timeout: 3s
      start_period: 10s
      retries: 10
    restart: unless-stopped

volumes:
  clickhouse-data:
  postgres-data:
  traceway-storage:
```

```bash
docker compose up -d
```

After starting, open `http://localhost/register` to create your first account.

The `traceway-storage` volume holds [blob storage](/server/storage): uploaded source maps, session recordings, and AI traces. Without it those files are lost when the container is recreated. To use S3 instead of a volume, see [Blob Storage](/server/storage).

The `docker-compose.yml` in the repository root builds from source instead. Use that if you are actively developing Traceway or need to run a modified build (`docker compose up --build`).

## Configuration

Edit the environment variables in your compose file as needed:

| Variable | Default | Description |
|----------|---------|-------------|
| `CLICKHOUSE_SERVER` | `clickhouse:9000` | ClickHouse host:port |
| `CLICKHOUSE_DATABASE` | `traceway` | ClickHouse database name |
| `CLICKHOUSE_USERNAME` | `default` | ClickHouse username |
| `CLICKHOUSE_PASSWORD` | `clickhouse` | ClickHouse password |
| `CLICKHOUSE_TLS` | `false` | Enable TLS for ClickHouse |
| `POSTGRES_HOST` | `postgres` | PostgreSQL host |
| `POSTGRES_PORT` | `5432` | PostgreSQL port |
| `POSTGRES_DATABASE` | `traceway` | PostgreSQL database name |
| `POSTGRES_USERNAME` | `traceway` | PostgreSQL username |
| `POSTGRES_PASSWORD` | `traceway` | PostgreSQL password |
| `POSTGRES_SSLMODE` | `disable` | PostgreSQL SSL mode |
| `JWT_SECRET` | `change-this-to-a-secure-secret-at-least-32-chars` | Signs all authentication tokens (dashboard sessions and CLI/MCP device logins). Replace the placeholder with a strong, unique secret of at least 32 chars (`openssl rand -hex 32`) and keep it stable. See [CLI Authentication](/learn/cli-auth#set-a-strong-jwt_secret). |
| `APP_BASE_URL` | *(none)* | Public URL of your Traceway instance (e.g. `https://traceway.example.com`). Used for SDK setup instructions, email links, deep links in notifications, OAuth callback URLs, and the CLI/MCP OAuth issuer plus device-login verification URL. If unset, the device-auth and `/.well-known` endpoints derive it per-request from the `Host` / `X-Forwarded-*` headers; set it explicitly behind a proxy that rewrites `Host`. See [CLI Authentication](/learn/cli-auth). |
| `TRUSTED_PROXIES` | *(loopback)* | Comma-separated CIDRs of the proxies in front of Traceway whose `X-Forwarded-For` / `X-Real-IP` is trusted for the real client IP. Every per-IP rate limit keys on it, and `/api/report` stores it as each session's `client.ip`. Unset trusts loopback only, so a proxy container on a Docker network or an in-cluster ingress has to be listed before its header counts. A value replaces the default, so list every hop between the client and this server, not just the outermost one: naming only a CDN leaves a private ingress untrusted and turns `X-Forwarded-For` off entirely. `*` trusts every peer and lets clients spoof their address. Until the proxy is listed, every visitor shares one rate-limit bucket keyed on the proxy, and the server logs a warning the first time it sees a forwarding header from a peer it does not trust. |
| `TRUSTED_PROXY_HEADER` | *(none)* | A header taken as the client IP on every request, ahead of `TRUSTED_PROXIES`: `X-Real-IP` behind ingress-nginx, `CF-Connecting-IP` behind Cloudflare. Only safe when every request provably passes through a proxy that overwrites the header; a directly reachable backend lets clients set it freely. |
| `REPORT_MAX_BODY_MB` | `64` | Cap on the decompressed `/api/report` and `/api/profiles/ingest` body in megabytes. Gzip does not raise it. A body over the cap answers `413`. |
| `INGEST_MAX_CONCURRENT` | *(2 x CPU cores, min 4)* | Telemetry ingest requests processed at once (`/api/report`, `/api/profiles/ingest`, `/api/otel/*`). Excess requests wait up to `INGEST_ADMISSION_WAIT_SECONDS` (default 5) and then get `503` with `Retry-After`; past a bounded waiting room (four times the capacity, at least 16) they are turned away immediately. Each admitted request can hold a decoded body, so on a memory-capped container size this from the memory limit rather than the CPU count. |
| `UPLOAD_MAX_CONCURRENT` | `4` | Source map and symbol uploads processed at once. Each holds a whole file in memory while it is parsed. Excess uploads wait 30 seconds and then get `503`. Separate from the ingest pool so a CI burst cannot starve telemetry. |
| `STORAGE_TYPE` | `local` | Blob storage backend for source maps, session recordings, and AI traces: `local` or `s3`. See [Blob Storage](/server/storage) for the S3 variables. |
| `STORAGE_PATH` | `./storage` | Folder for local blob storage, `/app/storage` in the minimal image. Mount a volume there. Ignored when `STORAGE_TYPE=s3`. |
| `SESSION_RECORDING_RETENTION_DAYS` | `30` | Days to keep session recording files on disk under `STORAGE_PATH/recordings/`. A worker deletes older files hourly and on startup. No effect when `STORAGE_TYPE=s3`. Set to `0` to disable. |

> ClickHouse table TTLs (`metric_points`, `log_records`, etc.) are managed at the schema level; this stack does not run the SQLite retention worker.

To run several backend containers against this stack, see [Running more than one instance](/server/minimal#running-more-than-one-instance): the minimal image is built for that shape, and the databases in this compose file are what the instances share.

## SSO (optional)

Adds **Continue with Google** / **Continue with GitHub** buttons to the login and register pages. See the [SSO guide](/learn/sso) for the full provider setup walkthrough.

When configuring providers, set the callback URL on the provider side to `<APP_BASE_URL>/api/auth/callback/{google|github}`.

| Variable | Default | Description |
|----------|---------|-------------|
| `GOOGLE_CLIENT_ID` | *(unset)* | Google OAuth client ID. Setting both Google variables enables the Google button. |
| `GOOGLE_CLIENT_SECRET` | *(unset)* | Google OAuth client secret. |
| `GITHUB_CLIENT_ID` | *(unset)* | GitHub OAuth App client ID. Setting both GitHub variables enables the GitHub button. |
| `GITHUB_CLIENT_SECRET` | *(unset)* | GitHub OAuth App client secret. |
| `OAUTH_SESSION_SECRET` | *(falls back to `JWT_SECRET`)* | Cookie signing secret for the OAuth round-trip. Override to rotate independently of `JWT_SECRET`. |

## Access Points

| URL | Description |
|-----|-------------|
| `http://localhost/` | Frontend dashboard |
| `http://localhost/api/*` | Backend API |
| `http://localhost/health` | Health check |

## Useful Commands

```bash
# View logs for all services
docker compose logs -f

# View logs for a specific service
docker compose logs -f traceway

# Stop all services
docker compose down

# Stop and remove all data
docker compose down -v
```