Registration Service — Local Dev Setup

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

1. Prerequisites

Tool	Version
Node.js	22.x
pnpm	9.x
Docker + Docker Compose	24+
mkcert (optional)	For local TLS

2. docker-compose.yml (dev stack)

version: "3.9"
services:
  postgres:
    image: postgres:16-alpine
    environment:
      POSTGRES_USER: ghasi
      POSTGRES_PASSWORD: ghasi_dev
      POSTGRES_DB: registration_dev
    ports:
      - "5433:5432"
    volumes:
      - pg_registration_data:/var/lib/postgresql/data

  redis:
    image: redis:7-alpine
    ports:
      - "6380:6379"

  nats:
    image: nats:2.10-alpine
    command: ["-js", "-m", "8222"]
    ports:
      - "4222:4222"
      - "8222:8222"

volumes:
  pg_registration_data:

3. Environment Variables (.env.example)

PORT=3003
NODE_ENV=development
DATABASE_URL=postgresql://ghasi:ghasi_dev@localhost:5433/registration_dev
REDIS_URL=redis://localhost:6380
NATS_URL=nats://localhost:4222
JWKS_URI=http://localhost:8080/realms/ghasi-dev/protocol/openid-connect/certs
AUDIT_NATS_SUBJECT=AUDIT.events
MODULE_KEY=ADMIN-REG
TERMINOLOGY_URL=http://localhost:3020
# Optional
REGISTRATION_REQUIRED_FIELDS_JSON=["names","birthDate"]
REGISTRATION_UNMERGE_ENABLED=false
REGISTRATION_UNIDENTIFIED_SLA_DAYS=7
REGISTRATION_PORTRAIT_CONSENT_REQUIRED=true
REGISTRATION_PORTRAIT_RETENTION_DAYS=2555
REGISTRATION_ALTERNATE_ID_TYPES_JSON=["VILLAGE_REG","HOUSEHOLD_BOOK"]

4. Common Commands

# Install dependencies
pnpm install

# Start dev stack
docker compose up -d

# Run migrations
pnpm drizzle-kit migrate

# Seed dev data
pnpm seed:dev

# Start in watch mode
pnpm dev:registration

# Run unit tests
pnpm test:unit --filter=registration

# Run integration tests (requires docker stack up)
pnpm test:integration --filter=registration

# Check coverage
pnpm test:coverage --filter=registration

5. Seed Data

The pnpm seed:dev script creates:

Seed entity	Description
2 tenants	tenant-af (Afghanistan) and tenant-ae (UAE)
10 patients	Mix of identified, provisional, and one deceased
3 encounters	Planned, in-progress, and finished states
1 merged pair	Source + survivor for testing merge workflows
Kin relationship catalog	Standard codes (MOTHER, FATHER, SPOUSE, SIBLING, etc.)
3 extension schemas	employment, marital, appearance standard bundles

6. Local FHIR Testing

# Start FHIR facade (uses same service process)
curl -H "Authorization: Bearer <local-dev-jwt>" \
  http://localhost:3003/fhir/R4/Patient?family=Ahmadi

Use pnpm generate:dev-token to get a short-lived dev JWT for local testing.