Déploiement CapRover : site statique construit sur le PC, servi par Caddy

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

docs/deploiement.md

@@ -0,0 +1,85 @@
+# Déploiement
+
+Ustagammon est un site statique (PWA, ADR 0009) : des fichiers HTML,
+JavaScript, le moteur en WebAssembly et ses données. Il est publié sur
+CapRover, machine `sans-pub` (https://captain.cloud.sans.pub), app
+`ustagammon`.
+
+**Le site est construit et testé sur le PC, pas sur le serveur.** La
+construction est lourde (Emscripten, génération des données du moteur) et déjà
+outillée en local. `make deploy-prod` envoie à CapRover une archive qui
+contient le site prêt, un `Dockerfile` et un `Caddyfile` (`deploy/`). Le serveur
+ne fait que copier les fichiers dans une image Caddy (`caddy:2.8.4-alpine`),
+qui les sert en HTTP derrière le HTTPS de CapRover.
+
+## Prérequis
+
+- La chaîne d'outils du projet : `make setup`.
+- **CLI CapRover**, installée avec Node par `fnm` (le script la trouve seul) :
+  ```bash
+  eval "$(fnm env)"; fnm use lts-latest
+  ```
+- **Session CapRover valide.** Le jeton expire ; pour vérifier :
+  ```bash
+  caprover api -n sans-pub -t /user/system/info -m GET -d '{}' -o false
+  ```
+  En cas de `not valid anymore` : `caprover login` dans un vrai terminal.
+- **L'app `ustagammon` existe dans CapRover** (une fois) : *Apps*, créer
+  `ustagammon`, sans volume (rien n'est stocké côté serveur), port du conteneur
+  80. Activer le HTTPS et, si besoin, un domaine.
+
+## Publier
+
+Depuis `main`, à jour avec `origin/main` (après fusion de la MR) :
+
+```
+make deploy-prod
+```
+
+Le script refuse de publier si l'arbre n'est pas propre, si l'on n'est pas sur
+`main`, si `main` diffère d'`origin/main`, ou si la session CapRover a expiré.
+Il lance `make lint` et `make test`, assemble le site (`make package`), puis
+`caprover deploy -t build/ustagammon.tar`.
+
+Pour une autre machine ou une autre app : `CAPROVER_MACHINE=… CAPROVER_APP=…
+make deploy-prod`.
+
+## Ce qui est publié
+
+- `make site` assemble `build/site/` : le contenu de `web/` à la racine, le
+  moteur (`engine.mjs`, `engine.wasm`, `engine.data`, `positions.json`) sous
+  `wasm/`, et `version.json` avec le commit publié.
+- `make package` ajoute `deploy/` et produit `build/ustagammon.tar` (environ
+  9 Mo).
+- `tests/test_site.sh` (dans `make test`) construit l'image de production en
+  local, la lance et vérifie ce que reçoit un navigateur : pages, types MIME
+  (`application/wasm` pour le moteur), compression gzip des données, en-têtes,
+  et commit de `version.json`.
+
+Réglages du serveur (`deploy/Caddyfile`) : compression zstd ou gzip, y compris
+pour les données du moteur ; `Cache-Control: no-cache` (les noms de fichiers ne
+changent pas d'une version à l'autre, le navigateur revalide chaque fichier) ;
+`X-Content-Type-Options: nosniff` ; `Referrer-Policy: no-referrer`.
+
+## Vérifier
+
+```bash
+curl -s https://<domaine de l'app>/version.json      # commit publié
+curl -sI https://<domaine de l'app>/wasm/engine.wasm  # application/wasm
+ssh sans.pub 'sudo docker service ps srv-captain--ustagammon --format "{{.Image}} {{.CurrentState}}" | head -2'
+```
+
+Puis ouvrir le site sur le téléphone : la page de test doit afficher « Moteur
+prêt ».
+
+## Retour arrière
+
+Dans CapRover, onglet *Deployment* de l'app `ustagammon` : redéployer une image
+précédente (`img-captain-ustagammon:N`). Rien n'est stocké côté serveur : aucun
+risque pour des données.
+
+## Incidents connus
+
+Voir `la-main-libre` (`docs/technique/deploiement.md`) pour le registre Docker
+de CapRover dont le certificat expire : le build réussit, l'envoi échoue, la
+production n'est pas touchée ; redémarrer `captain-registry` puis relancer.