Local dev setup¶

Implemented

Source: doc/operations/local-dev/ · Makefile targets

What runs¶

flowchart LR
    classDef infra fill:#eceff1,stroke:#455a64
    classDef cp    fill:#e3f2fd,stroke:#1565c0
    classDef wk    fill:#e8f5e9,stroke:#2e7d32

    subgraph Infra[docker compose]
        PG[(Postgres 16)]:::infra
        RD[(Redis 7)]:::infra
        NATS[(NATS JetStream)]:::infra
        TMP[(Temporal auto-setup)]:::infra
        KC[(Keycloak<br/>H2 in-memory<br/>realm imported)]:::infra
        OBS[(OTel + Prom + Loki +<br/>Tempo + Grafana)]:::infra
        WEB[(Next.js web<br/>optional profile)]:::infra
    end

    subgraph Host["Host (go run)"]
        API[cmd/api<br/>air hot-reload]:::cp
        BW[billing-worker]:::wk
        PW[provisioning-worker]:::wk
        NR[notification-relay]:::wk
        OR[outbox-relay]:::wk
    end

    API --> PG
    API --> RD
    API --> NATS
    API --> KC
    PW --> NATS
    BW --> NATS
    OR --> PG
    OR --> NATS
    NR --> NATS
    NR --> RD
    API --> OBS

Quick start¶

# 1. env
cp doc/operations/local-dev/env.local.example .env.local

# 2. infra
docker compose --env-file .env.local \
  -f doc/operations/local-dev/docker-compose.yaml up -d

# 3. schema + seed
psql $DATABASE_URL -f doc/architecture/db_schema_v1.sql
psql $DATABASE_URL -f scripts/seed.sql

# 4. run API (hot-reload via air)
make dev-api

Or in one shot:

make dev-up   # infra + api + workers

Compose profiles¶

Profile	Use
`docker-compose.yaml`	core infra (postgres, redis, nats, temporal, keycloak)
`docker-compose.app.yaml`	adds web (Next.js)
`docker-compose.observability.yaml`	OTel collector + Prometheus + Loki + Tempo + Grafana
`docker-compose.gitlab.yaml`	optional self-hosted GitLab for offline-dev

Dev users¶

User	Password	Roles
`dev-user`	`dev123`	`user`
`dev-admin`	`admin123`	`user`, `admin`

Fetch a bearer token:

curl -s -X POST http://localhost:8080/realms/gpuaas/protocol/openid-connect/token \
  -d "grant_type=password&client_id=gpuaas-api&client_secret=dev-client-secret&username=dev-user&password=dev123" \
  | jq -r .access_token

Make target reference¶

make dev-infra              start infra docker-compose
make dev-up                 start full local stack
make dev-up-web             start with web profile
make dev-up-observability   start with otel stack
make dev-api                go run ./cmd/api with air hot-reload
make dev-worker-billing     go run ./cmd/billing-worker
make dev-worker-provisioning  go run ./cmd/provisioning-worker
make dev-worker-notification  go run ./cmd/notification-relay
make dev-worker-outbox      go run ./cmd/outbox-relay
make build-cli              build CLI binary
make test                   go test ./...
make test-integration       go test ./... -tags integration
make verify-web             pnpm typecheck + full web tests
make lint                   golangci-lint run
make codegen                regenerate Go + TS artifacts
make db-init                apply db_schema_v1.sql
make seed                   apply scripts/seed.sql
make e2e-up                 full-stack docker-compose

Lab parity mode¶

→ Read source: Local_Parity_Mode_Inventory_v1.md.

make kind-parity-up brings a kind-cluster-based parity stack so production deployment topology can be exercised locally.