Architecture

Chinaski est volontairement découpé en quelques petites pièces mobiles plutôt qu'en un seul gros serveur toujours actif. Cette page présente les quatre éléments (l'application d'administration, le builder, la sortie statique et le manager) et leurs relations, pour que le reste de la documentation ait un point d'appui.

L'application d'administration

L'application d'administration (cms.pl) est le processus avec lequel vous interagissez : elle sert l'interface d'administration dans le navigateur et l'API REST. Tout ce que vous faites en tant qu'utilisateur se passe ici : rédiger et éditer du contenu, gérer les utilisateurs et les formulaires, configurer les réglages, gérer les clés API et les sauvegardes, et consulter les journaux de traduction et d'événements.

Elle détient une base de données SQLite contenant tout, du contenu des pages à l'historique d'audit, et elle ne tourne que sur votre serveur : liée à une adresse de loopback derrière votre proxy inverse, jamais directement accessible aux visiteurs. C'est un programme unique et autonome (un fichier Perl et ses modules de bibliothèque), déployable de trois façons : service systemd en production, serveur de développement pendant le développement, ou serveur autonome pour des déploiements hors ligne.

Elle expose aussi les points de terminaison API que les outils consomment : statut de build, tâches par lot, couverture de traduction, réglages et spécification OpenAPI, pour que des outils externes (y compris des assistants IA via le serveur MCP fourni) puissent piloter le CMS sans toucher à l'interface navigateur.

Le builder

Le builder est un programme séparé qui transforme le contenu de la base de données en site publié. Il lit la même base de données, rend chaque page et chaque billet à travers les gabarits une fois par langue configurée, et écrit des fichiers simples sur disque. Rien n'est caché dans le builder : chaque build est une opération que vous ou un webhook déclenchez explicitement, il journalise ses phases, enregistre les contrôles qualité et leurs résultats, et conserve un historique complet de chaque exécution, avec une progression visible en direct dans le tableau de bord d'administration pendant qu'il tourne.

Le builder écrit plus que des pages : chaque build régénère le sitemap de chaque langue, le flux RSS, le robots.txt, le fichier de politique de sécurité et les fichiers de redirection : la sortie publiée complète du site, déterministe à partir du contenu courant de la base de données.

Sortie statique

Le builder écrit le site sur disque sous forme de répertoires de HTML simple par langue, plus les fichiers auxiliaires ci-dessus. Votre serveur web préféré (des configurations Caddy ou nginx sont livrées avec le projet) sert ces fichiers directement aux lecteurs.

Cette séparation est la décision architecturale centrale : les lecteurs ne touchent jamais le CMS. Le site publié fonctionne que l'application d'administration tourne ou non ; même si tout le CMS était hors ligne, le site reste en service. Les seules requêtes de lecteurs qui atteignent l'application d'administration sont les soumissions de formulaires (capturés en direct par le CMS) et des sondes de scanners délibérément routées vers des URL honeypot. La mise en cache à la couche proxy fait que le contenu reconstruit atteint les lecteurs en quelques minutes.

Le manager

La documentation mentionne aussi un manager : un panneau de contrôle pour provisionner et piloter de nombreux sites depuis un seul endroit. Il existe comme produit à part entière : Chinaski Manager (github.com/bigjohncobb/chinaski-manager), et se marie avec le CMS sur un seul serveur hébergeant de nombreuses instances.

Ce que fait le Manager :

Tenants et instances. Créez des tenants, puis sous chaque tenant provisionnez de nouvelles instances Chinaski (par défaut depuis le dépôt amont) et pilotez leur cycle de vie complet : build, déploiement, retour à une version précédente, démarrage/arrêt, redémarrage et suppression. Les déploiements s'exécutent par étapes (récupération du code, dépendances, build, redémarrage) ; si une étape échoue, le manager s'en souvient et peut reprendre depuis cette étape au lieu de tout recommencer.
Discovery. Un serveur existant peut être analysé pour y trouver des instances Chinaski que le Manager ne connaît pas encore : il cherche les unités systemd et les signaux « écoute-et-travaille-dans-le-bon-répertoire », classifie ce qui peut être importé, et permet à un superadmin d'importer les instances découvertes en une seule étape.
Domaines. Rattachez des domaines d'administration et publics à n'importe quelle instance, et la configuration Caddy est régénérée et rechargée automatiquement ; chaque instance garde son propre port pour que les upstreams restent uniques.
Sauvegardes. Des instantanés de base de données par instance, réalisés avec la commande d'instantané sûre de SQLite elle-même, avec restauration (qui nettoie les fichiers fantômes de la base pour qu'elle s'ouvre proprement), plus sauvegarde et restauration séparées de la base de données propre au panneau de contrôle du Manager.
Contrôles de santé. Surveillance des instances en arrière-plan (par défaut : chaque minute), avec alertes webhook optionnelles et alertes e-mail par instance. Le Manager expose lui-même un point de terminaison de santé pour les moniteurs externes et redémarre automatiquement sous systemd en cas de crash.
Personnes et jetons. Trois rôles avec portée par tenant : superadmin (tout, y compris gestion des tenants/utilisateurs et discovery), admin (les instances d'un tenant) et user (ses propres jetons API plus une vue de l'audit log de son tenant). Les jetons API existent en version lecture seule ou accès complet, et un petit client en ligne de commande existe pour les deux.
Responsabilisation. Chaque action au niveau du manager est consignée dans un audit log avec qui, quoi, et quel tenant.

Le Manager garde sa propre base de données et son propre secret ; c'est une application de plan de contrôle, pas quelque chose qui vit à l'intérieur de vos instances CMS.

Distinction importante : le Manager contrôle de nombreuses instances CMS mono-tenant (une base de données SQLite par site). Le « CMS multi-tenant avec Postgres » de la feuille de route du projet principal est une autre chose, non livrée : un seul CMS servant plusieurs tenants. Le multi-site aujourd'hui = plusieurs instances, que vous les gériez à la main avec les modèles systemd fournis ou via le Manager.

Ce qui existe aujourd'hui dans le projet principal est exactement ce que la fonctionnalité Discovery importe : des services systemd à instance unique où un seul modèle d'unité exécute un nombre quelconque de sites (chinaski@1, chinaski@prod, chinaski@staging…), chacun avec sa propre base de données, son répertoire de sortie, son fichier de secret et ses sauvegardes.

L'autre démon livré : le serveur MCP

Encore un composant livré, et le troisième processus que vous pourriez réellement exécuter : chinaski-mcp, un adaptateur qui permet aux assistants IA (Claude Code et tout client compatible MCP) de piloter le CMS via l'API. Il parle JSON-RPC sur stdio, expose les outils CRUD/traduction/opérations de masse du contenu, garde son propre magasin de sessions et tourne comme son propre service systemd une fois déployé. Ce n'est pas le manager décrit ci-dessus ; c'est un pilote pour une seule instance CMS. Il est livré parce que ce codebase est développé « AI-first », mais c'est un outil optionnel : sans lui, le CMS fonctionne à l'identique via le navigateur.

Comment circule une requête

Requête de lecteur : serveur web → fichier statique sur disque → terminé. Le CMS n'intervient pas.
Soumission de formulaire : serveur web → /forms/<slug> mandaté en sens inverse → application d'administration → base de données (+ notification/webhooks).
Édition de contenu : administrateur connecté → application d'administration → base de données (avec révisions et audit journalisés) → rebuild explicite → fichiers statiques mis à jour → les lecteurs voient le contenu frais dans la courte fenêtre de cache du proxy.
Opérations de flotte : Manager → unités systemd, ports et domaines des instances → instances CMS provisionnées/construites/déployées par tenant, avec santé et sauvegardes surveillées centralement.

Le résumé en une ligne

Quatre pièces : l'application d'administration où vous éditez, le builder qui publie, les fichiers statiques qui servent ; et le Manager, qui relie de nombreux sites de ce type depuis un seul panneau.