Build Tags
The Traceway backend uses Go build tags to switch between storage backends and to embed the frontend. Storage is selected on two independent axes: the telemetry store (high-volume, append-only data) and the transactional store (relational/config data).
Tags
Telemetry axis
| Tag | Purpose |
|---|---|
(none) / telemetry_sqlite | SQLite telemetry store: embedded mode. This is the default; telemetry_sqlite is accepted as an explicit no-op spelling. |
telemetry_duckdb | DuckDB telemetry store: embedded mode with a columnar engine for much faster dashboard analytics. Requires CGO_ENABLED=1. |
telemetry_ch | ClickHouse telemetry store: standalone server mode. |
Transactional axis
| Tag | Purpose |
|---|---|
(none) / transactional_sqlite | SQLite main database. This is the default; transactional_sqlite is accepted as an explicit no-op spelling. |
transactional_pg | PostgreSQL main database: standalone server mode. |
Other
| Tag | Purpose |
|---|---|
localdist | Embeds frontend from static/dist/ instead of static/frontend/. Used by traceway-cloud to inject billing UI into the frontend build. Not needed for open-source builds. |
Supported combinations
Only three combinations are supported, enforced by compile-time guard files in backend/app/db/; an unsupported combination fails the build with a descriptive identifier in the error message:
| Mode | Tags | Databases |
|---|---|---|
| Embedded (default) | (none) | SQLite main + SQLite telemetry |
| Embedded, columnar telemetry | telemetry_duckdb | SQLite main + DuckDB telemetry |
| Standalone server | transactional_pg telemetry_ch | PostgreSQL main + ClickHouse telemetry |
The legacy pgch and duckdb tags were renamed to this scheme; passing them fails the build with a message pointing at the new tags, so a stale invocation cannot silently produce the wrong binary.
Building
Embedded mode (SQLite)
No tags needed: a plain go build gives you the embedded SQLite backend:
cd backend && go build ./cmd/tracewayThis is what library consumers get when they go get github.com/tracewayapp/traceway/backend and call tracewaybackend.Run().
Embedded mode with DuckDB telemetry
cd backend && CGO_ENABLED=1 go build -tags telemetry_duckdb ./cmd/tracewayDuckDB links prebuilt glibc static libraries, so this build needs CGO and a glibc-based image (Debian, not Alpine) when containerized; see Dockerfile.duckdb and the DuckDB deployment guide.
Standalone server (ClickHouse + PostgreSQL)
cd backend && go build -tags "transactional_pg telemetry_ch" ./cmd/tracewayRequires CLICKHOUSE_SERVER, POSTGRES_HOST, and the other environment variables to be configured.
Docker images
Each Dockerfile pairs one of the supported tag combinations with a SvelteKit frontend build that gets embedded into the Go binary from static/frontend/:
| Dockerfile | Build tags | Published image |
|---|---|---|
Dockerfile | transactional_pg telemetry_ch | ghcr.io/tracewayapp/traceway:latest (all-in-one: ClickHouse + PostgreSQL + backend under supervisord) |
Dockerfile.minimal | transactional_pg telemetry_ch | ghcr.io/tracewayapp/traceway:minimal (backend only, external ClickHouse/PostgreSQL) |
Dockerfile.sqlite | (none) | ghcr.io/tracewayapp/traceway:sqlite (embedded SQLite, Alpine, CGO-free) |
Dockerfile.duckdb | telemetry_duckdb | ghcr.io/tracewayapp/traceway:duckdb (SQLite main + DuckDB telemetry, Debian) |
You don't need to embed the frontend for local development; run the frontend dev server separately with cd frontend && npm run dev.
Running Tests
SQLite tests (default)
cd backend && go test -v -count=1 ./app/repositories/...DuckDB tests
cd backend && CGO_ENABLED=1 go test -tags telemetry_duckdb -v -count=1 ./app/repositories/...ClickHouse tests
cd backend && TEST_CLICKHOUSE_SERVER=localhost:9000 go test -tags "transactional_pg telemetry_ch" -v ./app/repositories/...Without TEST_CLICKHOUSE_SERVER set, the ClickHouse tests skip cleanly.