Owner brief of 2026-11-09 after the first U1 trial. Boards 23-30 (proposal), lots R0-R4 with arbitrations A1-A15, persistent trial stack plan. No code.
139 lines
9.0 KiB
Markdown
139 lines
9.0 KiB
Markdown
# Dedicated manual trial stack: technical plan
|
|
|
|
Status: PROPOSAL, 2026-11-09 (owner brief « V1-2.6 UX — Arbitrages du premier essai propriétaire », §5). 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. 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: `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), plus the platform role `owner` if the owner wants the rights screen (arbitration A13).
|
|
Administration then asks for a TOTP factor, enrolled in Mon compte.
|
|
- 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 | 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`, `faunosteo_trial_`, 58xxx and 5194 as in 3.2. |
|
|
| A12 | Fate of `pnpm db:sandbox trial`, `trial-account`, `trial-grant` | Removed once the trial stack is validated: one trial path. |
|
|
| A13 | Platform roles of the owner's trial account | `admin` with the catalogue rights, plus `owner` only if the rights screen is part of the trial. |
|
|
| A14 | Key lifetime | One year, with `rotate-keys`. |
|
|
| A15 | Backup before every `migrate` | Automatic, kept in the state folder, never pruned without the owner. |
|