Files
faunosteo/docs/development/TRIAL_STACK.md
T
bchanot d3bdbbe0ba fix(supabase): db:trial closure review fixes
Strict absent detection (stderr sentence per kind, measured on Docker 29.9.3), tri-state container_running, empty-volume check before restore, quieter DB init and rotation logging, backup/migrate refuse while the app runs, lock first in start/stop, truthful rotate-secrets and post-create checks. Stub reproduces Docker's stdout/stderr split. Harness 364/0.
2026-11-11 14:16:32 +01:00

177 lines
13 KiB
Markdown

# Dedicated manual trial stack: technical plan
Status: IMPLEMENTED 2026-11-10 (scripts and environment-free checks, lots committed 2026-11-09 and 2026-11-10), NOT
CREATED: the stack is created only after the owner's explicit go (brief « Après R0 — Implémentation technique de la
pile d'essai dédiée »). Design from the briefs « V1-2.6 UX — Arbitrages du premier essai propriétaire » §5,
« R0 — Décisions propriétaire et dernière validation graphique » (BDR-108) and « R0 — Verdict de revue graphique
propriétaire » (BDR-109). Operating guide: `SUPABASE.md` §5.2. 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 new values wait in `secrets.next.env` (600) until the commit is
known, and the previous secrets stay in the backup taken just before (no `secrets.prev` file); account passwords
are untouched. Both commands print no secret. Rules (A14, decided 2026-11-09): keys valid one year on this dedicated local stack
only; no secret in Git, in a command line, in the script's output or in a log (the state folder sits outside the
repository and the script refuses one inside it); the rotation procedure is written in the script's help and in
`SUPABASE.md`; the renewal code gets a security review (fresh security gate) before the stack is used. 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 (decided 2026-11-09, A13): technical platform role `admin` and the
catalogue right `sheet_editor`; no `owner`, no `sheet_reviewer`, no `sheet_publisher`. The `admin` role is there
only because rule O1 activates `sheet_editor` for a platform admin alone
(`supabase/migrations/20261028100000_sheet_access_hardening.sql:199`); O1 is not changed. This is a trial
account, not a production practitioner profile: a production practitioner holds neither `admin` nor a catalogue
editing right by default.
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 | RATIFIED: `pnpm db:trial`, `faunosteo_trial_`, 58xxx and 5194 as in 3.2. |
| 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); practitioner = technical `admin` + `sheet_editor`, not a production profile; O1 unchanged. |
| A14 | Key lifetime and renewal | DECIDED: one year, documented rotation, no secret in Git or logs, security review of the renewal (3.3). |
| A15 | Backup before every `migrate` | RATIFIED: automatic, kept in the state folder, never pruned without the owner. |
## 7. Implementation (2026-11-10)
`scripts/db-trial.sh`, `scripts/db-trial-check.sh`, the suites' guard `packages/supabase/tests/sandbox/target.ts`.
Owner choices made at implementation (contract `.claude/tasks/contracts/2026-11-09-db-trial-stack-1809.md`):
cold physical backups (both volumes and the secrets, the stack stopped a few seconds) and a `restore` command
instead of `pg_dump -Fc` (§3.4); a read-only `plan` command; `db-sandbox.sh` gains a state-folder guard only, no
shared helper file (§4), and `db-trial.sh` pins its own images; GoTrue's public sign-up closed. Also: the gateway
refuses `/auth/v1/admin/`; `grant owner|admin` follows §5.7.1 of the V1-2 contract (factors first, typed
confirmation, audit row); catalogue rights mirror `public.grant_catalog_right` (admin first, no implicit admin
role), and every grant asks a typed confirmation. After the plan challenge (2026-11-10): `account`, `grant`,
`restore` and `destroy` need a terminal; the app host is decided at each run, not recorded (§3.2); `start`
recreates a missing container; backups check free space, list each archive back and write checksums last, and
`restore` and `destroy` never remove a volume without a backup of it: `destroy` refuses without a restorable
backup of what it would remove and names the manual removal commands; the stub harness is run by hand, not by
`check:all` (it reads the host's real ports). R13 (owner 2026-11-10): the shared trial dev server serves exactly
one of two listed stacks (`apps/app/vite/trial-targets.ts`), and `db-trial.sh` checks each operation's target and
every key it hands over (`SUPABASE.md` §5.2). Known limit: `app` takes no lock, so a `stop`, `backup`, `migrate`, `destroy`, `restore`
or rotation run in another terminal just before Vite listens goes ahead (`SUPABASE.md` §5.2). The tests of §5 that
create a stack under a test prefix were not run (owner brief: environment-free checks only); the stub harness
replaces them until the first `create`.