npm run dev:emulator). External providers are stubbed by default for safety.
Profile summary
Encore itself is not containerized for local dev — run
cd api-events && npm run dev:emulator after infra is up.
Dev infra (default)
Starts Postgres, Azurite, the Clerk emulator, and the Cleo Pay emulator without any API container.What runs
Compose file:
dev/docker-compose.yml (project name api, shared with legacy Go compose volumes).
Typical workflow
dev:emulator sets stub flags (TWILIO_USE_STUB_SMS, NOTIFICATIONS_DRY_RUN=true, etc.), points Clerk at :4711, and points Cleo Pay at :4092.
To exercise the member onboarding progress tracker, sign in as Indigo Onboarding and open /onboarding/org?orgId=org_plo9pyQatNovhdX8kXMRd6IjarB. The busy org seed has a 7-step flow with long titles; Indigo is mid-flow on step 4.
Ephemeral profile
Isolated Postgres (and supporting stubs) that resets on restart. Used by api-events integration tests and CI.Configuration
Use cases
npm run test:integration:setupthennpm run test:integrationin api-events- E2e / CI pipelines that need a clean database
- Running alongside dev infra (different network)
Environment files
Local secrets are gitignored.npm run dev:emulator bakes in the documented emulator values — you usually do not need a hand-edited .env for the default loop.
For deployed env inventory, see api-events operations.
Docker layout
:4000, not inside this compose file.
npm run dev:emulator also starts a webhook-only relay on :4093 so Docker emulators can reach Clerk/Cleo webhook paths without exposing the full API.
Common commands
Troubleshooting
Clerk personas missing after seed
Clerk personas missing after seed
Run
npm run db:seed:demo-full, then restart clerk-emulator. The emulator reads api-events/scripts/seed/manifest/local-personas.json.Port 5433 already in use
Port 5433 already in use
Another Postgres or stale compose project may hold the port:
Ephemeral data not persisting
Ephemeral data not persisting
By design — use dev infra (
npm run dev:infra) for persistent local data.