Brand strings, config defaults, i18n dicts, PDF attachment metadata, HTML titles, Docker container name, package name, repo URLs, deploy paths, and all documentation updated. Git remote switched to faunosteo.git. Domain URLs (zoosteo.fr) preserved — DNS update is separate. 155/155 tests green. 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 | Bilans d'ostéopathie animalière |
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
zoosteo.fr → <vps-ipv4>
zoosteo.fr (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://zoosteo.fr/ | 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://zoosteo.fr/
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 zoosteo.fr;
# 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 zoosteo.fr;
# 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 zoosteo.fr
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://zoosteo.fr/ | grep -iE 'strict-transport|x-frame|content-security'
# Cross-check externally:
# https://securityheaders.com/?q=zoosteo.fr
# https://www.ssllabs.com/ssltest/analyze.html?d=zoosteo.fr
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'
zoosteo.fr {
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://zoosteo.fr/ | grep -i location # expect Location: https://...
# TLS itself
curl -sI https://zoosteo.fr/ | head -3 # expect HTTP/2 200
# env.js shipped fresh (no caching)
curl -sI https://zoosteo.fr/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@zoosteo.fr '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@zoosteo.fr '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@zoosteo.fr
# 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://zoosteo.fr/ | 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://zoosteo.fr/ |
HTTP/2 200, HTML containing <div id="root"> |
https://zoosteo.fr/env.js |
HTTP/2 200, Cache-Control: no-store, no-cache, must-revalidate, body starts with window.__APP_CONFIG__ = { |
https://zoosteo.fr/assets/<hash>.js |
HTTP/2 200, Cache-Control: public, max-age=31536000, immutable |
https://zoosteo.fr/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.