From zero to your first board
Four commands stand up the whole stack on your own machine. From there it's a normal sign-in, a new board, and one connected source before data starts flowing in.
pnpm, not npmDeckgauge itself is a pnpm monorepo — the commands below need pnpm installed (
npm install -g pnpm@9). That's separate from this docs site, which is a plain npm project.What it does, and where the data comes from
Everything runs in containers on localhost: Postgres for boards and IAM, Redis for the sync queue, ClickHouse for engineering intelligence, Keycloak for auth, and the web/api/worker services themselves. Order matters for the setup commands — the migration needs a live database to connect to, so it runs after the containers are up, not before.
How to stand up the stack
cp .env.example .env— copies the environment template. The defaults work out of the box.pnpm install— installs dependencies across every app and package in the monorepo.docker compose up -d— starts Postgres, Redis, ClickHouse, Keycloak, and the web/api/worker containers in the background.pnpm --filter @deckgauge/db migrate:deploy— applies the Prisma migrations against the now-running Postgres container.
Don't reach for migrate:dev
pnpm --filter @deckgauge/db migrate:dev fails here with a shadow-database error (Prisma P3006). migrate:deploy is the supported path for every schema change in this repo.How to get your first board synced
- Open
http://localhost:3000and sign in — self-registration through Keycloak is on by default, so a new account is enough. - New → pick a board template — name it and press Create.
- Sources tab → Add source — choose a provider (Jira, GitHub, GitLab, or Azure DevOps), enter its credentials, and attach the project to the board.
- Sync Now — pulls data immediately. Left alone, the worker syncs every connected source automatically on its own schedule — roughly every 15 minutes for board-level connectors; see When your data refreshes for GitHub's activity-based tiers.
Platform launch
⋮⋮ProjectOwnerStatus
⋮⋮Checkout revampAda L.In progress
Jira · PLAT
⋮⋮PLAT-101 · Guest checkoutR. PatelIn progress
The board right after the first sync — a manual group plus a Jira-synced group.
If it looks wrong
| Symptom | Cause | Fix |
|---|---|---|
docker compose up -d exits or a container won't stay up | Stale containers or volumes from a previous run | Run docker compose down, then docker compose up -d again |
migrate:deploy can't reach the database | Postgres hasn't finished its startup healthcheck yet | Wait a few seconds and re-run pnpm --filter @deckgauge/db migrate:deploy |
migrate:dev errors with P3006 | The shadow database Prisma needs for migrate:dev isn't supported in this setup | Use migrate:deploy instead — it's the only supported path here |
Related
- Concepts & data model — what a board, group, and source actually are underneath.
- Navigating the app — the sidebar, search, and the New menu you'll use next.
- Connecting sources — credentials and sync details for every provider.
Last updated