- Brand component now renders horizontal SVG logo instead of text - New AppHeader shared component replaces per-route header boilerplate - Tagline updated to "Outils pour ostéopathes animaliers" - All routes use AppHeader (HomeRoute, EditorsRoute, NewReportRoute, SvgEditorRoute) - ReportHeader and Footer simplified - DEPLOY.md URLs updated zoosteo.fr → faunosteo.com - Logo assets added (favicon.svg, logo-horizontal.svg, apple-touch-icon.png) - Removed unused eslint-disable directive in SvgEditorRoute Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
19 KiB
Deploy
Single nginx:alpine container behind a host reverse proxy that terminates
TLS. The container serves a static SPA bundle 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).
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:alpine inside, 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 <title>, 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. Override to relocate the loopback bind. |
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:
# 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):
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
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)
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:
docker version
docker info | grep -i 'logging driver\|live restore'
First-time VPS setup
# 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 and rsync the resulting
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:
cd ~/faunosteo
git fetch origin
git reset --hard origin/master # default branch is "master" on this remote
docker compose up --build -d
docker image prune -f # reclaim old build layers
Verify post-deploy:
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
# /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:
chmod 700 /opt/backup-osteo.sh
chown root:root /opt/backup-osteo.sh
Cron
# 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.):
# After installing rclone or aws-cli
aws s3 sync /var/backups/osteo s3://<bucket>/osteo/ --storage-class STANDARD_IA
Restore
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:
# /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:
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):
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:
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)
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
# 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
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:
PermitRootLogin prohibit-password
PasswordAuthentication no
PubkeyAuthentication yes
Reload + verify on a second terminal before closing the first one:
systemctl reload ssh
ssh deploy@faunosteo.com 'echo ok'
3. (Optional) Move SSH off port 22
Open the new port everywhere before closing 22:
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
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
systemctl enable --now fail2ban
fail2ban-client status sshd
6. Final lockdown check
# 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
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
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.
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:
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
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
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
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 × 10MBper 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:
.envcarries no secret material, but ifAPP_BRAND_NAMEetc. need to change, edit.env+docker compose up -d(no rebuild —entrypoint.shreads 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.