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.
Try it before you installA hosted demo with a seeded company — boards, roadmap, org chart and six months of intelligence history — is ready to open at deckgauge.com/try. It is shared and reset periodically, so treat anything you change there as temporary.
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
./scripts/init-env.sh— writes.envfrom.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;--checkreports on one instead. There is nocp .env.example .envstep any more — the template ships every credential empty anddocker-compose.ymlrequires them, so a hand-copied file stops atdocker compose upwith the variable named rather than running on a password published in the public repository.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