docs(docs): RUST.md with the R0 proofs, DEPLOY image deploy by digest + CSP note, workspace/test strategy/packages/CLAUDE.md, CHANGELOG; chore(memory): TODO R0

This commit is contained in:
bchanot committed 2026-10-13 00:01:27 +02:00
1 parent 4833fd29ef
commit 9d3e0294e2
8 files changed
+376 -3

No files matched your search

+65
View File
@@ -21,6 +21,13 @@ The host should publish only ports `22`, `80`, `443` to the internet. The
container port (`8080` by default) should stay loopback-only — the host
reverse proxy reads from it on `127.0.0.1:8080`.
Rust (plan R0, `docs/development/RUST.md`): the repository also builds a
worker image (`crates/worker/Dockerfile`, static musl binary on
`distroless/static`, container `faunosteo_worker`). It is not deployed yet
(its job loop arrives at R1); the live deployment above is unchanged. The
production VPS never needs a Rust toolchain: images are built in CI and
pulled by digest ("Image deploy by digest", prepared below).
### Reference sheet in the image (SHEET_BUNDLE)
The application needs an anatomical sheet to work. Until sheets are served by
@@ -563,6 +570,64 @@ already exported are unaffected.
---
## Image deploy by digest (prepared at R0, not yet applied)
Decision D-R13 (`docs/development/RUST_ARCHITECTURE_REVIEW.md` Annex A and
C): production images are built in CI and the VPS pulls them; it never
compiles the Rust project, and the DEV1-XS memory limit stops mattering for
builds. The procedure below is prepared and documented now; it replaces
"Routine deploys" and "Rollback" above **only when the first image built
this way is deployed, after a separate validation**. Until then the live
deployment keeps building on the VPS as documented above.
1. Build and publish: run the manual workflow `release-images`
(`.gitea/workflows/release-images.yml`, `workflow_dispatch`, never on
push) on the forge. It pushes `faunosteo_app:<sha>` and
`faunosteo_worker:<sha>` to the container registry named by the
`REGISTRY` secret (the forge's own Gitea registry is the recommended
choice, Scaleway Container Registry the alternative) and prints their
digests in the job summary. No workflow deploys anything.
2. Pin: `docker-compose.yml` on the VPS references the images by digest
(`image: <registry>/<owner>/faunosteo_app@sha256:…`); the digest is the
only thing that changes at a deploy, by hand, after validation.
3. Deploy: `docker compose pull && docker compose up -d` (no `--build`), then
the post-deploy checks of "Routine deploys".
4. Rollback: set the previous digest back in `docker-compose.yml` and run
step 3 again; nothing is rebuilt and nothing needs crates.io or npm.
5. Registry credentials on the VPS: a read-only token in `~/.docker/config.json`
of the deploy user, never in the repository.
Prerequisites checked at R0 and to re-check before the first digest deploy:
disk headroom on the VPS for two image generations (app ≈ 100 MB,
worker ≈ 9 MB, measured at R0), the registry reachable from the VPS, `docker compose pull`
working with the read-only token.
### WebAssembly and the CSP (from R2 on)
The application does not load the Rust core module before plan R2. When it
does, the two `Content-Security-Policy` headers of this file (nginx and
Caddy options) must carry `'wasm-unsafe-eval'` in `script-src`:
```text
script-src 'self' 'wasm-unsafe-eval';
```
Proven at R0 under the production nginx image and headers with headless
Chrome for Testing 156 (`docker/csp-proof/run.sh`, result in
`docs/development/RUST.md` §5): with `script-src 'self'` the browser refuses
to compile the module ("Compiling or instantiating WebAssembly module
violates the following Content Security policy directive"); with the keyword
the module instantiates. `'wasm-unsafe-eval'` allows WebAssembly compilation
only, never `eval` or inline scripts (the proof's inline variant was still
blocked). Browser floor for the keyword: Chrome 97, Firefox 102, Safari 16
(the Vite 7 baseline). The `.wasm` file is served as `application/wasm` by
`nginx:1.31-alpine` out of the box; at R2 `docker/nginx.conf` gains
`gzip_static on;` for a precompressed `.wasm.gz` (or `gzip_types
application/wasm`) and the served, compressed size is what the D-R13 budget
counts.
---
## Health checks
| URL | Expected |