Virtual Care 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: virtual_care_dev
      POSTGRES_USER: vcare
      POSTGRES_PASSWORD: devpass
    ports: ["5436:5432"]
    volumes: ["vcare_pgdata:/var/lib/postgresql/data"]

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

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

  keycloak:
    image: quay.io/keycloak/keycloak:24.0
    command: start-dev
    environment:
      KEYCLOAK_ADMIN: admin
      KEYCLOAK_ADMIN_PASSWORD: admin
    ports: ["8080:8080"]

volumes:
  vcare_pgdata:
  vcare_natsdata:

3. Environment Variables (.env.example)

DATABASE_URL=postgresql://vcare:devpass@localhost:5436/virtual_care_dev
NATS_URL=nats://localhost:4223
KEYCLOAK_JWKS_URL=http://localhost:8080/realms/ghasi-dev/protocol/openid-connect/certs
JITSI_SERVER_URL=http://localhost:8089
JITSI_JWT_APP_ID=ghasi-dev
JITSI_JWT_SECRET=dev-secret-change-in-production
KMS_KEY_ARN=arn:aws:kms:local:000000000000:key/dev-key
FHIR_GATEWAY_BASE_URL=http://localhost:3050
AI_GATEWAY_BASE_URL=http://localhost:3040
PORT=3031
OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4318
SESSION_GRACE_MINUTES_BEFORE=15
SESSION_GRACE_RECONNECT_SECONDS=60

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
pnpm test:integration

5. WireMock Stubs for Jitsi

Place stub files in test/wiremock/mappings/:

{
  "mappings": [
    {
      "request": { "method": "GET", "url": "/health" },
      "response": { "status": 200, "body": "{\"healthy\":true}" }
    },
    {
      "request": { "method": "POST", "url": "/http-bind" },
      "response": { "status": 200 }
    }
  ]
}

For backend failure simulation, update the health stub to return 503.

6. Seed Data

pnpm seed:dev creates:

• 2 licensed tenants; 1 unlicensed tenant
• 5 providers + 10 patients (8 with telehealth consent, 2 without)
• Pre-created sessions in each lifecycle state
• WireMock stubs: Jitsi healthy (default) + Jitsi 503 (toggle via WireMock Admin API)

7. Common Dev Tasks

Task	Command
Regenerate OpenAPI spec	pnpm openapi:generate
Run Drizzle Studio	pnpm drizzle-kit studio
Create a test session	curl -X POST http://localhost:3031/api/v1/virtual-care/sessions -H "Authorization: Bearer <token>" -d '{"patientId":"...","scheduledStart":"...","scheduledEnd":"..."}'
Simulate backend failure	curl -X POST http://localhost:8089/__admin/mappings -d '{"request":{"method":"GET","url":"/health"},"response":{"status":503}}'
Inspect outbox	psql $DATABASE_URL -c "SELECT * FROM virtual_care_outbox WHERE published = false ORDER BY created_at;"