# 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`. --- ## 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. | | `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 — there is no API, no DB, no provider credential. The `.env` file is not sensitive but should still be `chmod 600` to keep local identity overrides private. --- ## 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. --- ## 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. --- ## 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-web)`. - **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.