docs(dev): pin AUTH_URL to the tenant subdomain

Capture the redirect_uri gotcha from the live-stack smoke. .env.example pins AUTH_URL to acme.localhost:3000 with a long-form comment; README gets an 'AUTH_URL gotcha' callout. Refs: M5.1 follow-up
2026-05-19 16:05:45 +00:00
parent 3310a942f2
commit 8ab82c8b37
2 changed files with 18 additions and 3 deletions
@@ -38,6 +38,8 @@ make dev          # next dev on http://localhost:3000

 Seed login (from the dev-stack realm): `test@breakpilot.dev` / `test`.

+> **AUTH_URL gotcha:** Auth.js v5 builds the OAuth `redirect_uri` from `AUTH_URL` — not from the request Host header, even with `AUTH_TRUST_HOST=true`. For multi-tenant dev work, pin `AUTH_URL` to the subdomain you log in on (e.g., `http://acme.localhost:3000`); otherwise Keycloak rejects the token exchange with `invalid_grant: Incorrect redirect_uri`. In prod, orca-proxy passes the right host via `X-Forwarded-Host` and `AUTH_URL` is set to the apex (`https://breakpilot.com`).
+
 `make test` / `make lint` / `make typecheck` / `make build` run vitest / eslint / tsc / next build respectively.

 Env vars live in `.env.example`. Copy to `.env.local` for local overrides (gitignored).