# Supabase: local stack, migrations, tests Status: Step 3 deliverable, extended at Step 4 (2026-10-08). Covers the foundation (profiles, platform roles, audit log) and the anatomical sheet tables (`ANATOMICAL_SHEET_MODEL.md`). Conventions: `BACKEND_ARCHITECTURE.md` §3–§9. ## 1. Layout ```text supabase/ ├─ config.toml CLI config (public schema exposed only, PG 17, strong passwords) ├─ migrations/ forward-only SQL, _.sql │ ├─ 20261008100000_foundation.sql schemas private/audit, updated_at, audit log │ ├─ 20261008100100_profiles.sql profiles + auth.users trigger + RLS │ ├─ 20261008100200_platform_roles.sql platform_role, profile_roles, helpers, RPCs │ ├─ 20261008110000_anatomical_sheets.sql species, sheets, immutable versions, assets, lifecycle RPCs │ ├─ 20261008110100_private_execute_hardening.sql EXECUTE revoked from PUBLIC on the Step 3 helpers │ ├─ 20261009100000_sheet_asset_storage.sql bucket anatomical-sheet-assets + read policy through the sheet │ ├─ 20261010100000_sheet_document_schema_v2.sql document schema 2: references, review_status, count_range checks │ ├─ 20261011100000_profiles_professional.sql practice_name, professional_title, siret │ └─ 20261013100000_files_foundation.sql assets table, seven private buckets, avatar policies through assets, purge queue, browser + worker RPCs (STORAGE.md) ├─ seed.sql LOCAL dev accounts + first owner (never run in prod) ├─ seed/anatomical-sheets/equine/ official equine sheet as a DRAFT, generated by `pnpm import:equine` │ ├─ legacy-sources/ the historical Horse.svg, Horse_head.svg, pathologies.json, vertebrae.ts (importer input) │ ├─ legacy-import/ baseline import (document, id map, SVG copies, IMPORT-REPORT.md), no SQL │ ├─ curation/ authored changes.json + references.json │ └─ draft/ curated working revision (document, horse.svg, sheet-ref.json, report-migration-map.json, CHANGELOG, REVIEW-REPORT, review/*.svg; bundled into the app with SHEET_BUNDLE=draft) + equine_draft.sql: idempotent, converging seed (sheet, 1 asset row, working draft), applied by db reset and by PGlite └─ tests/ pgTAP, one file per concern, allowed AND denied paths packages/supabase/ ├─ src/client.ts createBrowserClient() (anon key, PKCE) ├─ src/database.types.ts `supabase gen types` output ├─ src/anatomical-sheets.ts publishSheetVersion(): Zod + integrity gate before the RPC ├─ src/assets.ts avatar flow: begin / quarantine upload / confirm / remove / own state / download, closed AssetFailure kinds ├─ tests/db/ PGlite harness: runs the pgTAP files without Docker └─ tests/e2e/ real-stack end-to-end (avatar flow with the worker container), `pnpm e2e:avatar` packages/domain/ └─ src/anatomical-sheet/ canonical sheet document (Zod), validateSheetDocument, createEmptySheetDocument ``` ## 2. Prerequisites - Node 24 + pnpm via corepack (`WORKSPACE.md`). - Docker daemon reachable by your user for the real stack. If `docker info` says `permission denied ... docker.sock`, add yourself to the `docker` group and log in again: ```bash sudo usermod -aG docker "$USER" ``` - No Docker: the PGlite suite still runs (see §5), the CLI commands do not. The Supabase CLI is a root devDependency (`pnpm supabase `), pinned like every other tool. Never install it globally. ## 3. Start, stop, reset Every CLI call goes through `scripts/supabase.sh` (`pnpm db:*`, `pnpm supabase `): it exports the DEV origin that `config.toml` reads with `env()` (`api.external_url`, `auth.site_url`, `studio.api_url`). A direct `node_modules/.bin/supabase start` would leave the literal `env(...)` text in GoTrue's mail links. The CLI publishes API 54321, PostgreSQL 54322, Studio 54323 and Mailpit 54324 on `0.0.0.0` (no bind option); the host firewall closes 54322-54324 on the LAN interface and the DEV gateway serves Mailpit behind basic auth on 54325 (`ENVIRONMENTS.md` §3). ```bash pnpm db:start # supabase start: pulls images, applies migrations + seed, prints URLs and keys pnpm db:stop # supabase stop (keeps the volume) pnpm db:reset # drop + replay every migration + seed from zero ``` Local endpoints (`config.toml`): | Service | URL | | --------------------------------------- | --------------------------------------------------------- | | API (PostgREST, Auth, Storage) | `http://127.0.0.1:54321` | | PostgreSQL | `postgresql://postgres:postgres@127.0.0.1:54322/postgres` | | Studio | `http://127.0.0.1:54323` | | Mail catcher (confirmation / OTP mails) | `http://127.0.0.1:54324` | Addresses on the host itself. From another device of the network: app `:5173`, API `:54321`, Mailpit through the gateway `:54325` (basic auth); Studio by SSH tunnel; PostgreSQL not at all (`ENVIRONMENTS.md` §3). `pnpm db:start` prints the `anon` and `service_role` keys. Only the anon key ever reaches the browser. Containers, volumes and network are named `supabase__faunosteo` (`project_id` of `config.toml`): the CLI imposes this pattern, so the `faunosteo_` prefix convention of DEPLOY.md ("Docker resource naming") applies as a suffix here. Several projects can run side by side as long as their `project_id` and ports differ. Two kinds of seed (`config.toml [db.seed] sql_paths`): | File | Scope | Content | | -------------- | ----------------- | ------------------------------------------------------------------------------------------------------------------------------ | | `seed.sql` | local only | dev accounts + first owner | | `seed/…/*.sql` | every environment | versioned reference data, idempotent (today: the official equine sheet as a draft); each file listed explicitly in `sql_paths` | The PGlite harness applies every `.sql` under `seed/` after the migrations, `seed.sql` never (it needs the real auth schema); a test fails when a seed file is missing from `sql_paths`. On another environment, apply a versioned seed with `psql -f` from a privileged session, then upload its assets (§3.1). Never run `supabase db push --include-seed` against a shared database: the list also contains `seed.sql` and its known local password. ### 3.1 Sheet assets (Storage) SVG files live in the private bucket `anatomical-sheet-assets`, keyed by content (`.svg`). Reading goes through the sheet (policy `anatomical_sheet_assets_read`): a published version of a usable sheet, or any version for its editors. No API role uploads; the operator does, with the service key, from the generated seed folder: ```bash export SUPABASE_URL=http://127.0.0.1:54321 read -rs SUPABASE_SERVICE_ROLE_KEY && export SUPABASE_SERVICE_ROLE_KEY # typed, not in shell history pnpm assets:upload supabase/seed/anatomical-sheets/equine/draft ``` The script verifies each file against `assets.json` (sha256, size) before uploading, keeps objects already present, and calls `confirm_sheet_asset_upload` (service role only) for each asset row: the read policy ignores a row whose upload was never confirmed, so a user who registers a known hash on their own sheet opens nothing. ### 3.2 Files worker (Storage, Step 8) User files land in private buckets and are processed by the Rust worker (`crates/worker`, `docs/development/STORAGE.md`). Against the local stack: ```bash pnpm worker:image # faunosteo_worker:dev pnpm e2e:avatar # starts the container on supabase_network_faunosteo, runs tests/e2e, stops it docker compose --profile worker up worker # the same container from docker-compose.yml, reading .env.worker ``` `.env.worker` (not editable by the assistant): `SUPABASE_URL=http://supabase_kong_faunosteo:8000`, `SUPABASE_SERVICE_ROLE_KEY=`, `WORKER_ID=dev`. The service key stays in that file and in the shell; it never reaches the app `.env`, env.js or a commit. Seed accounts (local only, password `LocalDev-only-password-1`): | Email | Role | | ----------------------- | ------------------------------------------- | | `owner@faunosteo.local` | platform owner (bootstrapped by `seed.sql`) | | `alice@faunosteo.local` | plain user | | `bob@faunosteo.local` | plain user | ## 4. Writing a migration 1. `pnpm supabase migration new ` creates `supabase/migrations/_.sql`. 2. A migration that adds a table adds, in the same file: RLS enable, explicit `revoke all ... from public, anon, authenticated` then the exact grants, separate SELECT / INSERT / UPDATE / DELETE policies, indexes, comments. 3. Add or extend a pgTAP file under `supabase/tests/`: the allowed path and every denied path (other user, anon, direct write bypassing an RPC). Scope counts to the fixture ids: on the real stack the seed accounts exist, in PGlite they do not. 4. `pnpm --filter @faunosteo/supabase test:run` (PGlite, seconds), then `pnpm db:reset && pnpm db:test` on the real stack. 5. `pnpm db:types` and commit `packages/supabase/src/database.types.ts`. 6. Never edit an applied migration. Corrections are new migrations. Rules enforced by the schema-types test for every future `public` table: RLS enabled, no `using (true)` / `with check (true)` policy for `anon` or `authenticated`. ## 5. Tests Two runners, one SQL source of truth (`supabase/tests/*.sql`, pgTAP): | Command | Engine | Needs Docker | What runs | | -------------------------------------------- | ------------------------------------------------ | ------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `pnpm --filter @faunosteo/supabase test:run` | PGlite (PostgreSQL 17 in WASM) | no | shim of the Supabase base schema (auth + storage tables) + all migrations + `seed/**` + every pgTAP file; schema ↔ types check; client factory; publish gate | | `pnpm db:test` | `supabase test db` (pg_prove in the local stack) | yes | the same pgTAP files against the real Supabase image | `pnpm test:run` at the root runs the PGlite suite together with the app suite. The shim (`packages/supabase/tests/db/supabase-shim.sql`) recreates the API roles, `auth.users`, `auth.uid()` and the permissive default privileges of Supabase so that a forgotten `revoke` fails a test. Two parity traps met so far: counts must be scoped to fixture ids (the real stack carries `seed.sql` rows), and `order by` on text must pin `collate "C"` (the real image sorts with a locale collation, PGlite with C). How a test impersonates a user (same technique in both runners): ```sql set local role authenticated; select set_config('request.jwt.claims', '{"sub":"","role":"authenticated"}', true); ``` ## 6. Generated types ```bash pnpm db:types # regenerate packages/supabase/src/database.types.ts (local stack running) pnpm db:types:check # CI: fail on any diff ``` The CLI emits unformatted TypeScript; both scripts pipe it through Prettier (repo config) so the committed file is stable byte for byte. The schema-types test checks tables, columns, enum labels and RPC argument names against the migrated schema, so a stale file fails before CI. ## 7. First platform owner in a real environment The RPCs refuse self-grants and need an existing owner or admin. The first owner is created once, from a privileged SQL session (service connection, `psql` on the host), never from the browser: ```sql select private.assign_platform_role(null, '', 'owner'); ``` The call is audited with a null actor. Afterwards every role change goes through `grant_platform_role` / `revoke_platform_role`. ## 8. Manual validation (Definition of Done: "an authenticated request hits a protected table safely") ```bash URL=http://127.0.0.1:54321 ANON= token() { # $1 = email curl -s -X POST "$URL/auth/v1/token?grant_type=password" \ -H "apikey: $ANON" -H "Content-Type: application/json" \ -d "{\"email\":\"$1\",\"password\":\"LocalDev-only-password-1\"}" | jq -r .access_token } ALICE=$(token alice@faunosteo.local); OWNER=$(token owner@faunosteo.local) ALICE_ID=10000000-0000-0000-0000-00000000000a # 1. alice reads exactly one profile (hers) curl -s "$URL/rest/v1/profiles?select=id,display_name" -H "apikey: $ANON" -H "Authorization: Bearer $ALICE" # 2. anon reads nothing (permission denied) curl -s "$URL/rest/v1/profiles" -H "apikey: $ANON" # 3. alice cannot deactivate herself (column privilege) nor self-grant admin curl -s -X PATCH "$URL/rest/v1/profiles?id=eq.$ALICE_ID" -H "apikey: $ANON" \ -H "Authorization: Bearer $ALICE" -H "Content-Type: application/json" -d '{"active":false}' curl -s -X POST "$URL/rest/v1/rpc/grant_platform_role" -H "apikey: $ANON" \ -H "Authorization: Bearer $ALICE" -H "Content-Type: application/json" \ -d "{\"target_user_id\":\"$ALICE_ID\",\"role\":\"admin\"}" # 4. the owner grants moderator to alice; the grant is audited curl -s -X POST "$URL/rest/v1/rpc/grant_platform_role" -H "apikey: $ANON" \ -H "Authorization: Bearer $OWNER" -H "Content-Type: application/json" \ -d "{\"target_user_id\":\"$ALICE_ID\",\"role\":\"moderator\"}" psql postgresql://postgres:postgres@127.0.0.1:54322/postgres \ -c "select actor_user_id, action, target_user_id, metadata from audit.audit_logs order by occurred_at" ``` Expected: 1 → one row; 2 → `42501`; 3 → both `42501`; 4 → a uuid, then two audit rows (bootstrap with null actor, grant by the owner). ## 9. Wiring the app Development: `pnpm dev` (`scripts/dev.sh`) sets `VITE_SUPABASE_URL` to the DEV origin (`http://:54321`, the LAN address of the machine: `ENVIRONMENTS.md` §2) and the anon key from `supabase status`; the app is served on `http://:5173` for every device of the private network. `pnpm dev:offline` runs the local tool without backend. Docker deployments use `.env`: ```bash APP_SUPABASE_URL= APP_SUPABASE_ANON_KEY= # public by design ``` Both empty keeps the app in its local-only mode: `getSupabaseClient()` returns null, the auth screens show an "unavailable" notice and `/app` redirects to `/login`. `APP_AUTH_PROVIDERS` / `VITE_AUTH_PROVIDERS` (`google,apple`) lists the OAuth buttons to show. Sign-in, sign-up, email confirmation, password recovery, the `/app` shell and Mon compte are documented in `IDENTITY.md` (routes, session handling, provider setup, MFA gap, manual validation). ## 10. Self-hosted parity The local stack runs the same images as a self-hosted deployment (`supabase/docker` compose), so migrations, policies and tests transfer unchanged. The self-hosted runbook (VPS sizing, secrets, backups, TLS) is a separate deliverable once the hosting question (OPEN_QUESTIONS Q2) is settled; it reuses `pnpm supabase db push --db-url <...>` for migrations.