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.

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.

If the host or container has less than 16 GB of memory, also set SQLITE_CACHE_SIZE_MB. The default can use several gigabytes; see Memory sizing.

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

Memory sizing

On a memory-capped host, set SQLITE_CACHE_SIZE_MB. The default suits a large dedicated machine, and it will get a small container killed for running out of memory.

The variable sizes SQLite's page cache for the telemetry database. Three things decide what it really costs:

• It is per connection. Every connection to the telemetry database keeps its own cache, and Traceway opens up to 4 of them.
• It costs about twice its size. The SQLite driver stores each 4 KB page in an 8 KB slot, so a 32 MB cache takes about 64 MB of memory.
• It is kept once filled. A cache grows as its connection reads or writes pages, and it stays allocated afterwards. Ingest, the hourly retention pass and dashboard queries over recent data all fill it.

So the most the caches can take is:

4 connections x 2 x SQLITE_CACHE_SIZE_MB

With the default of 512 that is 4 GB. One connection alone reaches about 1 GB within seconds of startup once the telemetry file is larger than about 500 MB, because the retention pass reads through it.

A good starting point is the container's memory in MB divided by 32. That keeps the caches within a quarter of the container:

docker run -d --name traceway \
  --memory=1g \
  -p 80:80 \
  -v "$(pwd)/traceway-data:/data" \
  -e JWT_SECRET="your-jwt-secret-min-32-characters-long" \
  -e SQLITE_CACHE_SIZE_MB="32" \
  ghcr.io/tracewayapp/traceway:sqlite

The rest of the container is not spare. Dashboard queries need about 150 MB of working memory on top of the caches, the source map cache has its own cap (SOURCEMAP_CACHE_MAX_BYTES_MB, 500 MB by default), and the operating system uses what is left to cache the database file. That file cache serves every read the SQLite cache does not hold, so a smaller SQLITE_CACHE_SIZE_MB changes where pages are cached, not what queries return.

512 MB is only enough while the telemetry file is small. Once it grows to several GB, give the container at least 1 GB, or the first dashboard opened after a restart can take minutes.

The server logs the value it is using at startup:

SQLite telemetry database opened at /data/traceway_telemetry.db (page cache: 32 MB per connection, up to 4 connections)

The sign of a cache that is too large is a container that restarts with exit code 137 (OOMKilled) when a dashboard opens or during heavy ingest, with nothing in the application log before the restart.

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