collective-lists/docs/deployment.md

Deployment

Production stack — ambrosio (OVH VPS)

Live URL: https://erosi.limonia.net (app + Supabase API, single-domain). Keycloak is external — its URL is set via PUBLIC_KEYCLOAK_URL in /opt/colectivo/.env. OVH VPS, Ubuntu 24, Docker 29.

• 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.
• .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.
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:

   --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.

Prod-specific fixes

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).

Not yet configured on ambrosio

• SMTP (Resend)
• Automated backups — script exists at infra/scripts/backup.sh, not scheduled
• Lighthouse run against prod URL
• Final production icons