Local setup

Getting a development environment running — everything in Docker.

Everything runs in Docker

There is exactly one command to start development:

docker compose up

That starts the Next.js app on port 3000, PostgreSQL on 5432, and MailHog (SMTP 1025, web UI 8025). Hot reload works through volume mounts on src/, prisma/ and public/; the Node debugger is on 9229.

Do not run npm run dev, Prisma commands, or npm install for the app on the host. They run in the container:

docker compose exec app npx prisma studio
docker compose exec app npm install <pkg>

Prerequisites

• Docker with Compose
• Node.js 22 on the host, for the quality gate (see below)

First run

1. Copy the environment file

   cp .env.example .env
   

   Most of it is optional for local work. The integrations (Graph, bexio, DocuSign, SECO) degrade cleanly when unconfigured.

2. Start the stack

   docker compose up
   
3. Push the schema and seed

   docker compose exec app npx prisma db push
   docker compose exec app npm run db:seed
   
4. Optionally seed demo data

   docker compose exec app npm run db:seed-demo
   # and to remove it again
   docker compose exec app npm run db:unseed-demo
   
5. Open the app

   http://localhost:3000. Mail goes to MailHog at http://localhost:8025 — magic links included.

Signing in locally

Local development can use a dev-login route, guarded three ways: ENABLE_DEV_LOGIN must be exactly "true", NODE_ENV must not be production, and the host must not be a production domain.

Production deployments must leave ENABLE_DEV_LOGIN unset. It is not a feature flag — it is a local-only bypass.

Set COOKIE_SECURE=false for plain http://localhost (the dev compose files already do). Never set it in a deployed environment.

The quality gate runs on the host

The gate is deliberately Docker-free and Postgres-free — unit and component tests mock the database — so it also works in web sessions where docker compose exec is not available:

npm run gate        # full: format, guards, script tests, lint, typecheck, tests, build
npm run gate:fast   # quick: format, guards, lint, typecheck — what the pre-push hook runs

See The quality gate.

Git hooks

Installed automatically on npm install:

Hook	Does
pre-commit	Auto-formats staged files with Prettier; runs the schema-migration guard.
pre-push	Runs npm run gate:fast.

Bypass deliberately with --no-verify when you have a reason.

Useful commands

# Database
docker compose exec app npx prisma db push
docker compose exec app npm run db:migrate:create -- describe_your_change
docker compose exec app npm run db:studio

# Tests
npm test                       # unit + component
npm run test:watch
npm run test:e2e               # Playwright

# Contracts
npm run gen:openapi            # regenerate the portal contract artifacts

Which CI path your diff takes

git diff --name-only origin/develop...HEAD | bash scripts/classify-pr-paths.sh

docs_only=true means CI runs only the static leg. prisma_changed=false means the Postgres migrations job is skipped.