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

Variable	Description	Example
`CLICKHOUSE_SERVER`	ClickHouse host:port	`clickhouse:9000`
`CLICKHOUSE_DATABASE`	ClickHouse database	`traceway`
`CLICKHOUSE_USERNAME`	ClickHouse username	`default`
`CLICKHOUSE_PASSWORD`	ClickHouse password	`password`
`CLICKHOUSE_TLS`	Enable TLS	`false`
`POSTGRES_HOST`	PostgreSQL host	`postgres`
`POSTGRES_PORT`	PostgreSQL port	`5432`
`POSTGRES_DATABASE`	PostgreSQL database	`traceway`
`POSTGRES_USERNAME`	PostgreSQL username	`traceway`
`POSTGRES_PASSWORD`	PostgreSQL password	`password`
`POSTGRES_SSLMODE`	PostgreSQL SSL mode	`disable`
`JWT_SECRET`	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.	`your-secret-here`
`APP_BASE_URL`	Public URL of your instance. Used for SDK setup instructions, email links, OAuth callback URLs, and the CLI/MCP OAuth issuer plus device-login verification URL. If unset, derived per-request from `Host` / `X-Forwarded-*`.	`https://traceway.example.com`
`STORAGE_TYPE`	Blob storage backend for source maps, session recordings, and AI traces: `local` (default) or `s3`. See Blob Storage for the S3 variables.	`local`
`STORAGE_PATH`	Folder for local blob storage. Defaults to `./storage`, which is `/app/storage` in this image. Mount a volume there. Ignored when `STORAGE_TYPE=s3`.	`/app/storage`
`SESSION_RECORDING_RETENTION_DAYS`	Days to keep on-disk session recordings under `STORAGE_PATH/recordings/`. Defaults to `30`. Worker runs hourly and on startup. `0` disables; no effect when `STORAGE_TYPE=s3`.	`30`

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

Variable	Description	Example
`GOOGLE_CLIENT_ID`	Google OAuth client ID. Setting both Google variables enables the Google button.	`...apps.googleusercontent.com`
`GOOGLE_CLIENT_SECRET`	Google OAuth client secret.	`GOCSPX-...`
`GITHUB_CLIENT_ID`	GitHub OAuth App client ID. Setting both GitHub variables enables the GitHub button.	`Ov23li...`
`GITHUB_CLIENT_SECRET`	GitHub OAuth App client secret.	`(40-char hex)`
`OAUTH_SESSION_SECRET`	Cookie signing secret for the OAuth round-trip. Falls back to `JWT_SECRET` when unset.	`(32+ random bytes)`

Access Points

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

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

Docker Compose SQLite