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>

.env.erosi.example

@@ -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_REALM=your-realm
-PUBLIC_KEYCLOAK_CLIENT_ID=colectivo-web
+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) ──────

CLAUDE.md

@@ -166,14 +166,15 @@ Defined in `keycloak/realm-export.json` and `supabase/seed.sql`. All use passwor
 - Test the shopping session mode on a real iPhone during development, not only in DevTools.
 
 **Traefik (prod) — WebSocket for Realtime:**
-- Traefik routes `Host(erosi.limonia.net) && PathPrefix(/rest/v1, /auth/v1, /realtime/v1, ...)` to Kong via Docker-provider labels (priority 100); everything else on the same host falls through to the SvelteKit app (priority 1). Routing lives on the `kong` and `app` services' `labels:` block in `infra/docker-compose.erosi.yml` — no Traefik config files.
+- Traefik routes `Host(erosi.limonia.net) && PathPrefix(/rest/v1, /auth/v1, /realtime/v1, ...)` to Kong via Docker-provider labels (priority 100); everything else on the same host falls through to the SvelteKit app (priority 1). Routing lives on the `kong` and `app` services' `labels:` block in `infra/docker-compose.erosi.yml` — no Traefik config files. NetBird's self-hosted installer (≥ v0.65) deploys Traefik with `--providers.docker=true` + `--providers.docker.exposedByDefault=false`, so our labeled services are auto-discovered on the `netbird_netbird` Docker network.
-- The HTTPS entrypoint must set `--entryPoints.websecure.transport.respondingTimeouts.idleTimeout=3600s` in Traefik's static config (NetBird-managed container — edit once when setting up). Default is ~180s; without the bump, Realtime WebSockets drop mid-shopping-session and the client reconnects continuously.
+- The HTTPS entrypoint needs `respondingTimeouts.idleTimeout` set to either `0` (unlimited, NetBird's default) or `≥3600s`. At the default ~180s, Realtime WebSockets drop mid-shopping-session and the client reconnects continuously. Verify with `docker inspect netbird-traefik --format '{{range .Args}}{{.}}{{"\n"}}{{end}}' | grep idleTimeout`.
 - Traefik auto-sets `X-Forwarded-{Proto,Host,Port,For}` when `tls.certresolver` is configured on the router, so no extra middleware is needed for the app.
 - CSP `connect-src` must include both `https://erosi.limonia.net` and `wss://erosi.limonia.net`.
 
 **External Keycloak:**
 - Keycloak runs outside this stack; `PUBLIC_KEYCLOAK_URL` in `.env` points at it. Whatever proxy sits in front of it must forward `X-Forwarded-{Host,Port,Proto}` or Keycloak builds redirect URIs with internal ports and the OIDC flow breaks — that's the external operator's concern, not ours.
-- The realm + client configuration required on the external Keycloak is documented in `docs/deployment.md` and mirrored in `keycloak/realm-export.erosi.json` (kept as reference; not imported by this stack).
+- The realm + client configuration required on the external Keycloak is documented in `docs/deployment.md` and mirrored in `keycloak/realm-export.erosi.json` (kept as reference; not imported by this stack). Realm name, client id, and client secret are operator-chosen and wired in via `.env` — the file's literal `colectivo-web` / `colectivo` values are illustrative, not required.
+- **Legacy Keycloak `/auth/` base path**: Keycloak ≤ 16 (and some later distributions) serve realms under `/auth/realms/...` instead of `/realms/...`. In that case `PUBLIC_KEYCLOAK_URL` must include the suffix, e.g. `https://auth.example.com/auth`. Symptom of a missing `/auth` suffix: `GOTRUE_EXTERNAL_KEYCLOAK_URL/...well-known/openid-configuration` returns 404; the Supabase login redirect lands on a Keycloak error page. Verify before deploying: `curl -I ${PUBLIC_KEYCLOAK_URL}/realms/${PUBLIC_KEYCLOAK_REALM}/.well-known/openid-configuration` must return 200.
 
 **Supabase Realtime self-hosted:**
 - Check `MAX_REPLICATION_SLOTS` in PostgreSQL and `REALTIME_MAX_CONNECTIONS` before going to production.

docs/deployment.md

@@ -7,20 +7,16 @@ Live URL: **https://erosi.limonia.net** (app + Supabase API, single-domain). Key
 - `infra/docker-compose.erosi.yml` — full stack (db, auth, rest, realtime, storage, imgproxy, kong, app). `studio`, `meta`, and the bundled `keycloak` service are intentionally absent. `kong` and `app` attach to two Docker networks: `colectivo` (internal, for DB and inter-service traffic) and `traefik` (external, named via `${TRAEFIK_NETWORK}` — the Traefik instance that NetBird's self-hosted installer deployed).
 - **Reverse proxy**: Traefik owns ports 80 + 443 on ambrosio. It discovers our services via `traefik.*` labels (Docker provider): `erosi-kong` (priority 100) catches `/rest/v1`, `/auth/v1`, `/realtime/v1`, `/storage/v1`, `/graphql/v1`, `/pg` on `erosi.limonia.net` → `kong:8000`; `erosi-app` (priority 1) catches everything else on the same host → `app:3000`. TLS via Traefik's certresolver (`${TRAEFIK_CERTRESOLVER}`, defaults to `letsencrypt`). No container binds a host port.
 - `infra/scripts/deploy-erosi.sh` — idempotent redeploy: rsync → on first run generate secrets + write `/opt/colectivo/.env` with placeholders the operator fills in (`PUBLIC_KEYCLOAK_URL`, `KEYCLOAK_CLIENT_SECRET`, `TRAEFIK_NETWORK`) → subsequent runs fail fast if any placeholder is unfilled → docker compose build + up → apply pending migrations. Never touches `/etc/caddy/*`, never runs `sudo`.
-- `keycloak/realm-export.erosi.json` — **not imported** by this stack (no bundled Keycloak). Kept as reference for what the external Keycloak's `colectivo-web` client must have: `redirectUris: ["https://erosi.limonia.net/*", "https://erosi.limonia.net/auth/v1/callback"]`, `webOrigins: ["https://erosi.limonia.net"]`, confidential client, `openid` as a default client scope with `include.in.token.scope=true`.
+- `keycloak/realm-export.erosi.json` — **not imported** by this stack (no bundled Keycloak). Kept as reference for what the external Keycloak client must have — realm name, client id, and client secret are operator-chosen and wired in via `.env` (`PUBLIC_KEYCLOAK_REALM`, `PUBLIC_KEYCLOAK_CLIENT_ID`, `KEYCLOAK_CLIENT_SECRET`), so the file's literal `colectivo-web` / `colectivo` values are illustrative, not required. What the client must actually have: `redirectUris: ["https://erosi.limonia.net/*", "https://erosi.limonia.net/auth/v1/callback"]`, `webOrigins: ["https://erosi.limonia.net"]`, confidential, `openid` as a default client scope with `include.in.token.scope=true`.
 - `.env.erosi.example` — committed template. The real `/opt/colectivo/.env` on ambrosio is 600 and stays on the server.
 
 ## Pre-deploy prerequisites
 
-1. **External Keycloak** reachable from ambrosio's Docker network (outbound HTTPS). Realm + `colectivo-web` client configured as described above; operator pastes the client secret into `.env` as `KEYCLOAK_CLIENT_SECRET`.
+1. **External Keycloak** reachable from ambrosio's Docker network (outbound HTTPS). Realm + confidential client configured as described above; `.env` gets `PUBLIC_KEYCLOAK_URL`, `PUBLIC_KEYCLOAK_REALM`, `PUBLIC_KEYCLOAK_CLIENT_ID`, `KEYCLOAK_CLIENT_SECRET`. **If the Keycloak deployment uses the legacy `/auth/` base path** (Keycloak ≤ 16 default; some distributions still carry it — `auth.fosil.eu` is one) then `PUBLIC_KEYCLOAK_URL` must include it, e.g. `https://auth.example.com/auth`. Verify by opening `${PUBLIC_KEYCLOAK_URL}/realms/${PUBLIC_KEYCLOAK_REALM}/.well-known/openid-configuration` — it should return 200 JSON; 404 means the base path is wrong.
 2. **Users in the external Keycloak must match existing `auth.users` UUIDs** (`auth.users.id = keycloak sub`) or the stack starts fresh with no prior users. Re-registering produces new sub UUIDs; either re-seed `auth.users` + `auth.identities` or wipe and start over.
-3. **NetBird's Traefik long-idle-timeout** on the HTTPS entrypoint — required for Realtime WebSockets. Add to the Traefik container's args:
+3. **Traefik idle timeout on the HTTPS entrypoint** — NetBird's installer sets `--entryPoints.websecure.transport.respondingTimeouts.idleTimeout=0` (unlimited) by default, which is what Realtime WebSockets need. Verify with `docker inspect netbird-traefik --format '{{range .Args}}{{.}}{{"\n"}}{{end}}' | grep idleTimeout`. If it's not `0` or `≥3600s`, bump it — otherwise active shopping sessions disconnect.
-   ```
-   --entryPoints.websecure.transport.respondingTimeouts.idleTimeout=3600s
-   ```
-   Default is ~180s; active shopping sessions disconnect without this. One-time change outside this repo.
 4. **DNS** for `erosi.limonia.net` → ambrosio (A/AAAA).
-5. **Host Caddy disabled**. The previous deploy used a systemd Caddy as TLS terminator; it must be stopped and `systemctl disable caddy` so it doesn't race Traefik for 80/443 on reboot. Remove any `# BEGIN colectivo-erosi … # END colectivo-erosi` block from `/etc/caddy/Caddyfile` for tidiness.
+5. **Host Caddy disabled**: `sudo systemctl stop caddy && sudo systemctl disable caddy`. Without `disable`, the unit comes back on reboot and races Traefik for 80/443. Remove any `# BEGIN colectivo-erosi … # END` block from `/etc/caddy/Caddyfile` for tidiness.
 
 ## Prod-specific fixes
 
@@ -29,6 +25,39 @@ Had to be made for the stack to boot cleanly on a fresh volume:
 - `infra/db-init/00-role-passwords.sh` — rewrote as idempotent bootstrap (see the "supabase/postgres doesn't bootstrap Supabase roles" gotcha in `CLAUDE.md`): creates all Supabase service roles if absent, enables `pg_cron` + `pgcrypto` + `uuid-ossp`, creates `auth` / `storage` / `graphql_public` / `_realtime` / `realtime` schemas + empty `supabase_realtime` publication, sets `supabase_auth_admin` search_path to `auth`. The old `00-role-passwords.sql` (ALTER-only) has been removed.
 - `apps/web/vite.config.ts` — PWA strategy switched `injectManifest` → `generateSW` (see the "injectManifest hardcoded filename" gotcha in `CLAUDE.md`).
 
+## Runbook
+
+### App build hang / PostHog timeout
+The `app` image's final build stage (`pnpm --filter @colectivo/web build` → vite SSR) occasionally stalls during `transforming...` and ~9 minutes later dies with `UnhandledPromiseRejection: "Timeout while shutting down PostHog"`. Intermittent; reproducible across rebuilds with the same layer cache.
+
+Fix: rebuild with `--no-cache` once:
+```sh
+ssh ambrosio 'cd /opt/colectivo && docker compose --env-file .env -f infra/docker-compose.erosi.yml build --no-cache app'
+```
+Subsequent normal builds succeed. Run inside `tmux` if you're on a flaky SSH link — the no-cache build takes 5–15 minutes and losing the connection kills BuildKit.
+
+### Changing `PUBLIC_*` env values (URL, realm, client id)
+Any change to `PUBLIC_APP_URL`, `PUBLIC_SUPABASE_URL`, `PUBLIC_KEYCLOAK_URL`, `PUBLIC_KEYCLOAK_REALM`, `PUBLIC_KEYCLOAK_CLIENT_ID` requires an **app rebuild** (those values are baked into the client bundle at build time via `docker-compose.erosi.yml` build args). After editing `.env`:
+```sh
+ssh ambrosio 'cd /opt/colectivo && docker compose --env-file .env -f infra/docker-compose.erosi.yml build app && docker compose --env-file .env -f infra/docker-compose.erosi.yml up -d'
+```
+`KEYCLOAK_CLIENT_SECRET` is runtime-only (GoTrue reads it) — for that one a `docker compose restart auth` is enough.
+
+### Wipe all app + auth data (keep schema, keep migrations)
+When switching Keycloak realms or starting fresh:
+```sql
+BEGIN;
+TRUNCATE TABLE public.notes, public.tasks, public.task_lists,
+  public.shopping_items, public.shopping_lists, public.item_frequency,
+  public.collective_invitations, public.collective_members, public.collectives,
+  public.users
+  RESTART IDENTITY CASCADE;
+TRUNCATE TABLE auth.refresh_tokens, auth.sessions, auth.identities, auth.users
+  RESTART IDENTITY CASCADE;
+COMMIT;
+```
+CASCADE also empties `auth.mfa_factors`, `auth.mfa_amr_claims`, `auth.mfa_challenges`, `auth.one_time_tokens` — expected. Never touch `auth.schema_migrations` or `public._applied_migrations` (they track what DDL has been applied).
+
 ## Not yet configured on ambrosio
 
 - SMTP (Resend)