Minimal Container

Lightweight Alpine image (~20-30MB) containing only the Go backend with the embedded frontend. Requires external ClickHouse and PostgreSQL instances.

Quick Start

Pull the pre-built image and run it pointing at your databases:

docker pull ghcr.io/tracewayapp/traceway:minimal
 
docker run -d --name traceway \
  -p 80:80 \
  -v traceway-storage:/app/storage \
  -e CLICKHOUSE_SERVER="clickhouse-host:9000" \
  -e CLICKHOUSE_DATABASE="traceway" \
  -e CLICKHOUSE_USERNAME="default" \
  -e CLICKHOUSE_PASSWORD="your-password" \
  -e POSTGRES_HOST="postgres-host" \
  -e POSTGRES_PORT="5432" \
  -e POSTGRES_DATABASE="traceway" \
  -e POSTGRES_USERNAME="traceway" \
  -e POSTGRES_PASSWORD="your-password" \
  -e POSTGRES_SSLMODE="disable" \
  -e JWT_SECRET="your-jwt-secret-min-32-characters-long" \
  -e APP_BASE_URL="https://traceway.example.com" \
  ghcr.io/tracewayapp/traceway:minimal

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

The traceway-storage volume holds blob 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.

Build from Source

Only needed if you want to run a custom or modified build:

docker build -f Dockerfile.minimal -t traceway:minimal .

Then use traceway:minimal instead of ghcr.io/tracewayapp/traceway:minimal in the command above.

Required Environment Variables

Running more than one instance

This image is the only one that supports several backend instances behind a load balancer, because everything the instances have to agree on lives in PostgreSQL and ClickHouse:

• Project tokens. Each instance keeps the project list in memory to validate SDK tokens. Creating, updating or deleting a project, or rotating a source map token, sends a PostgreSQL NOTIFY on the project_cache_changed channel inside the write transaction, and every instance listening on that channel reloads the list. An instance that lost its database connection reloads the list as soon as the connection is back, so a change made while it was disconnected is not missed.
• Background workers. The notification outbox, the on-call escalator, the synthetics scheduler and the one-time dashboards backfill take a PostgreSQL advisory lock per tick, so only one instance drains the queue or pages someone even though every instance runs the workers.

What the deployment needs:

• Every instance points at the same PostgreSQL and ClickHouse and carries the same JWT_SECRET, so a session issued by one instance is valid on all of them.
• STORAGE_TYPE=s3. With local storage, a source map uploaded through one instance exists only on that instance's disk. See Blob Storage.
• TRUSTED_PROXIES lists the load balancer. Otherwise every instance sees the balancer's address as the client and all visitors share one rate-limit bucket.
• Migrations run at startup. Roll instances out one at a time so a single instance applies them before the others start.

Two caches stay per instance: the source map artifact cache and the symbolicator's negative cache, which retries a failed artifact within at most 15 minutes on the instances that did not receive the upload. See Symbolicator performance.

The SQLite and DuckDB images are single-instance by design: their databases are local files, and their project cache has no way to learn about a write made by another process. The All-in-One image bundles both databases inside the container, so it is single-instance as well. Run exactly one container of those images per data volume.

SSO (optional)

Adds Continue with Google / Continue with GitHub buttons to the login and register pages. See the SSO guide 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}.

Access Points

Useful Commands

# View logs
docker logs traceway
docker logs -f traceway
 
# Enter container shell
docker exec -it traceway sh
 
# Health check
curl http://localhost/health
 
# Stop and remove
docker stop traceway && docker rm traceway