Local Dev Setup

:::info Source Sourced from services/authoring-service/14-LOCAL_DEV_SETUP.md in the documentation repo. :::

1. Prerequisites

Node 20, pnpm 9, Docker 24.

2. Quick Start

cd services/authoring-service
cp .env.example .env.local
pnpm install
docker compose -f docker-compose.dev.yml up -d    # postgres, redis, nats, minio, ai-gateway-mock
pnpm db:migrate
pnpm seed
pnpm dev                     # API on :3010
pnpm dev:collab              # Yjs collab on :3011 (M5+)
pnpm dev:worker              # Outbox + saga worker

3. Dependencies

Service	Port	Purpose
postgres	5432	Schema authoring
redis	6379	Draft locks, Yjs awareness, AI cache
nats	4222	Events
minio	9000	S3-compatible for draft snapshots, SCORM staging
ai-gateway-mock	3020	Deterministic AI responses in dev
media-service (mock)	3060	Media references

4. Environment Variables

PORT=3010
COLLAB_PORT=3011
LOG_LEVEL=debug
ENV=dev

DATABASE_URL=postgres://authoring:authoring@localhost:5432/authoring
REDIS_URL=redis://localhost:6379/10
NATS_URL=nats://localhost:4222
NATS_STREAM=AUTHORING

S3_ENDPOINT=http://localhost:9000
S3_ACCESS_KEY=minioadmin
S3_SECRET_KEY=minioadmin
S3_BUCKET_DRAFTS=authoring-drafts-dev

AI_GATEWAY_URL=http://localhost:3020
AI_DEFAULT_PROMPTS=block-generation,quiz-generation,text-improvement,translation

MEDIA_SERVICE_URL=http://localhost:3060
CATALOG_SERVICE_URL=http://localhost:3070
CONTENT_SERVICE_URL=http://localhost:3080

PUBLISH_SAGA_TIMEOUT_MS=900000     # 15 min
SCORM_IMPORT_MAX_MB=500
YJS_SNAPSHOT_INTERVAL_MS=60000

5. Seed Data

pnpm seed creates:

Tenant	Drafts
acme	3 drafts: "Onboarding 101" (published_idle), "Safety Essentials" (editing), "Compliance 2026" (draft_ai with AI blocks)
globex	2 drafts for two-tenant isolation test

6. Useful Commands

pnpm dev
pnpm test
pnpm test:integration
pnpm test:saga                 # publish saga chaos tests
pnpm ai:prompt-eval            # Regression suite for AI prompts
pnpm scorm:validate <file.zip> # Validate SCORM zip
pnpm openapi:check
pnpm block:migrate-schema      # Migrate block registry schema

7. AI Mock

ai-gateway-mock returns deterministic responses per prompt + input hash. Enables snapshot testing of AI-generated blocks. Real AI calls require AI_USE_REAL=1.

8. Collab Debugging

• Open two browsers as different authors in same tenant.
• Open the same draft.
• pnpm dev:collab:debug logs every Yjs update.
• pnpm collab:inspect <draftId> prints current Yjs doc state + awareness map.