Files
faunosteo/docs/development/TRIAL_STACK.md
T

10 KiB

Dedicated manual trial stack: technical plan

Status: PROPOSAL, 2026-11-09 (owner brief « V1-2.6 UX — Arbitrages du premier essai propriétaire », §5), with the decisions of the brief « R0 — Décisions propriétaire et dernière validation graphique » (2026-11-09, BDR-108): name pnpm db:trial, two trial accounts, db:sandbox trial* kept for now, isolation from the suites, volumes preserved, resources capped, secrets renewable. Plan only: no stack is created, started, reset or removed, no script changes, existing data untouched. Implementation needs its own owner authorisation. Companion of V1-2-6_U1_CORRECTIONS.md.

1. Why

The owner's first trial (2026-11-09) ran on the automated sandbox through pnpm db:sandbox trial (scripts/db-sandbox.sh:386-453). The sandbox then held 219 official sheets, 217 of them made by the e2e and vitest suites, a working copy left by a suite, and seven versions with a fictitious fingerprint. The owner chose a persistent manual stack that no automated suite touches.

2. Today's setup (facts the plan builds on)

  • The sandbox: containers and network faunosteo_dbsandbox_* (db-sandbox.sh:47-56), loopback ports 57xxx (:59-60), no Docker volume (:2-6; checked 2026-11-09: neither the Postgres nor the Storage image declares one, data lives in the containers until down). Secrets in ~/.cache/faunosteo-db-sandbox/secrets.sh, generated at each up (:93-119), keys valid 30 days (:101).
  • Seeds: supabase/config.toml:44 lists seed.sql (three accounts with the public DEV password, seed.sql:5) and seed/anatomical-sheets/equine/draft/equine_draft.sql (the historical equine sheet).
  • How suites reach a stack: vitest and Playwright get endpoints and keys only from with_sandbox_env (db-sandbox.sh:270-276); packages/supabase/tests/sandbox/stack.ts:11-26 throws without them; the e2e app is built against a fake origin replayed onto those URLs (apps/app/e2e/support/sandbox.ts:11-40); e2e dev servers on 5191 and 5192.
  • The trial app: Vite with apps/app/vite/trial.config.ts, which takes the gateway URL and the host from its environment and refuses anything but http://127.0.0.1:<port> and a private IPv4 (:12-25).
  • DEV: supabase_*_faunosteo, ports 54321 to 54324 on all interfaces.
  • Measured on 2026-11-09 (docker stats): sandbox about 620 MiB (PostgREST 280, Postgres 185, Storage 105), DEV about 545 MiB; host 14.7 GiB RAM, 16 CPUs. Ports 58000 to 58999 and 5194 free (ss -ltn).

3. Design

3.1 Containers, network, volumes

Prefix faunosteo_trial_: _db, _auth, _rest, _storage, _mail, _gateway; network faunosteo_trial_net; named volumes faunosteo_trial_db (Postgres PGDATA=/var/lib/postgresql/data) and faunosteo_trial_storage (Storage FILE_STORAGE_BACKEND_PATH=/mnt). Same images and versions as the sandbox (db-sandbox.sh:42-46). The sandbox's guard and removal name only faunosteo_dbsandbox_* (:242, :262-267), so pnpm db:sandbox up or down never sees the trial stack; the trial script acts only on its own prefix.

3.2 Ports (loopback only, app excepted)

Service Port
Postgres 127.0.0.1:58432
GoTrue 127.0.0.1:58999
PostgREST 127.0.0.1:58300
Storage 127.0.0.1:58500
Mailpit (UI) 127.0.0.1:58025
Gateway (/auth/v1, /rest/v1, /storage/v1) 127.0.0.1:58801
App (Vite, trial.config.ts) trial host:5194 (LAN address by default, 127.0.0.1 for host-only, same rule as trial_host, db-sandbox.sh:392-408)

Every start checks that each port is free and that the container publishes it on 127.0.0.1 only, as the sandbox gateway does (:422-423).

3.3 Secrets and state

~/.cache/faunosteo-trial/ (700, outside the repository, refused inside it as db-sandbox.sh:66-70 does): secrets.sh (600) with its own Postgres password, JWT secret, anon and service keys; env files per service (600), never argv. Generated once at creation; start never regenerates them (the database keeps the role passwords set at its first initialisation). Keys valid one year instead of 30 days, with a rotate-keys command that re-signs both keys with the same secret and restarts the services: a persistent stack with the sandbox's 30-day keys would lock itself out after a month. Full renewal (owner 2026-11-09) is rotate-secrets: a new JWT secret and new keys, new role passwords set in the database (alter role … password, values through psql variables, never argv), env files rewritten (600), services restarted in order, the previous secrets file kept as secrets.prev.sh (600) until the stack answers; account passwords are untouched. Both commands print no secret. Since every secret differs from the sandbox's, a suite that reached a trial port by mistake would be refused by GoTrue, PostgREST and Postgres instead of writing.

3.4 Persistence and lifecycle

  • create refuses when a container, the network or a volume of the prefix exists; runs migrations and the equine seed (3.5); leaves the stack running.
  • stop / start: docker stop / docker start of the same containers; data kept. Restart policy no: nothing starts at boot.
  • migrate: applies new migrations of the branch forward (supabase migration up --db-url), after an automatic backup; it stops when a migration already applied differs from its file (a file edited in place cannot be replayed on a persistent stack).
  • backup: pg_dump -Fc into ~/.cache/faunosteo-trial/backups/ and a tar of the storage volume mounted read-only; sizes printed.
  • destroy: the only removal path. It prints the inventory (containers, volumes, accounts, sheets, drafts, backups kept) and requires the typed confirmation of the stack name; under the owner's sandbox rule it is run only after the owner's go for that operation.

3.5 Content: accounts, the equine sheet and its drawings

  • Migrations of the branch, then equine_draft.sql only. Not seed.sql: its three accounts carry the public DEV password (seed.sql:5).
  • Trial accounts (owner 2026-11-09: two distinct accounts): account <email> creates a confirmed account through GoTrue's admin API, password at a hidden prompt (12 characters minimum), as cmd_trial_account does (db-sandbox.sh:457-472); grant <email> <right> as cmd_trial_grant (:476-496).
    1. Owner/admin account, for the administration trials: platform roles owner and admin, catalogue rights sheet_editor, sheet_reviewer, sheet_publisher.
    2. Practitioner account, for the normal journey: sheet_editor only, no owner, no reviewer or publisher right. Fact to weigh: today a sheet_editor right is active only for a platform admin (rule O1, supabase/migrations/20261028100000_sheet_access_hardening.sql:199), so this account also needs the admin role; without it, it can read the catalogue (catalog_reader) but not edit. Changing O1 is out of scope. Editing and Administration require a TOTP factor (aal2, same file :321-341), enrolled in Mon compte by each account.
  • The equine sheet: the seed gives the historical sheet its fixed id and private.historical_sheet_id() flags it (20261102100000_sheet_admin_reads.sql:56); it is the only official sheet at creation.
  • Its drawings: the existing tool pnpm assets:upload supabase/seed/anatomical-sheets/equine/draft (R5.5), through the trial gateway, the service key passed in its environment from the trial state file. The tool checks the seed rows and hashes, never overwrites, confirms after verification and can be rerun (scripts/sheet-assets-e2e.sh proves the rerun). No hand-written SQL, no copy from the sandbox, whose data is test data. The working copy is then made in the app (« Créer une copie de travail »).

3.6 No accidental access from the suites

  1. Suites read endpoints only from SANDBOX_* variables set by db-sandbox.sh from the sandbox's secrets; the trial script never exports them and refuses to run when one is set in its environment.
  2. A guard added to stack.ts: the container name must start with faunosteo_dbsandbox_ and every URL must be a 127.0.0.1 port of the sandbox list; any other value stops the suite before its first request.
  3. Distinct dev-server ports (5191, 5192 for e2e; 5193 sandbox trial; 5194 trial stack) with --strictPort.
  4. Distinct secrets (3.3) as the last barrier.

3.7 Memory and resources

Per container --memory, --cpus 1, --pids-limit: Postgres 1 GiB (shared_buffers 128 MB), PostgREST 384 MiB, Storage 256 MiB, GoTrue 128 MiB, Mailpit and gateway 64 MiB each: at most about 1.9 GiB, about 650 MiB expected from the sandbox figures. The Vite server is a host process: NODE_OPTIONS=--max-old-space-size=768. With DEV and the sandbox up, about 2 GiB of 14.7 GiB. DEV shares no name, port, network, volume or secret with the trial stack.

4. Commands (proposal, arbitration A11)

pnpm db:trial create | start | stop | status | migrate | backup | rotate-keys | rotate-secrets | app | account <email> | grant <email> <right> | assets | destroy, in a new scripts/db-trial.sh built on the sandbox script's functions (shared helpers extracted to one sourced file rather than copied).

Trial procedure once built: create, assets, account, grant (admin rights and catalogue rights), app, sign in, enrol TOTP, work; Ctrl+C stops the app, stop stops the stack and keeps everything.

5. What the implementation touches

scripts/db-trial.sh (new) and a shared helper file, package.json (one script), packages/supabase/tests/sandbox/ stack.ts (guard 3.6.2), vite/trial.config.ts reused unchanged, docs (SUPABASE.md §5, V1-2-6_OWNER_TRIAL.md, CLAUDE.md commands). Its tests create a stack under a test prefix and a temporary state folder and remove only what they created; shellcheck on both scripts.

6. Arbitrations

# Question Recommendation
A11 Command name, prefix, ports pnpm db:trial (RATIFIED), faunosteo_trial_, 58xxx and 5194 as in 3.2 (open).
A12 Fate of pnpm db:sandbox trial, trial-account, trial-grant DECIDED: kept for now, neither removed nor silently redirected.
A13 Trial accounts DECIDED: two accounts (3.5). Open: confirm the practitioner account takes admin because of O1.
A14 Key lifetime and renewal Renewal DECIDED (rotate-keys, rotate-secrets); one-year lifetime open.
A15 Backup before every migrate Automatic, kept in the state folder, never pruned without the owner.