Skip to content

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

9.2 KB
Raw Blame
# Haloy

Deploy Traceway to your own server using [Haloy](https://haloy.dev), 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](https://haloy.dev/docs).

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

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

```bash
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:**

```bash
haloy deploy -t clickhouse,postgres
```

Wait for the databases to be ready before proceeding.

**2. Deploy Traceway:**

```bash
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 what the deep links in notifications are built from, and the CLI/MCP OAuth issuer and device-login verification URL. 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. Haloy fronts the app with its own proxy, so list the range that proxy connects from (and your CDN's, if any). |
| `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. |
| `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](/learn/cli-auth#set-a-strong-jwt_secret). |
| `GOOGLE_CLIENT_ID` | *(unset)* | Optional. Google OAuth client ID. Setting both Google variables enables the **Continue with Google** button. See the [SSO guide](/learn/sso). |
| `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](/server/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

```bash
# 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
```