supabase-selfhost-ops: Instructions file for Codex

Ansible-Supabase — AI Context

Purpose

Deterministic, configuration-based Ansible deployer for self-hosted Supabase with optional components (Caddy SSO, monitoring, fail2ban, backups, UFW, LUKS).

Workflow

config.yml  ──>  setup.sh  ──>  env/supabase.yml  ──>  ansible-playbook
                                        │
                              playbook-supabase.yml
                              (regenerated from component toggles)

The user edits only config.yml (copy of config.example.yml). setup.sh validates, renders env vars into env/supabase.yml, regenerates playbook-supabase.yml, then runs install.sh (which bootstraps Ansible and executes the playbook).

Key Files

File	Purpose
config.example.yml	User-facing template — add new config fields here
config.yml	Actual config (gitignored) — single source of truth
setup.sh	Orchestrator: validates, renders secrets, writes env vars
env/supabase.yml	Ansible vars file — rendered by setup.sh, consumed by playbook
playbook-supabase.yml	Generated playbook — roles enabled/disabled by component toggles
install.sh	Ansible runner (pip install + ansible-playbook)

Roles (roles/)

Each role follows Ansible convention:

• tasks/main.yml — idempotent deployment logic
• defaults/main.yml — default variables
• templates/ — Jinja2 templates

Role: docker

Installs Docker Engine (official APT repo), docker-compose-plugin, and adds deploy_user to the docker group. Always runs first as a prerequisite.

Role: supabase

Clones the official Supabase repo, renders the Docker Compose stack, configures the API gateway (Envoy by default, api-gw/supabase-envoy; a Kong fallback override docker-compose.kong.yml is also rendered but not active by default), sets up SSL certs (from Caddy or self-signed), and starts all Supabase services (Postgres, GoTrue, PostgREST, Realtime, Storage, Edge Functions, Studio, etc.). Templates: docker-compose-supabase.yml.j2, docker-compose-kong.yml.j2 (Kong fallback override), docker-compose-logs.yml.j2 (Logflare + Vector log-drain override, see below), vector-logs.yml.j2 (<supabase_path>/volumes/logs/vector.yml — Vector pipeline that routes container logs to Logflare, container names templated with the deploy_env suffix), kong-supabase.yml.j2 (Kong declarative config, used by the fallback), the four Envoy configs (envoy.yaml.j2, cds.yaml.j2, lds.template.yaml.j2, docker-entrypoint.sh.j2), env-supabase.j2, start-supabase.sh.j2.