Population Health Service — Local Dev Setup

Status: populated Owner: TBD Last updated: 2026-04-18 Companion: Service Template

1. Prerequisites

Tool	Version
Docker Desktop	≥ 4.25
Node.js	22.x
pnpm	≥ 9

2. docker-compose.yml (service-local)

version: "3.9"
services:
  db:
    image: postgres:16-alpine
    environment:
      POSTGRES_DB: population_health_dev
      POSTGRES_USER: pophealth
      POSTGRES_PASSWORD: devpass
    ports: ["5435:5432"]
    volumes: ["pophealth_pgdata:/var/lib/postgresql/data"]

  nats:
    image: nats:2.10-alpine
    command: "-js -sd /data"
    ports: ["4222:4222", "8222:8222"]
    volumes: ["pophealth_natsdata:/data"]

  dhis2-mock:
    image: wiremock/wiremock:3.3.1
    ports: ["8088:8080"]
    volumes: ["./test/wiremock:/home/wiremock"]

volumes:
  pophealth_pgdata:
  pophealth_natsdata:

3. Environment Variables (.env.example)

DATABASE_URL=postgresql://pophealth:devpass@localhost:5435/population_health_dev
NATS_URL=nats://localhost:4222
KEYCLOAK_JWKS_URL=http://localhost:8080/realms/ghasi-dev/protocol/openid-connect/certs
DHIS2_BASE_URL=http://localhost:8088
DHIS2_USERNAME=admin
DHIS2_PASSWORD=district
KMS_KEY_ARN=arn:aws:kms:local:000000000000:key/dev-key
OBJECT_STORAGE_BUCKET=pophealth-exports-dev
OBJECT_STORAGE_ENDPOINT=http://localhost:9000
PORT=3030
OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4318

4. Bootstrap Commands

# 1. Start dependencies
docker compose up -d

# 2. Install dependencies
pnpm install

# 3. Run DB migrations
pnpm drizzle-kit migrate

# 4. Seed development data
pnpm seed:dev

# 5. Start service in watch mode
pnpm dev

# 6. Run all tests
pnpm test

# 7. Run integration tests only
pnpm test:integration

# 8. View NATS dashboard
open http://localhost:8222

5. Seed Data

pnpm seed:dev creates:

• 3 tenants (tenant-a, tenant-b, tenant-platform)
• 2 facilities per tenant
• 1,000 synthetic patients per facility with randomized conditions
• 5 pre-built cohort definitions (diabetes, hypertension, MCH, overdue screenings, high-risk)
• Pre-computed quality metric snapshots for current quarter
• WireMock stubs for DHIS2 success and 502 failure responses

6. Common Dev Tasks

Task	Command
Regenerate OpenAPI spec	pnpm openapi:generate
Run Drizzle Studio (DB browser)	pnpm drizzle-kit studio
Trigger HMIS export manually	curl -X POST http://localhost:3030/api/v1/population-health/hmis/exports -H "Authorization: Bearer <token>" -d '{"indicatorFamily":"service-utilization","period":{"start":"2026-04-01","end":"2026-04-17"}}'
Inspect outbox queue	psql $DATABASE_URL -c "SELECT * FROM population_health_outbox WHERE published = false ORDER BY created_at;"