794 lines
29 KiB
Markdown
794 lines
29 KiB
Markdown
# 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_<service>_faunosteo` | `project_id` in `supabase/config.toml` |
|
||
|
||
Known limit: the Supabase CLI hard-codes `supabase_<service>_<project_id>`
|
||
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 `<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. |
|
||
| `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.
|