Pourquoi refuser de démarrer plutôt qu'avertir, et diagnostiquer par contrôles indépendants¶
Une installation de Kirexo peut être « démarrée » et pourtant cassée, ou compromise, sans que rien ne le montre. Deux dispositifs y répondent : un garde-fou dans l'entrypoint de l'image, qui refuse de lancer l'application quand un secret vaut encore sa valeur d'exemple, et une commande de diagnostic, app:install:check, qui passe l'installation en revue contrôle par contrôle. Cette page discute les choix qui les structurent. Le comportement exact est décrit dans Garde-fou des secrets d'exemple et Commande app:install:check ; la correction pas à pas, dans Déployer Kirexo en production.
Des pannes qui ne se voient pas¶
La plupart des pannes d'installation ne produisent aucune erreur au démarrage. Un SMTP injoignable ne se remarque qu'au premier mot de passe oublié. Sans worker Messenger, les e-mails et la diffusion des articles s'empilent dans RabbitMQ sans message. Une image sans assets compilés sert une application sans style ni JavaScript. Chacune se découvre tard, par un symptôme éloigné de sa cause.
Le cas des secrets est pire, parce qu'il ne produit même pas de symptôme. APP_SECRET=!ChangeMe! ou un mot de passe PostgreSQL !ChangeMe! ne dégradent rien : l'instance fonctionne parfaitement. Mais ces valeurs sont versionnées, donc publiques, et elles suffisent pour forger une session, signer un JWT Mercure ou ouvrir la base. C'est une compromission silencieuse : l'exploitant n'a aucune raison d'y penser, et un attaquant toutes les raisons d'essayer.
Ces valeurs arrivent en production par deux chemins, et aucun ne demande de faute grossière. Un installateur recopie le .env ou le compose.yaml du dépôt, qui portent ces placeholders pour le développement. Ou bien il oublie une variable : l'image de production n'a pas de dump-env, une variable absente du conteneur retombe sur le .env embarqué, et ce .env porte justement les valeurs d'exemple. D'où la règle « absent = valeur d'exemple » : un oubli y mène aussi sûrement qu'une copie.
Refuser plutôt qu'avertir¶
Un avertissement dans les logs aurait été plus simple. Mais il faut que quelqu'un le lise, et le démarrage d'une instance qui répond normalement n'incite pas à lire ses logs. Pour une panne qui ne produit aucun symptôme, un signal qu'on peut ignorer ne sert à rien.
Le refus change la nature du problème : une compromission silencieuse devient une panne visible au premier démarrage. Le coût est faible, puisqu'il suffit de générer une valeur et de recréer le conteneur. Et l'erreur arrive au pire moment pour l'ignorer, pendant l'installation, quand l'exploitant regarde justement si l'instance démarre.
La même logique a conduit à refuser plutôt qu'interpréter une valeur de RUN_MIGRATIONS qui ne vaut ni 0 ni 1 : dans les deux cas, deviner laisserait tourner une production dans un état que personne n'a choisi.
Pourquoi dans l'entrypoint sh, avant tout¶
Le contrôle aurait pu vivre dans Symfony : un listener au boot du kernel, par exemple. Il vit dans l'entrypoint shell, pour trois raisons.
Il passe avant tout contact avec l'extérieur. L'entrypoint attend la base puis joue les migrations. Placé avant, le garde-fou garantit qu'aucune connexion n'est tentée avec un mot de passe d'exemple, et qu'aucune migration ne modifie le schéma d'une instance qu'on s'apprête à déclarer invalide.
Il couvre tous les processus d'un coup. Serveur, worker et commandes ponctuelles passent par le même entrypoint. Un contrôle dans le kernel serait exécuté à chaque requête ou à chaque commande, et devrait trancher lui-même entre « bloquer » et « laisser passer une commande de maintenance ». L'entrypoint décide une fois, sur la commande lancée : frankenphp, php ou bin/console sont contrôlés ; composer ou sh ne le sont pas.
Il laisse une porte de diagnostic. docker compose exec ne passe pas par l'entrypoint. Dans un conteneur bloqué, app:install:check reste donc lançable : le mécanisme qui refuse ne ferme pas l'accès à l'outil qui explique.
Le prix est un langage pauvre. L'image de production n'a que /bin/sh (busybox) : pas de parseur d'URL, d'où une extraction du mot de passe de DATABASE_URL sans décodage, et une liste qui porte explicitement la forme encodée %21ChangeMe%21. Le diagnostic PHP, qui décode, complète cette vérification. La valeur testée est passée à grep par l'entrée standard plutôt qu'en argument, pour qu'elle n'apparaisse jamais dans la table des processus. Et aucune valeur n'est jamais affichée : seuls les libellés le sont.
Rester en vie plutôt que sortir¶
Un script de démarrage qui détecte une erreur sort d'ordinaire en code non nul. En production, restart: always relancerait aussitôt le conteneur, qui retrouverait la même valeur et sortirait de nouveau. Le diagnostic utile disparaîtrait dans une boucle de redémarrage, et chaque tour reprendrait l'attente de la base.
L'entrypoint réutilise donc l'état d'attente déjà introduit pour les migrations en échec : un diagnostic sur stderr, puis un processus qui reste vivant sans lancer le serveur. Le healthcheck échoue, le service passe unhealthy, et rien ne redémarre puisque rien ne meurt. Le raisonnement complet est dans Pourquoi attendre plutôt que sortir. Seule la ligne de reprise change : elle indique de renseigner les secrets et de recréer les conteneurs, plutôt que de rejouer une migration.
Le garde-fou est aussi fail-closed. Si la liste des valeurs refusées est introuvable, il ne conclut pas qu'il n'y a rien à refuser : il refuse de démarrer. Une image assez incomplète pour avoir perdu ce fichier n'est de toute façon pas une image à mettre en service.
Une source unique pour les valeurs d'exemple¶
Deux lecteurs ont besoin de connaître les valeurs d'exemple : l'entrypoint sh et le contrôle PHP du diagnostic. Deux listes écrites dans deux langages auraient divergé au premier placeholder ajouté. infra/install/example-secrets.txt est donc un simple fichier de données, une valeur par ligne, lisible par grep comme par file(). Il est déjà dans l'image, puisque infra/ y est copié : aucune ligne de Dockerfile à ajouter.
La liste reste la vérité, dans les deux sens. La comparaison est exacte : !ChangeMe!x passe, parce qu'il n'est pas dans la liste. Le garde-fou ne cherche pas à juger de la force d'un secret. Il repère des valeurs connues, publiées dans le dépôt, et chaque nouveau placeholder de secret doit y être ajouté.
Le partage des rôles avec Compose découle de ce choix. Là où un fichier Compose déclare un secret par ${VAR:?…}, un secret vide est refusé avant même le démarrage, avec un message qui nomme la variable. L'entrypoint couvre ce que Compose ne peut pas voir : une variable sans :? restée vide, et surtout une valeur non vide mais publique.
Diagnostiquer par contrôles indépendants¶
Le garde-fou ne traite qu'une question, et la tranche. Les autres pannes demandent un constat plus fin : l'instance peut démarrer avec un SMTP injoignable, et il ne serait pas raisonnable de lui refuser le démarrage pour cela. app:install:check les passe en revue sans rien bloquer.
La commande est une suite de contrôles indépendants, découverts par un tag de service. Chacun rend son verdict, un détail et une remédiation. Un contrôle qui lève une exception est rendu comme un échec (« Contrôle interrompu »), et les suivants s'exécutent quand même. Une base injoignable ne doit pas empêcher de savoir que le SMTP l'est aussi : c'est souvent la vue d'ensemble qui oriente vers la cause commune, un réseau ou une variable mal exportée.
Les verdicts sont écrits pour être collés dans un ticket. Aucun ne contient la valeur d'un secret ni un DSN complet. Face à une exception, seul son nom de classe est affiché, jamais son message : celui d'une erreur DBAL peut citer le DSN, celui d'un refus SMTP l'identifiant. Le diagnostic perd un peu en précision, mais il reste partageable.
Le rouge en développement est assumé. La commande ne regarde pas APP_ENV : elle vise les installations, et la stack de développement porte par construction les valeurs d'exemple, une adresse d'expéditeur en .local et une regex TRUSTED_HOSTS qui ne couvre pas php. Adapter les verdicts à l'environnement aurait supposé qu'on sait mieux que l'exploitant ce qui est acceptable chez lui.
Pourquoi TRUSTED_HOSTS non défini est nominal¶
Deux réglages d'hôtes cassent toute une instance sans message. Si le domaine applicatif manque à KIREXO_RESERVED_DOMAINS, la résolution Host → Site le prend pour un domaine de site inconnu et rend un 404 partout, /login compris. Si TRUSTED_HOSTS est trop étroit, Symfony rejette en 400 des hôtes que l'application devait servir. Dans les deux cas, l'instance démarre et paraît saine vue du serveur.
Le second piège venait de la documentation elle-même. La recommandation historique, une regex ^<SERVER_NAME>$, est la parade habituelle d'une application mono-domaine. Kirexo est multi-tenant : ses sites vivent sur des domaines arbitraires, ajoutés en base après l'installation. Une regex écrite au déploiement ne peut pas les connaître, et le rôle de filtre qu'elle devait jouer est déjà tenu par la résolution Host → Site, qui rend un 404 à tout hôte ni réservé ni mappé. Le raisonnement complet, et les trois protections qui couvrent l'empoisonnement de Host sans elle, sont dans Pourquoi TRUSTED_HOSTS n'est pas le filtre des Host en production.
D'où le renversement du verdict : TRUSTED_HOSTS absent est vert. Le diagnostic ne cherche pas à imposer une défense que l'architecture rend superflue ; il vérifie seulement qu'une défense ajoutée par l'exploitant ne casse rien. S'il en pose une, il endosse une liste à tenir à jour, et le contrôle la confronte à ce qu'elle doit laisser passer :
- le domaine applicatif, sans quoi l'interface elle-même répond 400 ;
php, parce que Caddy appelle l'endpointaskde l'on-demand TLS sur cet hôte interne. Un rejet n'y produit aucune erreur visible côté utilisateur : les certificats ne sont simplement jamais émis. C'est précisément le genre de panne que seul un diagnostic révèle ;- chaque domaine de site, en attente compris. Un domaine en attente doit déjà passer
TRUSTED_HOSTSpour être résolu, puis validé : rejeté en 400, il ne quitte pas cet état, sans que rien dans l'application l'explique.
Plutôt que de réinterpréter la regex, le contrôle soumet chaque hôte à Symfony lui-même, avec les motifs que le kernel a chargés. Un contrôle qui imiterait la sémantique des trusted_hosts pourrait diverger d'elle ; celui-ci ne peut pas se tromper sur ce que Symfony acceptera.
Reste la question de la provenance des domaines de site. Ils appartiennent au plugin web : le cœur, qui porte le diagnostic, ne doit pas le citer. Le plugin les expose par une capability neutre, que le contrôle interroge sur chaque plugin présent, comme pour les transports du worker plus bas. Un plugin qui servirait un jour ses propres hôtes les ajouterait au contrôle sans le modifier. Le contrat est décrit dans ServedHostsProviderInterface.
Un signe de vie en cache, faute de heartbeat Messenger¶
Savoir si un worker tourne est la question la plus délicate du diagnostic. Messenger n'expose aucun état « worker vivant » : pas de heartbeat natif, pas de registre des consommateurs. Interroger RabbitMQ sur ses consommateurs ne couvrirait que les transports AMQP, et scheduler_default n'en est pas un.
Le worker écrit donc lui-même son signe de vie. Un subscriber, branché sur les événements que messenger:consume émet au démarrage et à chaque tour de boucle, dépose un horodatage par transport dans le cache applicatif. Ce cache est déjà partagé entre le serveur et les workers (Redis), et c'est le moyen de coordination que Messenger utilise lui-même pour messenger:stop-workers.
Les réglages suivent des compromis :
- Cadence : le tour de boucle a lieu même quand la file est vide, donc très souvent. Un battement au plus toutes les 30 s par processus évite d'écrire dans Redis à chaque tour.
- Expiration : 300 s. Pendant le traitement d'un message, aucun événement n'est émis ; la marge couvre un message long, comme une analyse IA. Au-delà, le contrôle peut passer rouge le temps du message, et c'est un rouge qu'on accepte.
- Pas de suppression à l'arrêt : avec plusieurs instances, l'arrêt d'une seule effacerait le battement que les autres entretiennent, et le contrôle serait faussement rouge. L'expiration suffit.
Le subscriber garde en mémoire l'heure de son dernier battement. En mode worker FrankenPHP, un état de service survit d'une requête à l'autre, et c'est d'ordinaire un risque. Ici, seuls les événements de messenger:consume modifient cet état, et le processus serveur ne les émet jamais : il n'y a pas de fuite entre requêtes.
Des transports dérivés du conteneur, pas une liste en dur¶
Pour dire « un worker consomme chaque transport », il faut savoir quels transports existent. Une liste écrite dans le cœur (async, plugin_web, scheduler_default) aurait été plus lisible, mais elle aurait fait citer au cœur un transport qui appartient au plugin web. Désinstaller ce plugin aurait alors rendu le diagnostic rouge sur un transport qui n'existe plus, et installer un autre plugin l'aurait laissé aveugle sur le sien.
Le contrôle lit donc les transports déclarés dans le conteneur de services (les alias du receiver locator de Messenger), en écartant ceux qu'un worker ne consomme jamais (failed, sync). Chaque plugin qui déclare son transport l'ajoute ainsi aux attentes du diagnostic, sans que le cœur ait à le connaître. C'est la même règle d'isolation qui régit le reste du système de plugins : Architecture en plugins.
La contrepartie est qu'une liste de transports consommés trop courte se voit : un worker lancé sans scheduler_default laisse ce transport rouge. C'est voulu, car un planificateur qui ne tourne pas est justement le genre de panne silencieuse que le diagnostic doit rendre visible.