Skip to content

Quick start

Bring the full stack up locally and sign in — about 5 minutes.

Requirements

Tool Version Note
Docker + Compose latest recommended path — the whole stack in one command
Go 1.26+ only if running the backend by hand
Node.js 20+ only if running the frontend by hand
PostgreSQL / Redis 16+ / 7+ not needed when using Docker

1. Fastest path — Docker Compose

git clone https://github.com/gerege-systems/gerege-app-mn.git
cd gerege-app-mn
docker compose up -d --build

This brings up:

Service What Note
db PostgreSQL 16 + pgvector built from backend/deploy/db/Dockerfile (alpine)
redis Redis 7 session deny-list, transient state
migrate One-shot migration runs on every up, idempotent
api Go API (:8080) the platform-core server
web Next.js BFF (:3000) the only thing the browser talks to

Then open http://localhost:3000.

Do not swap the pgvector image

db is built from an alpine-based pgvector image. Moving to the Debian pgvector image changes the collation and breaks the existing volume.

Compose runs ENVIRONMENT=development on purpose

The internal database has no TLS, and the production guard requires sslmode=verify-full. So the local stack runs in development mode.

2. Running by hand (development)

cd backend
cp internal/config/.env.example internal/config/.env
# set JWT_SECRET (≥32 chars), DB, Redis, EID_* RP credentials
go run ./cmd/api          # → http://localhost:8080

The migration / seed / healthcheck binaries live in platform-core:

go run github.com/gerege-systems/private-gerege-core/cmd/migration
go run github.com/gerege-systems/public-gerege-core/cmd/seed

cd frontend
cp .env.example .env.local     # BACKEND_URL=http://localhost:8080
npm install
npm run dev                    # → http://localhost:3000

3. Signing in

Choose Sign in with eID on the landing page, then one of three routes:

  • QR code — scan the on-screen QR with the eID mobile app.
  • App2App — jump straight into the eID app on your phone (deep link).
  • National ID — enter your national ID and approve the push on your registered device.

The Google option only appears when GOOGLE_CLIENT_ID/SECRET are configured. See eID sign-in.

Trying it without eID credentials

With EID_* unset, real sign-in will not work. If you only want to inspect the UI and architecture, the platform-core unit tests use a FakeEID stub — the flow is visible there.

4. Checks

cd backend  && go test ./...     # unit tests (mocks, fast)
cd frontend && npm run build     # build + lint + typecheck (same as CI)
cd frontend && npm run test      # vitest — i18n parity, BFF, security headers

Reproducing the CI gates locally:

cd backend && make pre-push      # lint + test + swag drift + build
gofmt -l .                       # must be empty

5. Common problems

Symptom Cause Fix
migrate fails: failed to load config file wrong ownership on backend.env (container uid 65532) chown 65532:65532 backend.env
every /api/v1/* returns 404 BACKEND_URL resolves to a different container pin the full container name
no sign-in button eID / Google credentials not configured add EID_* or GOOGLE_*
API refuses to start connecting as a superuser role in production create a least-privilege role (RLS)

Next