Skip to main content

Local Dev Setup

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

1. Prerequisites​

Node 20, pnpm 9, Docker 24, Postgres CLI 16.

2. Quick Start​

cd services/progress-service
cp .env.example .env.local
pnpm install
docker compose -f docker-compose.dev.yml up -d
pnpm db:migrate
pnpm partman:init           # pg_partman monthly partition init
pnpm seed
pnpm dev                    # :3030
pnpm dev:projector

3. Dependencies​

ServicePortPurpose
postgres5432Schema progress; pg_partman ext
redis6379Query cache
nats4222Events

4. Environment​

PORT=3030
LOG_LEVEL=debug
ENV=dev

DATABASE_URL=postgres://progress:progress@localhost:5432/progress
DATABASE_READ_URL=postgres://progress:progress@localhost:5432/progress
REDIS_URL=redis://localhost:6379/30
NATS_URL=nats://localhost:4222
NATS_STREAM=PROGRESS

XAPI_VERSION=1.0.3
XAPI_STATEMENT_BATCH_MAX=10000

PARTITION_MONTHS_RETAIN_HOT=6
PARTITION_DETACH_SCHEDULE="0 3 * * 0"   # Sunday 3 AM

OUTBOX_POLL_INTERVAL_MS=200

STATEMENT_QUERY_CACHE_TTL_S=60

5. Seed Data​

  • 2 enrollments with full-course completion (attempts × 100 statements each).
  • 1 in-progress attempt (open state, 20 statements).
  • 1 failed attempt → retake journey.
  • GDPR-erasure fixture: user erased_user@dev.local scheduled for erasure in tests.

6. Useful Commands​

pnpm dev
pnpm test
pnpm test:integration
pnpm test:xapi:conformance   # ADL xAPI test suite
pnpm test:replay             # event-log replay test
pnpm transcript:render <enrollmentId>
pnpm xapi:query --agent ... --verb ...
pnpm openapi:check
pnpm partman:maintain        # manually run monthly partition maintenance

7. xAPI Testing​

  • Public conformance fixtures in fixtures/xapi/.
  • pnpm xapi:post fixtures/xapi/passed.json posts a statement.
  • pnpm xapi:query provides a REPL over the xAPI surface.

8. Debugging​

  • pnpm attempt:inspect <id> — dump attempt + all statements.
  • pnpm partition:list — show partition status.
  • pnpm outbox:tail — watch outbox publisher activity.