Minimal Setup

The fastest way to fill these in is npm run setup, run from backend/. It copies each .env.example to .env, generates AUTH_SECRET, INTERNAL_API_TOKEN and ADMIN_MCP_API_KEY, writes the shared two identically to both files, and refuses to overwrite a .env that already exists. Edit the result rather than writing the files by hand.

What follows is the least those two files need for the local path (backend and frontend on your machine, Postgres from docker compose up -d postgres on port 5433), signing in with OAuth only: no magic links, no production hardening.

backend/.env

PORT=4000
DATABASE_URL=postgresql://postgres:postgres@localhost:5433/crabstack
NODE_ENV=development
ALLOWED_ORIGINS=http://localhost:3000
AUTH_SECRET=<openssl rand -base64 32>
ADMIN_MCP_API_KEY=<openssl rand -base64 32>
INTERNAL_API_TOKEN=<openssl rand -base64 32>
[email protected]

Running your own Postgres on 5432 instead? Create a crabstack database in it and use postgresql://postgres:postgres@localhost:5432/crabstack.

frontend/.env

NEXT_PUBLIC_API_URL=http://localhost:4000
NEXT_PUBLIC_SITE_URL=http://localhost:3000
AUTH_URL=http://localhost:3000
INTERNAL_API_URL=http://localhost:4000
INTERNAL_API_TOKEN=<same as backend>
AUTH_SECRET=<same as backend>
AUTH_GITHUB_ID=<from github>
AUTH_GITHUB_SECRET=<from github>

No EMAIL_* lines: magic links are off here, and an EMAIL_* value set without EMAIL_SERVER_HOST is a partial config that fails boot in production. The .env that npm run setup writes keeps the MailDev EMAIL_* block from frontend/.env.example; delete the whole block, not part of it, to turn magic links off. GitHub credentials: OAuth providers.