Référence build.pl

builder/build.pl est le builder de site statique que Chinaski exécute après les changements de contenu et de réglages. Il lit le contenu dans la base de données, rend le HTML dans un répertoire staging, le contrôle, et ne l'échange en ligne que lorsque le build est sain. Il n'y a aucun flag en ligne de commande : le builder est contrôlé entièrement par les variables d'environnement, les réglages que vous éditez dans la zone admin, et les contrôles de build du dashboard.

Cette page couvre le cycle de vie complet du build et les interrupteurs utilisables en exécutant le builder à la main. (Invocation recommandée pour les exécutions manuelles : définissez d'abord CHINASKI_DB et CHINASKI_OUTPUT, à l'identique de la façon dont le CMS l'exécute.)

Garde-fous

Le builder refuse de tourner en tant que root : les fichiers de sortie seraient alors non inscriptibles par l'utilisateur de service chinaski. Exécutez-le plutôt comme l'utilisateur chinaski (ex. sudo -u chinaski perl builder/build.pl).
Le builder refuse de tourner du tout si le fichier de base de données n'existe pas.

Où vivent les choses

Base de données : CHINASKI_DB si définie ; sinon chinaski.db à la racine de l'app.
Sortie : CHINASKI_OUTPUT si définie ; sinon output à la racine du repo.
Templates de blocks : CHINASKI_BLOCK_TEMPLATES si définie ; sinon builder/block_templates dans le repo.
Un build terminé conserve les 100 dernières lignes d'historique de build (visibles sous Builds dans la zone admin).

Builds full vs incrémentaux

Le build par défaut est incrémental : il réutilise ce qui est déjà en ligne.

Un build incrémental n'est tenté que lorsque :

le mode incrémental est réellement demandé,
un build réussi précédent est enregistré (et non horodaté dans le futur),
le répertoire de sortie en ligne existe toujours et contient un index.html,
le fingerprint de build stocké est inchangé (un écart de fingerprint signifie un changement global, comme un changement de thème ; cela déclenche un build full),
et l'amorçage de la copie staging de l'arborescence en ligne réussit ; si l'amorçage échoue, tout le build retombe silencieusement en full.

Tout le reste provoque un build full, et la raison est consignée dans l'historique de build.

Pour forcer un rebuild full propre : utilisez la case Full rebuild du dashboard, définissez CHINASKI_FORCE_FULL=1, ou exécutez bin/force-full-build.pl, qui vide le cache de build puis lance un build full.

Priorités et parallélisme

CHINASKI_JOBS définit combien de workers parallèles rendent les pages. Ce doit être un nombre simple ; il prime sur le réglage build_jobs de la zone admin, et les deux retombent sur votre nombre de CPU. La valeur est bornée à la plage 1 à 16. Une valeur de 1 build séquentiellement sans processus supplémentaires.

Le timeout

Chaque build a une limite dure en temps mural de 30 minutes (1800 secondes). Quand la limite est atteinte, les workers de rendu en vol sont tués et le build meurt avec un message de timeout ; rien n'est promu.

Comment s'exécute un build

Contrôle d'éligibilité : incrémental ou full est décidé avant que quoi que ce soit soit écrit, si bien qu'un contrôle en échec ne peut jamais endommager le site en ligne.
Rendu en staging : pages, posts et tout le reste sont rendus dans <output>.next, un répertoire staging à côté de la sortie en ligne. Les builds incrémentaux sautent la réécriture des pages inchangées en réutilisant les fichiers du build précédent.
Contrôle de qualité : le promotion guard compare ce build à la dernière promotion saine (voir ci-dessous). Les erreurs de rendu sont collectées à mesure qu'elles surviennent.
Écriture du manifest signé : une attestation signée de la sortie est produite seulement après que tous les contrôles passent, et seulement si aucune erreur n'aurait déjà bloqué le build. Si la signature échoue, le build avorte et le manifest précédent est restauré, sauf si le manifest est marqué optionnel.
Promotion : le répertoire staging est échangé avec la ligne. L'échange est atomique (un seul rename), donc il n'y a aucune fenêtre où le site est à moitié mis à jour.

Quand un build refuse de promouvoir

Le build ne promeut jamais par-dessus un résultat cassé. Trois conditions l'arrêtent :

Erreurs de rendu. Tout échec de template ou de rendu bloque la promotion. La sortie en ligne reste intacte, le staging est écarté, et les templates en échec sont rapportés.
Le promotion guard (mode enforce). Le guard compare ce build à la dernière promotion propre : chute du nombre de pages (seuil par défaut 80 %), augmentation des liens cassés (25 par défaut) et augmentation des problèmes d'accessibilité (10 par défaut), plus une limite absolue optionnelle sur les blocks non résolus. En mode enforce, la promotion est bloquée exactement comme un échec de rendu. En mode warn (le défaut), le problème est logué mais le build promeut quand même. Les réglages du guard vivent sous Settings → Workflow.
Échec du manifest. Un build ne peut pas promouvoir sans un manifest signé utilisable.

Contourner un blocage du guard est possible pour un seul build à la fois : le contrôle Promote anyway du dashboard, ou CHINASKI_FORCE_PROMOTE=1. Forcer ne met jamais à jour les baselines de qualité ; le prochain build ordinaire compare toujours à la dernière promotion propre, de sorte qu'un build forcé mauvais peut être attrapé plus tard.

Codes de sortie

Le builder sort avec 0 sur une promotion qui s'est déroulée proprement avec zéro erreur de rendu, et 1 sur tout le reste : un blocage du guard, des erreurs de rendu, un timeout, un échec de manifest ou une promotion en échec. Les outils de deploy s'appuient sur cela : une sortie non nulle avorte un deploy standard plutôt que de redémarrer le service sur une sortie périmée.

Exécuter les builds depuis la zone admin

Normalement vous n'exécutez pas build.pl à la main :

Enregistrer des réglages qui affectent la sortie, ou changer le préfixe d'URL des posts, déclenche un build automatiquement.
Le dashboard (via Build) propose un build normal (incrémental), un Full rebuild et Promote anyway, chacun avec son propre message de confirmation.
Un seul build s'exécute à la fois : en démarrer un second est refusé avec « a build is already in progress ». Le lock expire aussi tout seul si un build ne fait jamais de retour, donc il ne peut pas figer les builds définitivement.
Pendant qu'un build tourne, /admin/build/status rapporte la progression, et l'historique de build montre les 100 derniers builds terminés, y compris les bloqués et les en erreur.
Si un email de notification de build est configuré sous Settings → Email, un message est envoyé quand un build réussit ou échoue (délivré via le relais SMTP, donc il faut SMTP configuré, et c'est sauté en mode air-gap).

Mode air-gap

Avec CHINASKI_AIRGAP=1 définie, le builder retire toutes les références externes des pages générées : les analytics GA4/GTM sont supprimées même si configurées, et le code de snippet référençant des URL externes est retiré. Les pages construites ne chargent alors rien depuis un CDN.

Référence rapide des variables d'environnement

Variable	Effet
`CHINASKI_DB`	Base de données à lire (outrepasse le défaut)
`CHINASKI_OUTPUT`	Où publier
`CHINASKI_INCREMENTAL=1`	Demander incrémental (peut tout de même retomber en full)
`CHINASKI_FORCE_FULL=1`	Forcer un rebuild full propre
`CHINASKI_FORCE_PROMOTE=1`	Contourner le promotion guard pour ce build
`CHINASKI_JOBS`	Nombre de workers parallèles (1 à 16)
`CHINASKI_BLOCK_TEMPLATES`	Répertoire des templates de blocks
`CHINASKI_MANIFEST_OPTIONAL=1`	Rétrograder un échec de manifest signé en avertissement
`CHINASKI_AIRGAP`	Retirer les analytics et les références de snippet externes
`CHINASKI_TEST`	Échappatoire en mode test (autorise l'exécution en root)

Voir la référence des variables d'environnement pour le contexte des variables partagées.