From d4f628f8c834eae8e63a8f1e08469ac04341dafb Mon Sep 17 00:00:00 2001 From: bchanot Date: Sun, 25 Oct 2026 17:12:38 +0100 Subject: [PATCH] docs(docs): separate public 0.1.0 from develop in README and DEPLOY README splits the public 0.1.0, develop, DEV-only features and planned work. CHANGELOG states nothing under Unreleased is deployed. DEPLOY gets a status notice (historical, unverified, would-break, security prerequisites) and marks both CSP examples as not production-ready; fixes stay with RR-5. --- CHANGELOG.md | 7 ++++++ DEPLOY.md | 70 ++++++++++++++++++++++++++++++++++++++++++++++++++++ README.md | 65 +++++++++++++++++++++++++++++++++++++----------- 3 files changed, 127 insertions(+), 15 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index c023545f..d615e6e3 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -6,6 +6,13 @@ Versions follow [Semantic Versioning](https://semver.org/). ## [Unreleased] +Nothing in this section is released or deployed: faunosteo.com runs 0.1.0. +Everything below is on `develop` only, accumulated since 0.1.0: the SaaS +Steps 0 to 8 and the Rust migration R0 to R5 included. `release/0.2.0` (Steps +3 to 6) was cut on 2026-10-11 and never finished; its `[0.2.0]` section lives +on that branch and reaches this file only if the release is finished (TODO +RR-9). + ### Removed (2026-10-25, Rust R5.7: the TypeScript pipeline and domain packages) - `packages/anatomy` (legacy importer, curation pipeline, TypeScript renderer, `import-equine` CLI) and `packages/domain` (Zod schemas and rules) are deleted, with the TypeScript upload script `packages/supabase/scripts/upload-sheet-assets.ts` and the scripts `pnpm import:equine:legacy` and `assets:upload:legacy`. The Rust core does all of it: `pnpm import:equine` and `pnpm assets:upload` are unchanged for the user. `@xmldom/xmldom` leaves the lockfile; `tsx` is no longer a dependency of any package (pnpm keeps it only as an optional peer of vite); root Prettier stays (`pnpm format`, `db:types`). diff --git a/DEPLOY.md b/DEPLOY.md index cee17275..223269e9 100644 --- a/DEPLOY.md +++ b/DEPLOY.md @@ -1,5 +1,56 @@ # Deploy +## Status of this guide (2026-10-25) + +This guide was written for the static deployment of 0.1.0, the version +faunosteo.com runs, and is kept as that record. It is not a procedure for +`develop`: nothing authorises deploying it (release readiness track, TODO +RR-1 to RR-10). The corrections this file needs are TODO RR-5. + +Historical, true for 0.1.0 and wrong for an image with a backend: the +introduction below ("no backend, no database"), "Data persistence", +"Backups", "Backend CORS", "Frontend API base URL", the rollback's "no +server-side state", and the troubleshooting entries "CORS rejected in +browser" and "volume / data unexpectedly empty". + +Not verified for the current code: + +- the loopback claim: `docker-compose.yml` publishes `${PORT:-8080}` on every + interface, and rootful Docker bypasses UFW; +- "First-time VPS setup", "Routine deploys" and "Rollback" build the image on + the VPS; an image from R2 on compiles the Rust core and is never built there + (see "Image deploy by digest"); +- the fallback that serves `apps/app/dist/` from a plain `nginx:alpine` drops + `docker/nginx.conf` (the `env.js` no-cache rule, the `.wasm.gz` served with + `gzip_static`); +- the VPS sizing table, written before the Rust build stages. + +Would break the current application if applied as written: + +- the two CSP examples (Option A nginx, Option B Caddy), marked below as not + production-ready: without `'wasm-unsafe-eval'` the editor, the export and + the import cannot load the Rust core; without the Supabase origin in + `connect-src` (it falls back to `default-src 'self'`), sign-in and the + `/app` space fail unless Supabase is served from the same origin; +- a default build (`SHEET_BUNDLE=none`): no anatomical sheet, the editor + refuses to create or import a report. + +Security prerequisites before deploying anything built from `develop`: + +- the CSP of "WebAssembly and the CSP" with `connect-src` naming the Supabase + origin, checked on the image (`docker/csp-proof/app-image.sh`); +- the container port bound to loopback in fact, checked from outside the VPS; +- a hosting decision for Supabase (`docs/development/OPEN_QUESTIONS.md` Q2), + production SMTP with French auth email templates, captcha, OAuth ids, MFA + for platform roles (RR-3, RR-5); +- the worker's service key out of `.env`, its exposure to the `docker` group + settled (RR-4); +- images built off the VPS and pulled by digest, base images pinned (RR-6); +- the RLS and API items of RR-3 and RR-4 and the dependency advisories of + RR-1 treated or qualified. + +--- + Single nginx:alpine container behind a host reverse proxy that terminates TLS. The container serves a static SPA bundle (built from `apps/app`, Node 24, pnpm 10.13.1) from `/usr/share/nginx/html` @@ -298,6 +349,10 @@ previous image, never a rebuild of the old engine. ## Data persistence +Historical (0.1.0, no backend): once Supabase or the worker run beside the +application, the database and the Storage objects are server-side state that +this section and the next do not cover. + There are no server-side volumes to back up: - **In-flight session data** lives in the praticien's browser @@ -314,6 +369,10 @@ regenerated on every build. ## Backups (cron + retention) +Historical (0.1.0): the `.env` snapshot below is the whole backup only while +the server holds no data; `docs/development/STORAGE.md` §5.2 sets the order +for a backend (database dump first, files within 48 h). + Because there is no server-side state, the backup target is the source repository plus the `.env` file. @@ -430,6 +489,11 @@ systemctl status certbot.timer # auto-renew preinstalled on Ubuntu #### Security headers (Option A only) +Not production-ready (2026-10-25): the `Content-Security-Policy` line below is +the 0.1.0 header. It lacks `'wasm-unsafe-eval'` and the Supabase origin in +`connect-src`; any later image needs "WebAssembly and the CSP" below first +(correction tracked as TODO RR-5). + Add inside the `listen 443` block (under any existing `location` rules the certbot template inserted): @@ -460,6 +524,9 @@ the PDF preview emits data URLs. ### Option B — Caddy (auto-TLS, single file) +Not production-ready (2026-10-25): the `Content-Security-Policy` of this +Caddyfile is the 0.1.0 header, with the same gaps as Option A (TODO RR-5). + ```bash apt-get install -y debian-keyring debian-archive-keyring apt-transport-https curl -1sLf https://dl.cloudsmith.io/public/caddy/stable/gpg.key | gpg --dearmor -o /usr/share/keyrings/caddy-stable-archive-keyring.gpg @@ -489,6 +556,9 @@ Caddy handles TLS issuance + renewal automatically. ### Backend CORS +Historical (0.1.0): since Step 7 the browser calls the Supabase API, a +cross-origin request unless Supabase is served from the same origin. + N/A. The app has no backend and makes no cross-origin requests. The only runtime fetches target the same origin (SVG assets, `env.js`). diff --git a/README.md b/README.md index d9106969..edd3c01c 100644 --- a/README.md +++ b/README.md @@ -11,15 +11,52 @@ generated and curated under `supabase/seed/anatomical-sheets/equine/`. Another species is another sheet document, no code change. See `docs/development/ANATOMICAL_SHEET_MODEL.md` §6 for how a sheet is produced. -Open to every praticien who wants to use it. No authentication, no backend, -no central server in v1 — the PDF is the long-term record. Phase 2 will add -optional praticien accounts + server-side persistence on the same data -contract. +--- + +## Versions: what is public, what is in development + +| Where | What it is | +| ------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| Public, on faunosteo.com: **0.1.0** (2026-05-21) | The local tool alone, open to every praticien: a static application with no account, no backend and no central server. The exported PDF is the long-term record. | +| `develop` (not released, not deployed) | The local tool on the canonical anatomical sheet and Report v3, the PDF archive envelope, the Rust migration R0 to R5 (domain rules, SVG reader, PDF reader and writer, curation pipeline and files worker in `crates/`), and the SaaS foundations: Supabase schema under RLS, accounts, the `/app` space, the profile photo. | +| `release/0.2.0` | Cut on 2026-10-11 from plan Steps 3 to 6, never finished or deployed; its fate is TODO RR-9. | + +Available only in a development environment (they need the local Supabase +stack, `pnpm db:start`, and for the photo the worker container; no production +Supabase exists and hosting is undecided, `docs/development/OPEN_QUESTIONS.md` +Q2): + +- sign-up with email confirmation, sign-in, password recovery, OAuth buttons + behind configuration; +- the `/app` space: dashboard and Mon compte (personal, professional, + preferences, security sections); +- the profile photo, processed by the Rust worker; +- the curated equine sheet DRAFT in the editor, bundled only with + `SHEET_BUNDLE=draft` (`pnpm dev`, `pnpm build:preview`): not medically + validated, not published; a default build carries no sheet; +- the anatomical pipeline and archive tools (`pnpm import:equine`, + `pnpm assets:upload`, `pnpm report:compare`). + +Planned, not implemented (roadmap in +`docs/development/IMPLEMENTATION_PLAN.md` §0): V1-1 clients and animals (its +contract awaits the owner's ratification), V1-2 sheets served from Supabase, +V1-3 bilans stored in the cloud with history, V1-4 stored PDFs and authorised +sharing, V1-5 mobile and accessibility pass; then professional verification, +cabinets, entitlements, agenda, public site and the rest of the plan. Nothing +on `develop` authorises a release: the release readiness track (TODO RR-1 to +RR-10) comes first. --- ## Features +The local tool as it stands on `develop`. The public 0.1.0 has the canvas, +the detail view, the vertebra picker, the findings tree, PDF export and +re-import (report v2), the bilingual UI, the configurable identity and the +practitioner cache; laterality, the footer branding, Report v3 with the v2 +migration, the sheet document and the rescue copy came after it (CHANGELOG +`Unreleased`). + - **Anatomy canvas** — inline SVG drawing with markers rendered from the sheet document (hitbox + visible twin, delegated click listener) - **Observation builder** — group zones into clinical observations with severity and free-text notes - **Hierarchical findings tree** — per-zone picker with breadcrumb drill-down through the expert-authored catalog (26 zones for the horse), vet-referral badges on sensitive leaves, scope-disclaimer modal once per session @@ -61,13 +98,13 @@ corepack enable pnpm install cp .env.example .env # edit APP_* vars if desired -pnpm dev # http://localhost:5173 +pnpm dev # http://:5173 (the DEV origin, never localhost) ``` Development server on the private network (the DEV origin is the machine's LAN address, `scripts/dev-env.sh`): `pnpm db:start`, then `pnpm dev` and open `http://:5173` from any device of the network; Mailpit for the -sign-up mails on `:54324` (`docs/development/ENVIRONMENTS.md`). +sign-up mails through the DEV gateway on `:54325` behind basic auth, `pnpm dev:gateway` (`docs/development/ENVIRONMENTS.md`). Rust (core, browser module, worker): a user-level `rustup` installs the pinned toolchain from `rust-toolchain.toml` on first use; see @@ -114,7 +151,7 @@ docker build -t faunosteo . # multi-stage Docker image docker compose up --build # run with env_file: .env ``` -For production deployment (VPS provisioning, firewall, TLS, nginx reverse proxy, backups, hardening) — see [DEPLOY.md](DEPLOY.md). +For production deployment (VPS provisioning, firewall, TLS, nginx reverse proxy, backups, hardening) — see [DEPLOY.md](DEPLOY.md). It describes the static 0.1.0 deployment; read its status notice before deploying anything built from `develop`. --- @@ -128,9 +165,10 @@ For production deployment (VPS provisioning, firewall, TLS, nginx reverse proxy, - [docs/development/STEP6_PDF_ARCHIVE_ANALYSIS.md](docs/development/STEP6_PDF_ARCHIVE_ANALYSIS.md) — why and how the PDF became an autonomous archive (Step 6) - [docs/development/PDF_IMPORT_HARDENING.md](docs/development/PDF_IMPORT_HARDENING.md) — PDF import against decompression bombs: what lands now, what is required before external users - [docs/development/SUPABASE.md](docs/development/SUPABASE.md) — local Supabase stack, migrations, RLS tests, generated types -- [DEPLOY.md](DEPLOY.md) — production VPS deploy guide (Docker + nginx + TLS + hardening) +- [docs/development/IMPLEMENTATION_PLAN.md](docs/development/IMPLEMENTATION_PLAN.md) — SaaS plan; §0 holds the product roadmap and where each step stands +- [DEPLOY.md](DEPLOY.md) — production VPS deploy guide (Docker + nginx + TLS + hardening), written for the static 0.1.0 - [CHANGELOG.md](CHANGELOG.md) — versioned release notes -- [.claude/tasks/TODO.md](.claude/tasks/TODO.md) — implementation roadmap +- [.claude/tasks/TODO.md](.claude/tasks/TODO.md) — task list and release readiness track --- @@ -165,12 +203,9 @@ faunosteo/ pnpm workspace (see docs/development/WORKSPACE.md) ## Status -v0.1.0 MVP — implementation complete. - -- `pnpm typecheck` ✅ -- `pnpm lint` ✅ -- `pnpm test:run` ✅ — the vitest suites of the workspace (core-wasm, supabase, app); `pnpm rust:check` runs the Rust ones -- `pnpm build` ✅ +Public: 0.1.0 (2026-05-21), the local tool with no backend. `develop`: plan +Steps 0 to 8 and the Rust migration R0 to R5, merged, not released. The merge +gate is `pnpm check:all` (see "Verifying a change"); no CI runs on the forge. The first species ships as the equine anatomical sheet: the historical `Horse.svg`, `Horse_head.svg` and findings catalog (26 zones, 792 nodes)