Run the backend locally

The backend is an Encore.ts application that ships every microservice in a single repo. Encore handles the Postgres containers, the API gateway, and live reload for you.

1. Install dependencies

cd backend
npm install

Why npm here?

The backend uses npm because the Encore CLI shells out to it during type generation. The frontend and docs use Bun — they live in their own folders so the package managers do not collide.

2. Configure local secrets

Encore reads local-only secrets from backend/.secrets.local.cue. Copy from the example or create your own:

// backend/.secrets.local.cue
ResendAPIKey: "re_your_resend_test_key"
AdminEmail:   "admin@n2e.local"
AdminPassword: "ChangeMe!2026"
WebURL:       "http://localhost:3000"

Secret	Purpose
ResendAPIKey	Transactional email (verification codes, password resets). Get a key at https://resend.com — the free tier covers local dev.
AdminEmail	Email of the seed admin created by POST /seed/admin.
AdminPassword	Password of the seed admin.
WebURL	Base URL used in outgoing emails (must match the frontend).

The file is git-ignored — do not commit it.

3. Start Encore

encore run

You should see something like:

Building Encore application graph...
Analyzing service topology...
Starting Encore application...

Encore development server running!

Your API is running at:     http://127.0.0.1:4000
Development Dashboard URL:  http://localhost:9400/n2e-aq92

Endpoint	What it is
http://127.0.0.1:4000	The API gateway — every service is reachable here.
http://localhost:9400	The Encore local dev dashboard — service graph, traces, API explorer, log stream.

The first boot pulls and starts a Postgres Docker container per service database. Subsequent boots are fast.

4. Verify it works

In a second terminal:

curl http://127.0.0.1:4000/auth/signup \
  -H 'Content-Type: application/json' \
  -d '{"email":"test@n2e.local","password":"TestPass!2026","fullName":"Test","role":"admin"}'

You should get a JSON response with a new user object.

5. Run database migrations

Each service has its own database and its own Drizzle config. Migrations are auto-applied by Encore on encore run, but to generate new ones after editing a schema:

# Example: regenerate auth migrations after editing backend/auth/schema.ts
npx drizzle-kit generate --config=drizzle-auth.config.ts

The same pattern works for every drizzle-*.config.ts in backend/.

6. Tests

encore test

This boots a separate test database, runs the suite and tears down on exit.

Common issues

Symptom	Fix
docker: command not found	Start Docker Desktop first.
Port 4000 already in use	Stop any existing encore run or change the port via encore run --port 4001.
permission denied for table users	Drop the local DB: encore db reset auth and re-run.
Slow first boot	Encore is pulling encoredotdev/postgres:15. Subsequent boots use the cached image.

Continue to Run the frontend.