ADR 0018 Unified Upstream Supabase Runtime

Context

FractalOps previously composed Supabase from three in-repository charts for the core APIs, Realtime, and Storage. Those chart sources are deleted. The stable Application identity remains supabase, while the Application source changes in place to the upstream chart. Studio must manage the same release as the APIs and database, never a separate release.

Decision

Run exactly one manual Argo CD Application, supabase, from the upstream stable community Helm chart through the environment Kustomize overlay. One Helm release named supabase contains Studio, Auth, PostgREST, Realtime, Storage, postgres-meta, and internal Kong. Do not add a second Application, a standalone Studio chart, a chart fork, or a custom Supabase operator.

Each Assembly revision pins the chart archive, upstream commit, and every enabled image digest. A six-hour stable-channel workflow may advance those pins only after repository contracts and live API-server dry-run pass; it never synchronizes the manual Application.

CloudNativePG owns PostgreSQL lifecycle and login roles. Backend migrations own schemas, grants, RLS, and data repair. SeaweedFS owns authenticated S3-compatible object storage. The Supabase chart’s PostgreSQL, MinIO, and durable PVCs stay disabled. Internal Kong stays because it implements Supabase API routing and auth plugins; Kubernetes ingress only exposes upstream API prefixes. Studio is exposed through Pomerium from the same release, so Kong’s / Studio fallback and /pg/ metadata route never reach the public API host. GraphQL stays disabled because the standard CNPG image does not provide pg_graphql; Assembly must not advertise a schema absent from Backend migrations.

Existing HMAC keys remain valid during the first manual rollout. Asymmetric signing is a separate, explicit rotation using Supabase’s official key-generation contract. Assembly never silently replaces signing keys or database passwords.

Portability and Manual Rollout

Manifests may depend on standard Kubernetes, Argo CD, External Secrets, CNPG, and SeaweedFS APIs. They may not encode host paths, node names, custom worker labels, or locally built controllers. platform/k8s/bootstrap_supabase.sh seeds the referenced OpenBao values and publishes only the supabase Application; synchronization remains a manual operator decision.

Before the first sync, require immutable images, a current CNPG backup, schema ledgers, node capacity, the SeaweedFS bucket, Realtime tenant health, authenticated object write/read, and rollback pins. Preserve the previous Storage data volume as a read-only migration source and perform its Argo ownership removal as a one-time orphan handoff. After copy and readback proof, remove that source explicitly and let normal server-side apply and foreground pruning own the release. Do not commit permanent Argo Force=true or Replace=true annotations to bypass immutable Storage fields.

Consequences

One Application and one upstream release own the complete Supabase API topology and Studio view. Native stack boundaries replace the deleted custom component charts. Rollback restores the prior Assembly pin; database migrations remain forward-only and ledger rows are never fabricated.

Revision History

2026-07-14: Accepted the single-release upstream Supabase direction.
2026-07-15: Kept the supabase Application identity, deleted custom charts, and defined the one-time Storage orphan handoff.