Haloy

Deploy Traceway to your own server using Haloy (opens in a new tab), a CLI-based deployment tool. Haloy manages your containers, handles automatic SSL certificates, and is configured with a single YAML file.

Prerequisites

Install the Haloy CLI and configure a server by following the instructions at haloy.dev/docs (opens in a new tab).

Configuration

Create a haloy.yaml in the traceway project root. Replace haloy.tracewayapp.com with your configured Haloy server and traceway.yourdomain.com with the domain you want Traceway accessible at.

# haloy api endpoint
server: haloy.tracewayapp.com
 
targets:
  clickhouse:
    preset: database
    image:
      repository: clickhouse/clickhouse-server:24.8-alpine
    port: 9000
    env:
      - name: CLICKHOUSE_DB
        value: traceway
      - name: CLICKHOUSE_PASSWORD
        from:
          env: CLICKHOUSE_PASSWORD
    volumes:
      - clickhouse-data:/var/lib/clickhouse
 
  postgres:
    preset: database
    image:
      repository: postgres:17
    port: 5432
    env:
      - name: POSTGRES_USER
        value: traceway
      - name: POSTGRES_PASSWORD
        from:
          env: POSTGRES_PASSWORD # from .env
      - name: POSTGRES_DB
        value: traceway
    volumes:
      - postgres-data:/var/lib/postgresql/data
 
  traceway:
    preset: service
    image:
      repository: traceway/traceway:minimal
      build_config:
        dockerfile: ./Dockerfile.minimal
    domains:
      - domain: traceway.yourdomain.com # will automatically set up TLS
    port: 80
    env:
      - name: APP_BASE_URL
        value: https://traceway.yourdomain.com # match domain
      - name: CLICKHOUSE_SERVER
        value: "clickhouse:9000"
      - name: CLICKHOUSE_DATABASE
        value: traceway
      - name: CLICKHOUSE_USERNAME
        value: default
      - name: CLICKHOUSE_PASSWORD
        from:
          env: CLICKHOUSE_PASSWORD
      - name: CLICKHOUSE_TLS
        value: "false"
      - name: POSTGRES_HOST
        value: postgres
      - name: POSTGRES_PORT
        value: "5432"
      - name: POSTGRES_DATABASE
        value: traceway
      - name: POSTGRES_USERNAME
        value: traceway
      - name: POSTGRES_PASSWORD
        from:
          env: POSTGRES_PASSWORD
      - name: POSTGRES_SSLMODE
        value: disable
      - name: JWT_SECRET
        from:
          env: JWT_SECRET
      # Optional: SSO providers. Omit a pair to disable that button.
      # See /learn/sso for the full setup walkthrough.
      - name: GOOGLE_CLIENT_ID
        from:
          env: GOOGLE_CLIENT_ID
      - name: GOOGLE_CLIENT_SECRET
        from:
          env: GOOGLE_CLIENT_SECRET
      - name: GITHUB_CLIENT_ID
        from:
          env: GITHUB_CLIENT_ID
      - name: GITHUB_CLIENT_SECRET
        from:
          env: GITHUB_CLIENT_SECRET

Sensitive values use from: env: to read from environment variables on your machine at deploy time rather than being stored in the YAML file. Set them before deploying:

export CLICKHOUSE_PASSWORD=your-clickhouse-password
export POSTGRES_PASSWORD=your-postgres-password
export JWT_SECRET=your-jwt-secret-at-least-32-chars
 
# Optional, only when enabling SSO
export GOOGLE_CLIENT_ID=...
export GOOGLE_CLIENT_SECRET=...
export GITHUB_CLIENT_ID=...
export GITHUB_CLIENT_SECRET=...

Deployment

Deploy the database services first, then the Traceway application.

1. Deploy databases:

haloy deploy -t clickhouse,postgres

Wait for the databases to be ready before proceeding.

2. Deploy Traceway:

haloy deploy -t traceway

After deploying, open https://traceway.yourdomain.com/register to create your first account.

Connecting Your SDK

Point your SDK's connection string at your Traceway domain:

<project_token>@https://traceway.yourdomain.com/api/report

Environment Variables

ClickHouse target

Variable	Default	Description
`CLICKHOUSE_DB`	`traceway`	Database to create on startup
`CLICKHOUSE_PASSWORD`	(from env)	ClickHouse password

PostgreSQL target

Variable	Default	Description
`POSTGRES_USER`	`traceway`	PostgreSQL username
`POSTGRES_PASSWORD`	(from env)	PostgreSQL password
`POSTGRES_DB`	`traceway`	PostgreSQL database name

Traceway target

Variable	Default	Description
`APP_BASE_URL`	`https://traceway.yourdomain.com`	Public URL of the Traceway instance. Also the CLI/MCP OAuth issuer and device-login verification URL. See CLI Authentication.
`CLICKHOUSE_SERVER`	`clickhouse:9000`	ClickHouse host:port
`CLICKHOUSE_DATABASE`	`traceway`	ClickHouse database name
`CLICKHOUSE_USERNAME`	`default`	ClickHouse username
`CLICKHOUSE_PASSWORD`	(from env)	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`	(from env)	PostgreSQL password
`POSTGRES_SSLMODE`	`disable`	PostgreSQL SSL mode
`JWT_SECRET`	(from env)	Signs all authentication tokens (dashboard sessions and CLI/MCP device logins). Use a strong, unique secret of at least 32 chars; keep it stable. See CLI Authentication.
`GOOGLE_CLIENT_ID`	(unset)	Optional. Google OAuth client ID. Setting both Google variables enables the Continue with Google button. See the SSO guide.
`GOOGLE_CLIENT_SECRET`	(unset)	Optional. Google OAuth client secret.
`GITHUB_CLIENT_ID`	(unset)	Optional. GitHub OAuth App client ID. Setting both GitHub variables enables the Continue with GitHub button.
`GITHUB_CLIENT_SECRET`	(unset)	Optional. GitHub OAuth App client secret.
`OAUTH_SESSION_SECRET`	(falls back to `JWT_SECRET`)	Optional. Cookie signing secret for the OAuth round-trip.
`STORAGE_TYPE`	`local`	Blob storage backend for source maps, session recordings, and AI traces: `local` or `s3`. See Blob Storage for the S3 variables and persistence notes.
`STORAGE_PATH`	`./storage`	Folder for local blob storage. Point it at a persistent mount, or use `STORAGE_TYPE=s3`. Ignored when `STORAGE_TYPE=s3`.
`SESSION_RECORDING_RETENTION_DAYS`	`30`	Optional. Days to keep on-disk session recordings under `STORAGE_PATH/recordings/`. Worker runs hourly and on startup. `0` disables; no effect when `STORAGE_TYPE=s3`.

When configuring providers, set the callback URL on the provider side to https://traceway.yourdomain.com/api/auth/callback/{google|github}.

Useful Commands

# Deploy a specific target
haloy deploy -t traceway
 
# Check status of a specific target
haloy status -t traceway
 
# Check status of all targets
haloy status -a
 
# Validate your config
haloy validate-config

Blob Storage Capacity & Self-Monitoring