Self-hosting Tracelane with Docker Compose

​

Prerequisites

​

Quick start — local development only

git clone https://github.com/tracelane/tracelane
cd tracelane

# Starts Postgres, ClickHouse, NATS, Grafana on local ports
docker compose -f infra/dev/docker-compose.yml up -d

# Apply migrations
./scripts/apply-migration-pg.sh

# In three separate terminals:
cargo run -p gateway --release
cargo run -p ingest --release
pnpm --filter @tracelanedev/web dev

​

Production — two topologies

​

A. Single-tenant self-host — the shipped compose

# On your host, from the repo root of your deployment checkout:
cp infra/self-host/.env.example infra/self-host/.env   # set TRACELANE_MASTER_KEY + a provider key
docker compose -f infra/self-host/docker-compose.yml up -d --build

​

B. Multi-tenant — running the hosted topology yourself

​

Environment variables — multi-tenant topology

​

Required (production)

​

Optional

​

Apply migrations

# Postgres — tenant metadata, API keys, CMK keys, billing, and the CANONICAL audit
# ledger (audit_log_rows, audit_anchor_records) when the gateway has a Postgres URL
./scripts/apply-migration-pg.sh

# ClickHouse — spans, trace_summaries, audit_log (the ledger's read copy — or its only
# home when you run without Postgres) (auto-applied by Docker Compose
# from infra/dev/clickhouse/schema.sql at container init).
# Non-compose install — apply schema + migrations directly:
clickhouse-client < infra/dev/clickhouse/schema.sql
for m in infra/dev/clickhouse/migrations/*.sql; do clickhouse-client < "$m"; done

​

Configure WorkOS

1. Create a WorkOS application at workos.com.
2. Set the Redirect URI to https://app.<your-domain>/auth/callback.
3. Configure Connections for the providers you want to support.
4. Add a Webhook at https://gateway.<your-domain>/v1/webhooks/workos, subscribed to: organization.created, user.created, dsync.user.created.
5. Copy the webhook secret to WORKOS_WEBHOOK_SECRET.
6. Copy Client ID and API Key to WORKOS_CLIENT_ID and WORKOS_API_KEY.

​

Configure Polar

1. Create Products with these lookup_key values (set on each product’s product_metadata) — one monthly base product per paid plan. Annual billing is not offered yet; when it is, it is a separate base-plus-usage pair per plan, described on the pricing page.

   lookup_key	Plan	Monthly
   builder_v1	Builder	$29/mo
   team_v1	Team	$229/mo
   business_v1	Business	$799/mo
   enterprise_v1	Enterprise	from $2,499/mo (custom)

2. Create six Meters with event_name:
   • ingest_gb, hot_gb_month, series, scan_units, cold_gb_month, eval_runs
3. Create a Webhook at https://<your-dashboard-domain>/api/webhooks/polar, subscribed to: subscription.created, subscription.updated, subscription.active, subscription.canceled, order.created, order.paid.
4. Issue an Organization Access Token with read/write scope for products, subscriptions, meter events, and customer-portal sessions.
5. Set POLAR_ACCESS_TOKEN, POLAR_WEBHOOK_SECRET, and POLAR_EXPECTED_ORGANIZATION_ID.

​

Generate audit signing key

# Generate Ed25519 signing key for audit signing + Rekor anchoring
openssl genpkey -algorithm ed25519 -out rekor-signing.pem

# Export as PKCS#8 DER base64
openssl pkcs8 -topk8 -nocrypt -in rekor-signing.pem -outform DER | base64 -w 0
# Paste the output into TRACELANE_REKOR_SIGNING_KEY

cargo test -p gateway --bin gateway print_signing_key -- --ignored --nocapture

​

Verify the stack

# Gateway health
curl http://localhost:8080/health
# {"status":"ok","service":"tracelane-gateway"}

# First trace
curl -X POST http://localhost:8080/v1/chat/completions \
  -H "Authorization: Bearer tlane_..." \
  -H "Content-Type: application/json" \
  -d '{"model":"claude-sonnet-4-6","messages":[{"role":"user","content":"ping"}]}'

# Confirm it landed in ClickHouse
curl "http://localhost:8080/v1/audit/export?since=$(date -u +%Y-%m-%dT%H:%M:%SZ -d '5 minutes ago')" \
  -H "Authorization: Bearer tlane_..." | head -3

​

Production checklist

• TRACELANE_REKOR_SIGNING_KEY generated and stored; TRACELANE_REKOR_URL set if batches are to be anchored (unset, they are signed locally and never anchored)
• ClickHouse pointing at production storage (not dev compose)
• TLS termination at reverse proxy (Caddy, Nginx, or Cloudflare Tunnel)
• OSV-Scanner + Grype clean on deployed commit
• Conformance suites green: pnpm --filter @tracelanedev/audit-verifier test

• TRACELANE_MASTER_KEY set (32 random bytes, stored in secrets manager) — it is the bearer token every client sends
• No POSTGRES_URL / PGHOST / WORKOS_CLIENT_ID / TRACELANE_SPIRE_SOCKET in the environment — the gateway and ingest refuse to start with one

• TRACELANE_BYOK_MASTER_KEY set and rotated (32 random bytes, stored in secrets manager)
• Confirm POSTGRES_URL is set — a release build has no auth fallback and refuses every API key without it
• Postgres pointing at production branch (Neon or RDS)
• WorkOS webhook verified (send a test event, confirm tenant is provisioned)
• Polar products + meters + webhook configured and verified

​

Upgrading

git pull origin main
cargo build --release --workspace
pnpm install && pnpm build

# Run migrations (idempotent)
./scripts/apply-migration-pg.sh
# ClickHouse schema + migrations (non-compose installs):
clickhouse-client < infra/dev/clickhouse/schema.sql
for m in infra/dev/clickhouse/migrations/*.sql; do clickhouse-client < "$m"; done

# Rolling restart: ingest first, then gateway, then dashboard

​

Related

• Architecture
• BYOK
• Onboarding
• API reference