Docker

The fastest way to a running keelwave is the app Compose profile. It starts TimescaleDB, applies migrations, then starts the API and dashboard on http://localhost:8080.

# from core/
docker compose --profile app up --build

That brings up three services, in order:

migrate waits on the db healthcheck (pg_isready), and app waits for migrate to complete successfully. Database files persist in the keelwave_db volume.

Check that it is up:

curl http://localhost:8080/v1/health
# {"data":{"status":"ok","version":"...","env":"development"}}

Then open http://localhost:8080 for the dashboard and http://localhost:8080/v1/docs for the API reference.

What the image contains

The keelwave image is self-contained: one binary, one process, one port, serving both the Go API and the React dashboard.

The Dockerfile builds in three stages:

1. web (node:22-bookworm-slim) — pnpm build compiles the dashboard as a static client-only SPA and copies the client bundle into internal/web/dist.
2. build (golang:1.26-bookworm) — overlays that directory, then CGO_ENABLED=0 go build -trimpath produces /out/keelwave with the dashboard embedded via //go:embed. Cross-compiled using TARGETOS and TARGETARCH.
3. runtime (gcr.io/distroless/static:nonroot) — non-root, no shell, EXPOSE 8080, ENTRYPOINT ["/usr/local/bin/keelwave"].

Routing inside the binary: chi matches /v1/* first (API, /v1/health, /v1/docs, /v1/openapi.json), and a catch-all mounted last serves the embedded dashboard. Unknown extensionless paths fall back to index.html so client-side routes deep-link; a missing asset returns 404.

Because the dashboard is same-origin with the API, it calls /v1/* over relative paths — no separate dashboard container, and no CORS setup needed for the dashboard itself.

Running the image directly

The binary needs a reachable Postgres/TimescaleDB. Minimum:

docker run --rm -p 8080:8080 \
  -e DB_ADDR="postgres://keelwave:keelwave@host:5432/keelwave?sslmode=disable" \
  ghcr.io/keelwave/keelwave:latest

To build the image locally instead of pulling it:

docker build --build-arg VERSION="$(git describe --tags --always)" -t keelwave:dev .

Released images are multi-arch (amd64 + arm64) and published to ghcr.io/keelwave/keelwave on a v* tag, with provenance and SBOM. Tags follow semver (X.Y.Z, X.Y, X), plus sha-<sha> and latest.

Database only

If you are running the Go binary from source, start just the database:

docker compose up -d db     # TimescaleDB (pg18) on :5432
make migrate-up             # apply all migrations
make run                    # API on :8080  (make dev for hot reload)

On a fresh checkout go build embeds only a placeholder dashboard. Run make web-build (or cd web && pnpm build) first if you want the real dashboard in a locally built binary. The Docker web stage does this automatically.

First API key

The server never stores plaintext API keys — only their SHA-256 hash — so a key is shown exactly once, at creation. There are two ways to get your first one.

Option 1 — seed script

make seed creates a user, an organization, a project, and one API key, then prints the plaintext to stdout:

make seed

project_id:   0199...
project_name: dev
api_key_id:   0199...
api_key:      kw_XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
store the api_key now — server only keeps the SHA-256 hash

Copy the kw_… value — that is what the SDKs authenticate with. Project and key names default to dev and seed; override them with SEED_PROJECT_NAME and SEED_KEY_NAME.

Option 2 — register, then create a key

SDKs send the key as Authorization: Bearer kw_<token> on /v1/ingest/* requests.

Next

• Configuration — every environment variable the server reads.
• Production — upgrades, backups, TLS.