Installing Deckgauge

Four commands take a fresh clone to a running stack at http://localhost:3000. The order is not optional — the migration step runs against containers that are already up, not before them.

deckgauge · docker compose ps

postgres healthy

clickhouse healthy

keycloak Up — no healthcheck defined, realm imported

api starting — waits up to 90s before its first health check

Container health right after `docker compose up -d`, before migrations run.

Prerequisites

Tool	Version
Node.js	20+
pnpm	9+ (`npm install -g pnpm@9`)
Docker	latest — Docker Desktop, Rancher Desktop, or any compatible engine

Deckgauge is a pnpm monorepo (this docs site is the one npm exception). Run every command below from the repository root.

How to install it

./scripts/init-env.sh — writes .env from .env.example, generating a fresh random password for Postgres, ClickHouse, Keycloak’s database, the Keycloak admin console, the OIDC client secret and the session-signing key. It refuses to overwrite an existing .env; --check reports on one instead. There is no cp .env.example .env step any more — the template ships every credential empty and docker-compose.yml requires them, so a hand-copied file stops at docker compose up with the variable named rather than running on a password published in the public repository. See the configuration reference for what each variable does.
pnpm install — installs dependencies for every app and package in the workspace.
docker compose up -d — builds and starts every service: postgres, redis, clickhouse, keycloak-db, keycloak, api, web, and worker. See the services and how they fit together for what each one does.
pnpm --filter @deckgauge/db migrate:deploy — applies the committed Prisma migrations against Postgres, creating the schema. This has to run after step 3 because Postgres has to be up and healthy first.

What happens on first boot

ClickHouse initializes its analytics schema from clickhouse/schemas/, mounted read-only into its docker-entrypoint-initdb.d — this only runs once, against a fresh volume. Keycloak's entrypoint processes keycloak/realm-export.json before the server starts: if the Microsoft SSO variables are all set it fills in the identity provider, otherwise it strips identity-provider config from the import entirely (see Keycloak and identity providers). The api and worker containers wait for postgres, redis, and clickhouse to report healthy before starting; web only waits for api to start, since it retries API calls at request time rather than blocking on a health check.

Verifying the stack is healthy

Check container status — docker compose ps should show every service as Up, with postgres, clickhouse, redis, keycloak-db, and api reporting healthy.
Hit the API health check — curl http://localhost:3001/health should return a success response.
Open the app — http://localhost:3000 should load the board and let you sign in through Keycloak (self-registration is enabled by default).

If it looks wrong

Symptom	Cause	Fix
`migrate:deploy` fails to connect	Postgres isn't up yet, or isn't healthy	Run `docker compose ps` first and wait for `postgres` to show `healthy`, then retry
`pnpm --filter @deckgauge/db migrate:dev` fails with a shadow-database error (P3006)	`migrate:dev` is not supported in this repo	Use `migrate:deploy` for setup; for a new schema change, hand-write the migration SQL and apply it the same way
The API container keeps restarting	Its healthcheck has a 90s `start_period` before the first check counts — a cold boot can look unhealthy briefly	Give it the full grace window before assuming it's broken; check `docker compose logs api` if it's still failing after that

More failure modes, including disk and memory pressure, are covered in Troubleshooting a self-hosted install.

Configuration reference — every variable in .env.example.
Services & architecture — what each container does, and what breaks when it's down.
Troubleshooting — evidenced failure modes and how to read them.
Quickstart — the first things to do once the app is up.

Last updated 11 September 2026