Ustagammon/docs/deploiement.md

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) :

  eval "$(fnm env)"; fnm use lts-latest
  

• Session CapRover valide. Le jeton expire ; pour vérifier :

  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

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.