Gebos/docs/adr/0003-vendored-supabase-compose-subset.md

ADR-0003: Vendor a trimmed Supabase compose stack against external Postgres

Date: 2026-07-08 Status: Accepted

Context

The Supabase stack on app-host was a placeholder skeleton. The official self-hosting bundle assumes its own bundled db container and ships nine+ services (realtime, storage, imgproxy, edge functions, supavisor pooler, Logflare analytics, …), most of which the UVI pilot does not use. Meanwhile our Postgres lives on a separate NixOS host (db-host) with TimescaleDB.

Kong deserves a note, since "why is it even there" came up: Kong is the single front door for api.gebos.online (Caddy → Kong on loopback :8000). It routes paths to internal services (/auth/v1 → GoTrue, /rest/v1 → PostgREST) and enforces the perimeter (key-auth + ACLs), so unauthenticated internet traffic never reaches the backends. Replacing it would mean re-implementing routing/auth/CORS in Caddy by hand instead of inheriting Supabase's tested config.

Decision

Vendor the upstream docker/docker-compose.yml (and kong.yml + kong-entrypoint.sh) into nix/supabase/, keeping only studio, kong, auth (GoTrue), rest (PostgREST), meta (postgres-meta), with these deviations — each also documented in the files' header comments:

1. No db service. Everything connects to ${POSTGRES_HOST}:${POSTGRES_PORT} (db-host); depends_on: db dropped.
2. No realtime / storage / imgproxy / functions / supavisor / analytics. Re-vendor from upstream when actually needed.
3. Studio binds to loopback only, and Kong's catch-all dashboard route is removed. Upstream fronts Studio with Kong basic-auth on /; we expose no route to it at all. Access is ssh -L 3000:127.0.0.1:3000 — possession of the SSH key is the credential. supabase_dashboard_password is therefore currently unused. The public API surface is exactly /auth/v1, /rest/v1, /graphql/v1 and two .well-known endpoints.
4. meta connects as supabase_admin, not postgres. Upstream's postgres role is its cluster superuser; on db-host postgres keeps a separate admin password, so supabase_admin (made SUPERUSER by ADR-0002) fills that role with the shared service password.
5. kong-entrypoint.sh is vendored byte-identical. Kong's declarative YAML cannot read env vars, so the entrypoint substitutes $VARS (the API keys) into the config at container start; keeping it unmodified makes re-vendoring a plain copy.

Variable layering (the answer to "where does POSTGRES_HOST come from"):

• non-secret deployment config (POSTGRES_HOST/PORT/DB, STUDIO_BIND) — systemd unit environment in gebos-supabase.nix, fed by module options;
• secrets (POSTGRES_PASSWORD, JWT_SECRET, ANON_KEY, SERVICE_ROLE_KEY) — sops-rendered EnvironmentFile;
• gebos constants (public URLs, org name) — hardcoded in the vendored compose.

Consequences

• Deliberately small attack surface and dependency set; Studio reachable only through SSH.
• Upstream updates are a re-copy plus re-applying the five listed deviations; all drift is concentrated in docker-compose.yml and kong.yml headers.
• GoTrue has no SMTP configured yet — magic-link login cannot send email until the SMTP_* secrets are added (TODO marked in the compose file).
• anon/authenticated still hold zero grants; PostgREST serves nothing until the RLS/grants migration lands (future ADR).