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.
This commit is contained in:
bchanot committed 2026-10-25 17:12:38 +01:00
1 parent ac60b24267
commit d4f628f8c8
3 files changed
+127 -15

No files matched your search

+7
View File
@@ -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`).
+70
View File
@@ -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`).
+50 -15
View File
@@ -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://<FAUNOSTEO_DEV_HOST>: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://<lan-address>: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)