# 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 | `Zoosteo` | Browser `
`, OG `site_name`. |
| `APP_BRAND_NAME` | yes | `Zoosteo` | Header brand block, PDF header. Praticien-visible identity. |
| `APP_FOOTER_NAME` | yes | `Zoosteo` | 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:
```text
# A record on your domain registrar / DNS provider
zoosteo.fr →
zoosteo.fr (AAAA) → # 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/zoosteo.git
cd zoosteo
# 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:
```bash
cd ~/zoosteo
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:
```bash
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
```bash
# /opt/backup-osteo.sh
#!/bin/sh
set -e
DEST="/var/backups/osteo"
DATE="$(date -u +%Y%m%d)"
mkdir -p "$DEST"
cp /home//zoosteo/.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:///osteo/ --storage-class STANDARD_IA
```
### Restore
```bash
docker compose down
cp /var/backups/osteo/env- /home//zoosteo/.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:
```bash
# /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:
```bash
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):
```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://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 `