wild-directory/supabase/notes.md

Supabase Notes

Overview

Supabase is a multi-component application. All components run in the supabase namespace:

Component	Image	Role
db	supabase/postgres	PostgreSQL with Supabase extensions
kong	kong/kong	API gateway, entry point for all traffic
auth	supabase/gotrue	JWT-based authentication
rest	postgrest/postgrest	Auto-generated REST API from Postgres
realtime	supabase/realtime	WebSocket subscriptions
storage + imgproxy	supabase/storage-api + darthsim/imgproxy	File storage (imgproxy as sidecar)
meta	supabase/postgres-meta	DB introspection for Studio
studio	supabase/studio	Web dashboard (protected by Kong basic-auth)

Traffic flows: browser → Traefik → Kong (port 8000) → individual services.

First-Deploy Checklist

1. Add and deploy with: wild app add supabase && wild app deploy supabase
2. Wait for postgres to initialize (~2–3 min on first boot — it runs SQL init scripts)
3. Access the Studio at https://supabase.<your-domain> using the dashboard credentials
4. Replace example API keys before going to production (see below)

JWT Keys — MUST Replace for Production

The default jwtSecret, anonKey, and serviceRoleKey in secrets.yaml are Supabase's well-known example keys (publicly known, expire Jan 2027). They are sufficient for testing but must not be used in production.

Generate new keys using the built-in script:

wild app run supabase generate-keys

Then copy the output values into secrets.yaml and redeploy:

wild app deploy supabase

The postgres database stores the JWT secret in its settings (app.settings.jwt_secret). After replacing keys, the postgres pod must restart to pick up the new secret — a redeploy handles this.

Postgres — Internal Database

Supabase uses its own dedicated postgres instance (supabase/postgres image) rather than the shared Wild Cloud postgres app. This image includes:

• ~390 extensions pre-compiled (pgjwt, wal2json, vector, pg_net, etc.)
• Supabase service roles (supabase_admin, authenticator, supabase_auth_admin, supabase_storage_admin, etc.)
• Initialization scripts for realtime, webhooks, JWT settings

All Supabase service roles (auth, storage, realtime, etc.) use the same password as the postgres admin (dbPassword secret). This is the Supabase default behavior.

Bootstrap User: supabase_admin

POSTGRES_USER is set to supabase_admin (not postgres). This is required because the image's migrate.sh script connects immediately as supabase_admin before running any init scripts. Using POSTGRES_USER=postgres would make postgres the bootstrap superuser, which prevents migrate.sh from demoting it (PostgreSQL prohibits removing SUPERUSER from the bootstrap user).

With POSTGRES_USER=supabase_admin:

1. initdb creates supabase_admin as the bootstrap superuser
2. migrate.sh connects as supabase_admin and creates the postgres role
3. After init-scripts run, migrate.sh demotes postgres to non-superuser (this is Supabase's intended model)

The postgres user remains available with database-level privileges. All Supabase service roles use specific functional accounts (supabase_auth_admin, authenticator, etc.), not the postgres superuser.

Volume Mount: /var/lib/postgresql (parent dir)

The PVC is mounted at /var/lib/postgresql (the parent), NOT at /var/lib/postgresql/data (PGDATA). This is required because Longhorn's ext4 filesystem creates a lost+found directory, which blocks postgres initdb when the PVC is mounted directly at PGDATA. With the parent-dir mount, initdb creates /var/lib/postgresql/data as a subdirectory, leaving lost+found at the parent level where it doesn't interfere.

Realtime Tenant ID

The Realtime service must identify itself with the tenant ID realtime-dev. The Deployment sets spec.template.spec.hostname: realtime-dev so the Elixir application seeds itself with this tenant ID. The Kubernetes service for Realtime is also named realtime-dev so Kong can route to it correctly.

Storage

File storage uses the local filesystem backend by default. Objects are stored in the supabase-storage PVC. The imgproxy container is a sidecar in the same pod, sharing the storage PVC for image transformation.

For S3-backed storage: edit deployment-storage.yaml to change STORAGE_BACKEND to s3 and add S3 credentials as secrets.

SMTP

SMTP is required for auth email flows (email confirmation, password reset). Configure the smtp app dependency and it will be wired automatically. If you want to disable email confirmation during initial testing, you can temporarily set GOTRUE_MAILER_AUTOCONFIRM=true in deployment-auth.yaml.

Studio Dashboard Credentials

The Studio dashboard is protected by HTTP Basic Auth via Kong. Credentials:

• Username: configured via dashboardUsername config key (default: supabase)
• Password: auto-generated dashboardPassword secret

To view the generated password:

kubectl -n supabase get secret supabase-secrets -o jsonpath='{.data.dashboardPassword}' | base64 -d

Connecting Applications

Applications connect to Supabase via the Kong API gateway:

• REST API: https://supabase.<domain>/rest/v1/
• Auth: https://supabase.<domain>/auth/v1/
• Realtime: wss://supabase.<domain>/realtime/v1/
• Storage: https://supabase.<domain>/storage/v1/

Use the anonKey for client-side (browser) access and serviceRoleKey for server-side (admin) access.

Supabase JavaScript Client

import { createClient } from '@supabase/supabase-js'

const supabase = createClient(
  'https://supabase.<your-domain>',
  '<anonKey>'  // from secrets.yaml
)

Troubleshooting

Postgres won't start: Check that the supabase/postgres image can be pulled and that the PVC is bound.

Auth returns 500: Postgres is not ready or the init scripts haven't completed. Check DB pod logs and wait for all init SQL to finish.

Kong returns 401 for all requests: The anonKey in secrets doesn't match the jwtSecret. Regenerate keys with wild app run supabase generate-keys.

Realtime health check fails: The pod hostname may not be realtime-dev. Check the Deployment spec.template.spec.hostname field.

Studio shows "Project not found": Studio needs Kong to be healthy. Check Kong pod logs for declarative config errors.