Déployer sur nginx

Une recette de production pour placer un site construit par Chinaski derrière nginx : servir la sortie statique, proxifier les quelques routes dynamiques vers le daemon du CMS, ajouter le TLS, et laisser les deploys tout garder en synchronisation.

Prérequis

Une instance du CMS en cours d'exécution (l'unité chinaski@<N>) avec le daemon lié au loopback.
Un répertoire de sortie construit sous /var/www/chinaski<N>/output/<lang> (ou output/ pour un site monolingue sans préfixe de langue).
Le vhost d'exemple du dépôt (deploy/chinaski.nginx.example pour un site statique minimal ; chinaski.nginx.conf.example pour le schéma plus complet par instance).

Les trois valeurs à remplacer

Dans le vhost copié, définissez :

YOUR_DOMAIN : le nom d'hôte public du site.
OUTPUT_PATH : le répertoire de sortie par langue indiqué ci-dessus.
CMS_PORT : le port correspondant à LISTEN_URL dans /etc/chinaski<N>/env (3001 pour l'instance 1 par défaut).

Activation :

ln -s /etc/nginx/sites-available/YOUR_DOMAIN /etc/nginx/sites-enabled/
nginx -t && systemctl reload nginx

Puis ajoutez le TLS :

certbot --nginx -d YOUR_DOMAIN

Les deux blocks de proxy à ne pas omettre

Un site Chinaski « statique » a exactement deux familles d'URL qui doivent atteindre le daemon du CMS :

/forms/ : les placeholders de formulaires s'intègrent dans les pages construites, mais les soumissions sont POSTées vers le CMS. Sans ce block, chaque soumission de formulaire renvoie 404.
/documents/ : les téléchargements de documents sont servis par le CMS (compteurs de téléchargement suivis, fenêtres de publication). Sans ce block, chaque URL de document renvoie 404.

Les deux blocks transfèrent les en-têtes standards (Host, X-Real-IP, X-Forwarded-For, X-Forwarded-Proto) pour que le CMS voie le vrai client, nécessaire pour que sa limitation de débit et sa journalisation fonctionnent par visiteur.

Traitez le trafic d'admin séparément : l'interface d'admin vit sur son propre vhost (ou sur le port loopback propre du CMS si vous ne l'exposez pas publiquement). Le schéma de checklist qui proxifie depuis le loopback garde la logique de trusted-proxy du CMS simple : aucun réglage CHINASKI_TRUSTED_PROXIES supplémentaire n'est nécessaire parce que la connexion vient du loopback. Si votre architecture fait parvenir nginx au daemon depuis une adresse non loopback (par exemple un bridge de conteneur), ajoutez ce réseau à CHINASKI_TRUSTED_PROXIES.

Cache et en-têtes

Le vhost d'exemple définit des durées de cache accordées au rythme de publication de Chinaski :

HTML : cache court (revalider rapidement après chaque build).
sw.js : no-cache, must-revalidate.
Polices : cache immuable d'un an.
Autres ressources : cache d'un jour.
En-têtes de sécurité (X-Frame-Options, nosniff, Referrer-Policy, Permissions-Policy, HSTS 1y), ceinture et bretelles à côté des en-têtes que l'application définit déjà.

Vhosts de langue

Pour les sites multilingues, dupliquez le server block par langue : le sous-domaine ou vhost de chemin de chaque langue sert son propre répertoire de sortie (par exemple es.example.com → /var/www/chinaski1/output/es), chacun avec son propre block /forms/ pointé vers le même upstream.

La synchronisation des roots au moment du deploy

deploy/deploy.sh balaie les configurations nginx après chaque deploy : il trouve les directives root qui pointent vers l'arbre de sortie de cette instance et les réécrit vers ce que le mode langue courant exige (output/ pour les sites monolingues, output/<langue par défaut>/ sinon), lance nginx -t, et recharge en cas de succès, avec un avertissement (sans rechargement) quand le test de configuration échoue, pour que l'erreur puisse être corrigée à la main. Si vous suivez la disposition des exemples, l'essentiel de l'entretien de nginx devient zéro toucher à chaque deploy.