Audit Service — Local Dev Setup

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

1. Prerequisites

Tool	Version	Purpose
Node.js	22 LTS	Runtime
pnpm	9.x	Package manager
Docker Desktop	4.x	Compose stack
nats-cli	latest	Stream inspection
MinIO Client (mc)	latest	Object storage inspection

2. docker-compose.yml (audit-service dev stack)

version: "3.9"
services:
  postgres:
    image: postgres:16-alpine
    environment:
      POSTGRES_DB: audit_dev
      POSTGRES_USER: audit_app
      POSTGRES_PASSWORD: dev_password
    ports:
      - "5433:5432"
    volumes:
      - audit_pg_data:/var/lib/postgresql/data
      - ./docker/init.sql:/docker-entrypoint-initdb.d/init.sql

  nats:
    image: nats:2.10-alpine
    command: ["--jetstream", "--store_dir=/data"]
    ports:
      - "4222:4222"
      - "8222:8222"
    volumes:
      - audit_nats_data:/data

  minio:
    image: minio/minio:latest
    command: server /data --console-address ":9001"
    environment:
      MINIO_ROOT_USER: minioadmin
      MINIO_ROOT_PASSWORD: minioadmin
    ports:
      - "9000:9000"
      - "9001:9001"
    volumes:
      - minio_data:/data

volumes:
  audit_pg_data:
  audit_nats_data:
  minio_data:

The docker/init.sql script creates the audit_app role with INSERT-only permissions on audit_entries (mirrors production).

3. Environment variables (.env.example)

NODE_ENV=development
PORT=3006
LOG_LEVEL=debug

DATABASE_URL=postgresql://audit_app:dev_password@localhost:5433/audit_dev
DATABASE_SCHEMA=audit

NATS_URL=nats://localhost:4222
NATS_CONSUMER_NAME=audit-service-dev

OBJECT_STORAGE_ENDPOINT=http://localhost:9000
OBJECT_STORAGE_ACCESS_KEY=minioadmin
OBJECT_STORAGE_SECRET_KEY=minioadmin
OBJECT_STORAGE_BUCKET=audit-exports

KEYCLOAK_REALM_URL=http://localhost:8080/realms/dev
JWT_PUBLIC_KEY_PATH=./docker/dev-jwt-public.pem

OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4318
OTEL_SERVICE_NAME=audit-service

CHAIN_INTEGRITY_JOB_CRON=0 2 * * *
EXPORT_SIGNED_URL_TTL_SECONDS=3600

4. Start the dev stack

# 1. Start dependencies
docker compose up -d postgres nats minio

# 2. Create MinIO bucket
mc alias set local http://localhost:9000 minioadmin minioadmin
mc mb local/audit-exports

# 3. Install dependencies
pnpm install

# 4. Apply migrations
pnpm db:migrate

# 5. Seed with test events
pnpm db:seed

# 6. Start service in watch mode
pnpm dev

5. Database commands

Command	Description
pnpm db:migrate	Apply Drizzle migrations
pnpm db:migrate:dry	Show SQL without executing
pnpm db:seed	Insert synthetic audit entries across 2 test tenants
pnpm db:verify-chain	Run chain-hash integrity check against dev DB
pnpm db:studio	Open Drizzle Studio at localhost:4983

6. Common development commands

Command	Description
pnpm dev	NestJS watch mode
pnpm build	TypeScript compile
pnpm test	All tests
pnpm test:unit	Unit only
pnpm test:integration	Integration (requires compose stack)
pnpm test:coverage	Coverage report
pnpm lint	ESLint
pnpm typecheck	tsc --noEmit

7. Seed data overview

Entity	Count	Notes
Tenants	2	ten_dev_a, ten_dev_b for isolation testing
AuditEntry rows	500 per tenant	Mix of all event types; realistic timestamps over 30 days
AuditExport jobs	2	One completed, one queued

8. Publish a test event (NATS)

# Simulate a USER_SUSPENDED event from identity-service
nats pub com.ghasi-ehr.iam.user.suspended '{
  "id": "evt_test_001",
  "type": "com.ghasi-ehr.iam.user.suspended",
  "source": "identity-service",
  "specversion": "1.0",
  "time": "2026-04-18T10:00:00Z",
  "data": {
    "tenantId": "ten_dev_a",
    "actorId": "usr_admin001",
    "resourceId": "usr_test_001",
    "reason": "Policy violation"
  }
}'

# Verify ingestion
nats stream view AUDIT_DEV --count 1

9. Troubleshooting

Issue	Resolution
INSERT denied on audit_entries	Check docker/init.sql creates audit_app role with INSERT-only
Chain-hash mismatch in dev	Run pnpm db:verify-chain; likely seed order issue; run pnpm db:reset
MinIO bucket not found	Run mc mb local/audit-exports manually
NATS subscription not receiving	Check wildcard consumer is created: nats consumer ls AUDIT_DEV