# 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` and a runtime-injected `env.js`; there is no backend, no database, no persistent server-side state. Praticien data lives in the browser (`sessionStorage` / `localStorage`) and in the exported PDFs themselves (JSON attached natively to each PDF). The container runs entirely as a non-root `nginx` user — no process is root after the image is built. --- ## What gets deployed | Service | Image source | Port (container) | Port (host) | Role | | ------- | ----------------------------------------- | ---------------- | --------------- | ----------------------------------------------------------------------------------- | | `app` | local build (multi-stage `Dockerfile`) | `${PORT:-8080}` | `${PORT:-8080}` | Serves the SPA (`dist/`) + runtime `env.js`. `nginx:1.31-alpine` inside, runs as non-root `nginx` user, SPA fallback to `index.html`. | 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/R1, `docs/development/RUST.md`): the repository also builds a worker image (`crates/worker/Dockerfile`, static musl binary on `distroless/static`, container `faunosteo_worker`, service `worker` under the Compose profile `worker`). Since Step 8 it carries the files job loop (avatar processing, purge sweeps: `docs/development/STORAGE.md` §3); since V1-2.3 the same image also runs the sheet verification mode, service `worker-verify` (`run --jobs sheet-verify`, STORAGE.md §3.6), never started on DEV without the owner's go. It is not deployed yet: it needs the self-hosted Supabase stack beside it, which production does not run today; the live deployment above is unchanged. The production VPS never needs a Rust toolchain: Rust is compiled on the Ubuntu development machine (native toolchain) or inside Docker builder images, and production images will be pulled by digest ("Image deploy by digest", prepared below) once a runner and a registry exist on the forge. No CI/CD is operational today (2026-10-13). ### Reference sheet in the image (SHEET_BUNDLE) The application needs an anatomical sheet to work. Until sheets are served by Supabase (plan Step 13) the only source is the sheet bundled at build time: | Build | Sheet in the bundle | |---|---| | `docker build .` / `pnpm build` (default, CI) | none: the app shows "no anatomical sheet" and refuses to create or import a report | | `docker build --build-arg SHEET_BUNDLE=draft .` / `pnpm build:preview` | the curated equine DRAFT, medically unvalidated | Bundling the draft is a deliberate preview decision, never the default: the draft content is readable by anyone who can load the application (BDR-037). ### Docker resource naming Expected change in `.env.example` (file not editable by the assistant): replace `COMPOSE_PROJECT_NAME=osteo-report` with `COMPOSE_PROJECT_NAME=faunosteo` or drop the line. The variable overrides `name: faunosteo` in `docker-compose.yml`, so an `.env` copied from the example would still create `osteo-report_*` resources. No secret is involved. Several SaaS may share one VPS, so every Docker resource Faunosteo owns carries the `faunosteo_` prefix whenever its name is configurable: containers, Compose project (hence networks and named volumes), images and future services (`faunosteo_app`, `faunosteo_worker`, `faunosteo_supabase_db`…). | Resource | Name | Set by | | ------------------------------ | ------------------------------------- | ---------------------------------------- | | SPA container | `faunosteo_app` | `container_name` in `docker-compose.yml` | | Compose project, network | `faunosteo`, `faunosteo_default` | top-level `name:` in `docker-compose.yml` | | Local Supabase stack (CLI) | `supabase__faunosteo` | `project_id` in `supabase/config.toml` | Known limit: the Supabase CLI hard-codes `supabase__` for its containers, volumes and network (`supabase_network_faunosteo`); the project id is a suffix, not a prefix. The name stays unique per SaaS, so no workaround is applied. A self-hosted production Supabase (docs/development/ SUPABASE.md §10) is a Compose project we write ourselves and must follow the prefix (`faunosteo_supabase_db`, `faunosteo_supabase_auth`, …). Renaming a container never touches data: the SPA container holds no volume. When a future service gains a named volume, keep the volume name across a rename (`external: true` or an explicit `name:`) instead of recreating it. --- ## Required environment All vars live in a single `.env` file at the project root on the VPS (read by `docker compose` via `env_file: .env`). Defaults sit in `docker/entrypoint.sh` and `src/config/env.ts`; production should set each one explicitly. | Variable | Required | Default | Notes | | ----------------- | -------- | ---------------- | ------------------------------------------------------------------------------------ | | `APP_SITE_NAME` | yes | `Faunosteo` | Browser ``, OG `site_name`. | | `APP_BRAND_NAME` | yes | `Faunosteo` | Header brand block, PDF header. Praticien-visible identity. | | `APP_FOOTER_NAME` | yes | `Faunosteo` | Footer copyright line. | | `APP_TAGLINE` | yes | `Outils pour ostéopathes animaliers` | Hero tagline on Home. | | `APP_SUPABASE_URL` | no | empty | Supabase project URL exposed to the browser. Empty = app runs without backend (current mode). | | `APP_SUPABASE_ANON_KEY` | no | empty | Supabase anon (publishable) key. Public by design, data stays behind RLS. Never the service_role key. | | `APP_AUTH_PROVIDERS` | no | empty | OAuth buttons on the auth screens, comma-separated (`google,apple`). The Supabase project must enable the same providers; empty = email/password only. | | `PORT` | no | `8080` | Container listen port. Must be `>=1024` — the container runs as a non-root `nginx` user and cannot bind privileged ports. | No secrets are required in this file: the anon key is public by design and the service_role key never leaves the Supabase host (see `docs/development/SUPABASE.md`). The `.env` file is not sensitive but should still be `chmod 600` to keep local identity overrides private. ### Worker environment (`.env.worker`, Step 8) The files worker (`docker compose --profile worker up -d worker`) reads a second env file, `.env.worker`, never the app `.env`: it holds the service key. `chmod 600`, excluded from every backup copy of env files, readable through `docker inspect` by the `docker` group (documented limit). The assistant cannot write `.env*` files in this repository: create it by hand from the table (STORAGE.md §3.2 lists the optional tuning variables). | Variable | Required | Notes | | --- | --- | --- | | `SUPABASE_URL` | yes | Kong origin on the Supabase compose network (`http://supabase_kong_faunosteo:8000` on the local CLI stack; the self-hosted stack's own Kong name in production). Never the public URL when the stack is on the same host. | | `SUPABASE_SERVICE_ROLE_KEY` | yes | the service key; on self-hosted a long-lived JWT (revoking it = rotating `JWT_SECRET`). Never in `.env`, env.js or the repository. | | `WORKER_ID` | no | tag of the log lines (default `worker-<pid>`). | The service joins the external network named by `SUPABASE_NETWORK` (default `supabase_network_faunosteo`, the local CLI stack); it publishes no port, runs read-only with every capability dropped, 512 MiB, 1 CPU, 64 pids. The verification service `worker-verify` (V1-2.3) has the same hardening with 1 280 MiB, so its child's 1 GiB address-space limit binds first: a host that runs it beside the stack needs that memory on top of the 1 GB below. Browser side, the production CSP `connect-src` must name the Supabase origin the app talks to (already required since Step 7), and `img-src` keeps `blob:` (the avatar is shown from a blob URL downloaded under RLS). --- ## Provision the VPS | Resource | Recommended minimum | | ------------ | ----------------------------------------------- | | CPU | 1 vCPU | | RAM | 1 GB (build runs out-of-band — see below) | | Disk | 10 GB | | OS | Ubuntu 24.04 LTS (or any recent Debian-family) | Build-time RAM peaks around 1 GB (Vite + TS + Tailwind). If your VPS only has 1 GB, either swap-enable the host or build the image locally and push it to a registry — the runtime image is well under 100 MB. DNS: ```text # A record on your domain registrar / DNS provider faunosteo.com → <vps-ipv4> faunosteo.com (AAAA) → <vps-ipv6> # optional ``` SSH key copied to the VPS before disabling password auth (see Hardening below). Baseline packages (apt): ```bash apt-get update apt-get install -y git curl ufw fail2ban ca-certificates gnupg \ nginx certbot python3-certbot-nginx unattended-upgrades ``` --- ## Firewall (two layers) ### Layer 1 — cloud provider security group | Source | Port | Protocol | Rule | | ---------------------- | ------- | -------- | ------- | | your office / home IP | 22 | TCP | allow | | 0.0.0.0/0 | 80 | TCP | allow | | 0.0.0.0/0 | 443 | TCP | allow | | any | other | any | deny | Cheat sheet: - **Scaleway**: Console → Security Groups → create + bind to instance. - **Hetzner**: Console → Firewalls → attach to server. - **OVH**: Public Cloud → Networking → Security groups (legacy: iptables). - **DigitalOcean**: Networking → Firewalls. ### Layer 2 — UFW on the VM ```bash ufw default deny incoming ufw default allow outgoing ufw allow 22/tcp # SSH ufw allow 80/tcp # HTTP (for ACME challenge + redirect) ufw allow 443/tcp # HTTPS ufw --force enable ufw status verbose ``` Do **not** open `8080` (or whatever `PORT` you pick). The host nginx talks to the container on `127.0.0.1:8080`. --- ## Install Docker (production-tuned) ```bash curl -fsSL https://get.docker.com | sh systemctl enable --now docker # Cap container log volume — JSON-file driver with rotation cat > /etc/docker/daemon.json <<'EOF' { "log-driver": "json-file", "log-opts": { "max-size": "10m", "max-file": "5" }, "live-restore": true } EOF systemctl restart docker ``` Confirm: ```bash docker version docker info | grep -i 'logging driver\|live restore' ``` --- ## First-time VPS setup ```bash # As your non-root deploy user (see Hardening §1 if you have not made one yet) cd ~ git clone https://git.bchanot.fr/bchanot/faunosteo.git cd faunosteo # Configure identity cp .env.example .env $EDITOR .env # set APP_BRAND_NAME, APP_FOOTER_NAME, APP_TAGLINE, etc. # First build (publishes to 127.0.0.1:8080) docker compose up --build -d docker compose ps docker compose logs --tail=50 # Loopback sanity check curl -sI http://127.0.0.1:8080/ | head -1 # expect 200 OK curl -s http://127.0.0.1:8080/env.js # expect window.__APP_CONFIG__ = {...}; ``` If the build OOMs on a 1 GB VPS, build locally (`pnpm build`) and rsync the resulting `apps/app/dist/` over, then bind-mount it into a plain `nginx:alpine` until you upsize. --- ## Routine deploys This project has no `scripts/deploy.sh` yet. Pull-and-recompose from the VPS is the path: ```bash cd ~/faunosteo git fetch origin git reset --hard origin/main # default branch is "main" on this remote docker compose up --build -d docker image prune -f # reclaim old build layers ``` Verify post-deploy: ```bash docker compose ps curl -sI https://faunosteo.com/ | head -3 ``` For zero-downtime updates, `docker compose up --build -d` rebuilds the image then recreates the container; the container restart is sub-second because nginx:alpine boots instantly. There is no warmup phase. Rollback note (PDF archives, Step 6): PDFs exported by a Step 6 build carry a report archive envelope. A build older than Step 6 reads such a PDF as "no attachment"; a Step 6 build reads every older PDF (bare v2 and v3). Roll back only with that limit in mind and tell the practitioners which build produced their files. Rollback note (PDF archives, R4): PDFs written by an R4 build (the core's writer) are read by the R3 build and by release 0.2.0: the frozen copy of their reader (`packages/core-wasm/tests/n-1/scanner`, O11) and the frozen Zod schemas (`n-1/domain`) read every R4 fixture in the test suites (`n-1.reader`, `n-1.scanner`, `archive.envelopes`); the attachment bytes are the envelope the TypeScript wrote, in contract key order (D-R11). An R4 build reads every older PDF (bare v2, bare v3, Step 6 and R3 envelopes). The TypeScript PDF engine left the repository at R4.8: a rollback is a 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 (`sessionStorage osteo:draft`, `localStorage osteo:lastPractitioner`, `localStorage osteo:locale`, `sessionStorage osteo:disclaimer-shown`). - **Long-term record** is the exported PDF — the full report JSON is attached natively (`AFRelationship.Data`). Re-importing the PDF restores the session. The only "data" the server holds is the SPA bundle and `env.js`, both 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. ### .env snapshot ```bash # /opt/backup-osteo.sh #!/bin/sh set -e DEST="/var/backups/osteo" DATE="$(date -u +%Y%m%d)" mkdir -p "$DEST" cp /home/<deploy-user>/faunosteo/.env "$DEST/env-$DATE" chmod 600 "$DEST/env-$DATE" find "$DEST" -name 'env-*' -mtime +30 -delete ``` Make executable: ```bash chmod 700 /opt/backup-osteo.sh chown root:root /opt/backup-osteo.sh ``` ### Cron ```bash # crontab -e (root) 5 3 * * * /opt/backup-osteo.sh >> /var/log/backup-osteo.log 2>&1 ``` ### Off-VPS storage (optional but recommended) Sync the backup directory to S3-compatible storage (Scaleway Object Storage, B2, etc.): ```bash # After installing rclone or aws-cli aws s3 sync /var/backups/osteo s3://<bucket>/osteo/ --storage-class STANDARD_IA ``` ### Restore ```bash docker compose down cp /var/backups/osteo/env-<date> /home/<deploy-user>/faunosteo/.env docker compose up --build -d curl -sI https://faunosteo.com/ ``` The praticien's exported PDFs are the real long-term store. If the VPS disappeared entirely, a fresh `git clone` + `.env` + `docker compose up` on a new host reproduces the live app. --- ## Behind a domain + TLS reverse proxy ### Option A — host nginx + Certbot DNS A/AAAA records pointing at the VPS, UFW allowing 80/443, then on the VPS: ```bash # /etc/nginx/sites-available/osteo server { listen 80; listen [::]:80; server_name faunosteo.com; # Certbot will rewrite this block to add the 301 redirect. location /.well-known/acme-challenge/ { root /var/www/letsencrypt; } location / { proxy_pass http://127.0.0.1:8080; proxy_http_version 1.1; proxy_set_header Host $host; proxy_set_header X-Real-IP $remote_addr; proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; proxy_set_header X-Forwarded-Proto $scheme; } } server { # nginx >= 1.25.1: HTTP/2 is its own directive (`listen ... http2` is deprecated). # nginx 1.24 (Ubuntu 24.04 package) does not know `http2 on;`: there, write # `listen 443 ssl http2;` and `listen [::]:443 ssl http2;` instead. Check with `nginx -v`. listen 443 ssl; listen [::]:443 ssl; http2 on; server_name faunosteo.com; # ssl_certificate + ssl_certificate_key written by certbot location / { proxy_pass http://127.0.0.1:8080; proxy_http_version 1.1; proxy_set_header Host $host; proxy_set_header X-Real-IP $remote_addr; proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; proxy_set_header X-Forwarded-Proto $scheme; } } ``` Enable + obtain certificate: ```bash ln -s /etc/nginx/sites-available/osteo /etc/nginx/sites-enabled/osteo nginx -t && systemctl reload nginx certbot --nginx -d faunosteo.com 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): ```nginx add_header Strict-Transport-Security "max-age=63072000; includeSubDomains; preload" always; add_header X-Content-Type-Options "nosniff" always; add_header X-Frame-Options "DENY" always; add_header Referrer-Policy "strict-origin-when-cross-origin" always; add_header Permissions-Policy "camera=(), microphone=(), geolocation=()" always; add_header Content-Security-Policy "default-src 'self'; img-src 'self' data: blob:; style-src 'self' 'unsafe-inline'; script-src 'self'; font-src 'self' data:; object-src 'none'; base-uri 'self'; frame-ancestors 'none'" always; ``` Reload + verify: ```bash nginx -t && systemctl reload nginx curl -sI https://faunosteo.com/ | grep -iE 'strict-transport|x-frame|content-security' # Cross-check externally: # https://securityheaders.com/?q=faunosteo.com # https://www.ssllabs.com/ssltest/analyze.html?d=faunosteo.com ``` The `'unsafe-inline'` on `style-src` is needed because Tailwind injects inline `<style>` tags via the runtime engine; tighten if a Tailwind build-time export gets adopted later. `img-src` includes `data:` and `blob:` because the canvas rasterization pipeline produces blob URLs and 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 echo "deb [signed-by=/usr/share/keyrings/caddy-stable-archive-keyring.gpg] https://dl.cloudsmith.io/public/caddy/stable/deb/debian any-version main" \ > /etc/apt/sources.list.d/caddy-stable.list apt-get update && apt-get install -y caddy cat > /etc/caddy/Caddyfile <<'EOF' faunosteo.com { encode gzip zstd reverse_proxy 127.0.0.1:8080 header { Strict-Transport-Security "max-age=63072000; includeSubDomains; preload" X-Content-Type-Options "nosniff" X-Frame-Options "DENY" Referrer-Policy "strict-origin-when-cross-origin" Permissions-Policy "camera=(), microphone=(), geolocation=()" Content-Security-Policy "default-src 'self'; img-src 'self' data: blob:; style-src 'self' 'unsafe-inline'; script-src 'self'; font-src 'self' data:; object-src 'none'; base-uri 'self'; frame-ancestors 'none'" } } EOF systemctl reload caddy ``` 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`). ### Frontend API base URL N/A. There is no build-time API URL var; the app is static. ### Sanity checks ```bash # HTTPS redirect on port 80 curl -sI http://faunosteo.com/ | grep -i location # expect Location: https://... # TLS itself curl -sI https://faunosteo.com/ | head -3 # expect HTTP/2 200 # env.js shipped fresh (no caching) curl -sI https://faunosteo.com/env.js | grep -i cache-control # expect: Cache-Control: no-store, no-cache, must-revalidate # Internal port is NOT publicly bound nc -zv <vps-public-ip> 8080 2>&1 | grep -i refused # expect "Connection refused" ``` --- ## Post-deploy hardening ### 1. Non-root deploy user ```bash adduser deploy usermod -aG docker deploy mkdir -p /home/deploy/.ssh cp ~/.ssh/authorized_keys /home/deploy/.ssh/ chown -R deploy:deploy /home/deploy/.ssh chmod 700 /home/deploy/.ssh chmod 600 /home/deploy/.ssh/authorized_keys echo 'deploy ALL=(ALL) NOPASSWD: /usr/bin/systemctl, /usr/bin/journalctl' \ > /etc/sudoers.d/deploy ``` ### 2. Disable root + password SSH In `/etc/ssh/sshd_config`: ```text PermitRootLogin prohibit-password PasswordAuthentication no PubkeyAuthentication yes ``` Reload + verify on a second terminal *before* closing the first one: ```bash systemctl reload ssh ssh deploy@faunosteo.com 'echo ok' ``` ### 3. (Optional) Move SSH off port 22 Open the new port everywhere before closing 22: ```bash ufw allow 2222/tcp # 1. UFW # 2. Add 2222 to cloud security group # 3. /etc/ssh/sshd_config: Port 2222 (keep Port 22 temporarily) systemctl reload ssh ssh -p 2222 deploy@faunosteo.com 'echo ok' # confirm # 4. Remove Port 22 from sshd_config + UFW + cloud SG ``` ### 4. Unattended security upgrades ```bash apt-get install -y unattended-upgrades dpkg-reconfigure --priority=low unattended-upgrades ``` Confirm `/etc/apt/apt.conf.d/20auto-upgrades` enables `Update-Package-Lists` and `Unattended-Upgrade`. ### 5. fail2ban ```bash systemctl enable --now fail2ban fail2ban-client status sshd ``` ### 6. Final lockdown check ```bash # From OUTSIDE the VPS nmap -Pn -p 22,80,443,8080,2222 <vps-public-ip> # 22: filtered (if SSH moved) or open (if not) # 80: open # 443: open # 8080: filtered ← MUST NOT be open # 2222: open ← if SSH was moved # Password-SSH attempt — should fail ssh -o PreferredAuthentications=password -o PubkeyAuthentication=no deploy@faunosteo.com # Expect: Permission denied (publickey). ``` --- ## Rollback ```bash cd ~/faunosteo git reflog | head -20 # find the known-good SHA git reset --hard <known-good-sha> docker compose up --build -d curl -sI https://faunosteo.com/ | head -1 ``` Because there is no server-side state to corrupt, rollback is purely a code revert + rebuild. Praticien browsers retain their own data; PDFs 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. **From R2 on (`feature/rust-r2-domain-core`), the application image compiles the Rust core** (Dockerfile stage `wasm`: the Rust toolchain and `wasm-bindgen-cli` in a builder stage). Such an image is never built on the VPS (1 vCPU, 1 GB): it is built on the development machine or a runner and pulled by digest, with the CSP of the next section in place first. The live deployment, built from `main` before R2, is not affected. 1. Build and publish: run the manual workflow `release-images` (`.gitea/workflows/release-images.yml`, `workflow_dispatch`, never on push) on the forge. Prerequisite not met yet: no runner, registry or secret is configured on the forge (2026-10-13); the workflow has never run, which is the CI/CD step to decide separately. 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) From R2 the application loads the Rust core module in the sheet pages (the editor, the new-report submit, the PDF import). Before an R2 image is deployed, the two `Content-Security-Policy` headers of this file (nginx and Caddy options above) must carry `'wasm-unsafe-eval'` in `script-src`; the examples above still show the header of the live, pre-R2 deployment: ```text script-src 'self' 'wasm-unsafe-eval'; ``` Without the keyword an R2 image stays usable but degraded: the sign-in and account pages work, the editor shows "Le moteur de calcul de Faunosteo n'a pas pu être chargé" with a retry, and the tab's draft is left untouched (proven on the image by `docker/csp-proof/app-image.sh`, `docs/development/RUST.md` §8.5). The keyword adds nothing for a pre-R2 image, so it can be set on the proxy before the switch. 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; since R2 the image precompresses it and `docker/nginx.conf` serves the `.wasm.gz` with `gzip_static on;` (R4.8 module with the PDF reader, writer and session: 1,535,289 B raw, 519,795 B gzip -9; R3: 1.18 MB raw, 372 KB served; D-R13 budget 600 KB, report line 550 KB passed at R4.6 and declared). A proxy in front must pass `Content-Encoding` through and keep the `application/wasm` type. Since R4 the PDF import runs in a module worker (`/assets/import.worker-*.js`, a same-origin hashed file that `script-src 'self'` already allows; no `blob:`, no inline worker): the worker's response carries the same policy, so the keyword is required for the import too. Without it the import answers « Le moteur de lecture n'a pas pu être chargé » and nothing else changes. The CSP needs no other change. Browser support of the import, apart from the application's floor above: module workers need Firefox 114 or later (Chrome 80, Safari 15); the import already needed Firefox 113 and Safari 16.4 before R4 (`DecompressionStream`), so Firefox 113 is the one version that loses it (owner decision OD-1, `docs/development/RUST.md` §10). The worker never fetches the module when the page's runtime already holds it (the compiled module is posted), so an import works offline once the editor has loaded the engine, as before. --- ## Health checks | URL | Expected | | --------------------------------------- | ----------------------------------------- | | `https://faunosteo.com/` | HTTP/2 200, HTML containing `<div id="root">` | | `https://faunosteo.com/env.js` | HTTP/2 200, `Cache-Control: no-store, no-cache, must-revalidate`, body starts with `window.__APP_CONFIG__ = {` | | `https://faunosteo.com/assets/<hash>.js` | HTTP/2 200, `Cache-Control: public, max-age=31536000, immutable` | | `https://faunosteo.com/nonexistent` | HTTP/2 200 (SPA fallback serves `index.html`) | | `http://127.0.0.1:8080/` (on VPS) | HTTP/1.1 200 | There is no `/health` endpoint — the container only serves static assets. Liveness is "nginx process up + serving 200 on `/`". --- ## Troubleshooting ### container won't start ```bash docker compose logs --tail=200 app ``` Common: `.env` missing or unreadable (compose will still start but `APP_*` defaults apply); permission error on `/entrypoint.sh` (rebuild with `--no-cache`). ### 5xx from the site The container itself only serves static files — a 5xx almost always comes from the host reverse proxy. ```bash journalctl -u nginx --since "10 min ago" # Option A journalctl -u caddy --since "10 min ago" # Option B ``` Most common: `proxy_pass` target wrong (`127.0.0.1:8080` vs container port) or container down. ### CORS rejected in browser The app makes no cross-origin requests. If you see a CORS error, the likely cause is a misconfigured CSP — check the `Content-Security-Policy` header against the failing resource URL. ### 502 bad gateway from host nginx The container is down or listening on a different port. Verify: ```bash docker compose ps ss -ltnp | grep 8080 # container should own the port curl -sI http://127.0.0.1:8080/ | head -1 ``` ### SSL renewal failed ```bash systemctl status certbot.timer certbot renew --dry-run journalctl -u certbot --since "1 week ago" ``` Common: UFW dropping port 80 (ACME HTTP-01 challenge fails) or the host nginx site config moved without reloading. ### volume / data unexpectedly empty N/A — this app has no volumes. ### disk full ```bash df -h docker system df docker system prune -a -f # purge unused images/layers journalctl --disk-usage journalctl --vacuum-time=7d ``` The Docker log driver is capped at `5×10MB` per container in this setup (see `/etc/docker/daemon.json`); runaway logs should not happen. ### restart loop ```bash docker compose ps # status column docker compose logs --tail=200 app ``` Most common: `entrypoint.sh` non-executable (`chmod +x` line missing from Dockerfile after a copy edit) or nginx config syntax error (test with `docker compose run --rm app nginx -t`). ### container log explosion Already mitigated by `json-file` driver caps. If you see disk pressure from `/var/lib/docker/containers/<id>/*.log` anyway, lower the cap in `/etc/docker/daemon.json` and restart Docker. --- ## Operational notes - **Logs**: Docker JSON-file driver, capped at `5 × 10MB` per container (`/etc/docker/daemon.json`). Host nginx logs in `/var/log/nginx/`; rotate via logrotate (default Ubuntu config). Certbot logs in `/var/log/letsencrypt/`. - **Manual log prune**: `docker compose logs --no-color > /tmp/x; truncate -s 0 $(docker inspect --format='{{.LogPath}}' faunosteo_app)`. - **Key rotation**: `.env` carries no secret material, but if `APP_BRAND_NAME` etc. need to change, edit `.env` + `docker compose up -d` (no rebuild — `entrypoint.sh` reads env on container start). - **Provider-specific**: - Scaleway DEV1-S works; DEV1-XS hits build OOM. - Hetzner CX22 is the cheapest reliable choice for the build itself. - On any 1 GB VPS, build locally and skip in-place compose builds.