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.
177 lines
13 KiB
Markdown
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`.
|