# Deploy 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). 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. 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. --- ## Data persistence 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) 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 { listen 443 ssl http2; listen [::]:443 ssl http2; 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) 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) ```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 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;` (372 KB served for 1.18 MB raw, D-R13 budget 600 KB). A proxy in front must pass `Content-Encoding` through and keep the `application/wasm` type. --- ## 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.