SQLite

Smallest possible Traceway deployment: a single Alpine container that uses SQLite for both the main database and telemetry, with the frontend embedded into the Go binary. No external Postgres or ClickHouse required. Blob storage (source maps, session recordings, AI traces) is written to a local folder by default and can optionally be backed by S3.

If your dashboards slow down as telemetry grows, the DuckDB deployment keeps this exact single-container setup but swaps the telemetry store for a columnar engine with far more read headroom.

All persistent state (both SQLite database files and blob storage) lives under /data. Bind-mount that single folder to keep your data across restarts.

Quick Start

Pull the pre-built image and run it with a persistent data volume:

docker pull ghcr.io/tracewayapp/traceway:sqlite
 
docker run -d --name traceway \
  -p 80:80 \
  -v "$(pwd)/traceway-data:/data" \
  -e JWT_SECRET="your-jwt-secret-min-32-characters-long" \
  -e APP_BASE_URL="https://traceway.example.com" \
  ghcr.io/tracewayapp/traceway:sqlite

Both SQLite files (traceway.db, traceway_telemetry.db) and uploaded blobs (under storage/) land inside the mounted folder.

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

Build from Source

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

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

Then use traceway:sqlite instead of ghcr.io/tracewayapp/traceway:sqlite in the commands above.

Run (S3 storage)

To offload blob storage to S3 (or any S3-compatible service like MinIO, Cloudflare R2, or DigitalOcean Spaces), set STORAGE_TYPE=s3 and provide the S3 credentials. SQLite still lives on disk under /data.

docker run -d --name traceway \
  -p 80:80 \
  -v "$(pwd)/traceway-data:/data" \
  -e JWT_SECRET="your-jwt-secret-min-32-characters-long" \
  -e STORAGE_TYPE="s3" \
  -e S3_BUCKET="your-bucket" \
  -e S3_REGION="us-east-1" \
  -e S3_ACCESS_KEY="your-access-key" \
  -e S3_SECRET_KEY="your-secret-key" \
  ghcr.io/tracewayapp/traceway:sqlite

For non-AWS providers add -e S3_ENDPOINT="https://s3.example.com". If S3_ACCESS_KEY and S3_SECRET_KEY are omitted, the AWS SDK falls back to the default credential chain (IAM role, environment, shared config).

If STORAGE_TYPE is unset (or set to local), blobs are written to /data/storage, the same volume as the SQLite files. No extra mounts are needed.

Configuration

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

Persistence

The image declares VOLUME ["/data"]. Mount a host folder or a named volume there to keep everything across restarts:

/data/
├── traceway.db              # users, organizations, projects, ...
├── traceway.db-wal          # SQLite WAL
├── traceway.db-shm          # SQLite shared memory
├── traceway_telemetry.db    # endpoints, exceptions, spans, metrics, ...
├── traceway_telemetry.db-wal
├── traceway_telemetry.db-shm
└── storage/                 # source maps, session recordings, AI traces (when STORAGE_TYPE=local)

Backup tip: stop the container or use sqlite3 traceway.db ".backup '/path/to/backup.db'" for a hot backup. WAL files are required for crash recovery, so when copying files manually, copy *.db, *.db-wal, and *.db-shm together.

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
 
# Hot backup of the main database
docker exec traceway sh -c "apk add --no-cache sqlite >/dev/null && sqlite3 /data/traceway.db \".backup '/data/traceway.backup.db'\""
 
# Stop and remove (data survives in the mounted volume)
docker stop traceway && docker rm traceway

Deploying to Railway

Railway (opens in a new tab) builds and runs the image from your GitHub repository, mounts a persistent volume at /data, and gives you a public HTTPS URL, a great fit for the SQLite deployment.

1. Connect the repo. Push the project to GitHub, then in Railway choose New Project → Deploy from GitHub repo and pick the Traceway repository.

2. Point Railway at Dockerfile.sqlite. Open Settings → Build on the service and set Custom Dockerfile Path to Dockerfile.sqlite. Railway will use that Dockerfile for every deploy.

3. Attach a volume at /data. Right-click the service tile and pick Attach volume, then enter /data as the mount path. Without this, your SQLite files and uploaded blobs get wiped on every redeploy.

4. Set environment variables. Open Variables and add:

To use external object storage, also set STORAGE_TYPE=s3, S3_BUCKET, S3_REGION, S3_ACCESS_KEY, S3_SECRET_KEY, and optionally S3_ENDPOINT. Otherwise blobs are written to /data/storage on the volume you added above.

5. Generate a domain. Open Settings → Networking → Generate Domain. Once Railway returns the *.up.railway.app URL, update APP_BASE_URL to match and redeploy.

6. Create the first user. Visit https://<your-domain>/register and create your account and organization. The first registered user automatically becomes the organization owner.

7. Point your SDKs at the new instance.

<project_token>@https://<your-domain>/api/report