docs(deploy): runbook + fixes from the limonia.net cutover

Document what we learned doing the real NetBird+Traefik migration:

- Keycloak realm/client names are operator-chosen; the realm-export.json's
  literal "colectivo-web" / "colectivo" values are illustrative, not required.
- Legacy Keycloak /auth/ base path: PUBLIC_KEYCLOAK_URL must include the
  suffix when the deployment serves realms under /auth/realms/... (hit this
  on auth.fosil.eu). Verify with the discovery URL returning 200.
- NetBird's installer deploys Traefik with idleTimeout=0 (unlimited) by
  default — verify instead of prescribing 3600s.
- Runbook: --no-cache fixes the intermittent vite SSR "transforming..."
  hang that surfaces as a PostHog shutdown timeout.
- Runbook: any PUBLIC_* change needs an app rebuild (build args); secret
  changes only need `docker compose restart auth`.
- Runbook: TRUNCATE recipe for wiping all app + auth data while keeping
  schema + migration tracking intact.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
This commit is contained in:
2026-04-24 01:58:00 +02:00
parent 33b32cae4a
commit dee9ee8014
3 changed files with 49 additions and 13 deletions

View File

@@ -10,9 +10,15 @@ PUBLIC_SUPABASE_URL=https://erosi.limonia.net
# (GoTrue v2.158.1 doesn't send `openid` in the OAuth scope param — Keycloak
# must inject it), redirectUris including https://erosi.limonia.net/* and
# https://erosi.limonia.net/auth/v1/callback, and webOrigins https://erosi.limonia.net.
#
# NOTE: if your Keycloak uses the legacy `/auth/` base path (Keycloak ≤ 16 and
# some later distributions), PUBLIC_KEYCLOAK_URL must include it — e.g.
# https://auth.example.com/auth. Verify before deploying: a GET on
# ${PUBLIC_KEYCLOAK_URL}/realms/${PUBLIC_KEYCLOAK_REALM}/.well-known/openid-configuration
# must return 200 JSON. 404 = wrong base path.
PUBLIC_KEYCLOAK_URL=https://your-keycloak.example.com
PUBLIC_KEYCLOAK_REALM=colectivo
PUBLIC_KEYCLOAK_CLIENT_ID=colectivo-web
PUBLIC_KEYCLOAK_REALM=your-realm
PUBLIC_KEYCLOAK_CLIENT_ID=your-client-id
KEYCLOAK_CLIENT_SECRET=CHANGEME-paste-from-external-keycloak
# ── Traefik (deployed by NetBird's self-hosted installer on ambrosio) ──────