Aller au contenu

Relancer FrankenPHP ou le worker Messenger depuis le conteneur

Vous êtes développeur·se sur Kirexo — ou l'agent Claude Code qui y travaille — et quelque chose ne répond plus : une page renvoie une 502, un e-mail n'arrive jamais dans Mailpit, un article publié reste invisible sur son site public. Cette recette identifie lequel des deux programmes du conteneur php est en cause, puis le relance sans toucher à l'autre.

Prérequis

  • Un terminal dans le conteneur php du worktree : celui de votre IDE branché en interpréteur distant, ou castor wt:shell depuis l'hôte, lancée depuis le répertoire du worktree — la cible ne prend pas de ticket, c'est le répertoire courant qui décide. (castor docker:sh hors worktree.)
  • Le conteneur php existe et vous y êtes. Il n'a pas besoin d'être sain : un conteneur en mode maintenance — healthcheck rouge, aucun programme vivant — se répare exactement de la même façon.

Si castor wt:shell ouvre un conteneur jetable, cette page ne s'applique pas

Le conteneur jetable n'a pas de supervisor : sa commande a été remplacée par bash, et les cibles castor supervisor:* n'y ont rien à relancer. C'est le signe que la stack entière est à terre — suivez Réparer un worktree dont la stack ne démarre plus.

Le modèle mental en une phrase

Le conteneur php fait tourner deux process long-running sous un supervisor unique (infra/supervisor/supervisor.sh) : FrankenPHP (qui sert l'application et héberge le hub Mercure) et le worker Messenger (qui consomme les transports scheduler_default, plugin_web et async). Chacun a sa boucle de supervision, son journal, son PID file et sa cible Castor de relance. Relancer l'un ne touche jamais l'autre.

1. Identifier le programme en cause

Partez du symptôme :

Symptôme observé Programme suspect Suite
502, Connection refused, https://localhost muet FrankenPHP Étapes 2 → 5
Un e-mail attendu (réinitialisation de mot de passe, par exemple) n'arrive pas dans Mailpit worker Messenger (transport async) Étapes 2 → 4
Un article publié n'apparaît pas sur le site public de son carnet worker Messenger (transport plugin_web) Étapes 2 → 4
Un rapport d'analyse IA reste « Non analysé » indéfiniment worker Messenger (transport async) Étapes 2 → 4
Un article en corbeille depuis plus de 30 jours n'est jamais purgé worker Messenger (transport scheduler_default) Étapes 2 → 4
Le temps réel de l'éditeur ne se propage plus (Mercure) FrankenPHP Étapes 2 → 5

Le cas « article publié absent du site public » mérite une précision, parce qu'il ne ressemble pas à une panne : la publication écrit bien en base et l'article est visible dans l'espace de rédaction. Ce qui manque, c'est l'invalidation du cache du site — elle est déclenchée par le message ArticlePublished consommé sur le transport plugin_web (src/Plugin/Web/src/MessageHandler/WebArticlePublishedHandler.php, qui appelle WebDiffusionPlugin::publish()). Sans worker, le message reste dans RabbitMQ et le site public continue de servir ses pages en cache. Le mécanisme d'invalidation par tag de site est expliqué dans Rendu public d'un site (plugin web).

2. Lire l'état des deux programmes

castor doctor

Depuis le conteneur, castor doctor bascule seul sur son diagnostic interne. Trois lignes tranchent :

Ligne Ce qu'elle dit quand elle est ✗ KO
Supervisor frankenphp actif La boucle de supervision de FrankenPHP est morte (bail-out, ou kill manuel).
Supervisor messenger actif La boucle du worker est morte : plus personne ne consomme les transports.
Transports Messenger joignables (plugin_web, async) RabbitMQ ne répond pas. Le worker n'y est pour rien — c'est une action hôte.

Ces deux dernières lignes existent précisément pour distinguer « worker mort » de « broker injoignable » : les deux symptômes sont identiques (mails muets, publications sans effet) et les remèdes sont opposés.

En cas de KO, la cible affiche un bloc « Remédiations » qui sépare ce qui se répare ici (dans le conteneur : …) de ce qui exige un terminal hôte (action hôte requise : …).

Pour l'état brut des deux boucles, sans passer par le diagnostic complet :

infra/supervisor/supervisor.sh status
frankenphp RUNNING pid=42 child=57 uptime=3812 last_exit=- loops=1
messenger STOPPED pid=- child=- uptime=- last_exit=1 loops=0

pid désigne la ou les boucles de supervision, séparées par des virgules. child désigne le programme surveillé. loops compte les boucles vivantes du programme, et la valeur attendue est 1. Le code de sortie vaut 0 si les deux programmes tournent, 1 sinon.

Si un programme a plusieurs boucles, status ajoute une ligne d'anomalie sous la sienne :

frankenphp RUNNING pid=421151,433208 child=433240 uptime=12 last_exit=- loops=2
frankenphp : 2 boucles actives (pid 421151 433208) — attendu : 1. Remède : infra/supervisor/supervisor.sh restart frankenphp
messenger RUNNING pid=43 child=61 uptime=3812 last_exit=- loops=1

C'est la panne typique d'une application qui répond 200 avec l'ancien code : deux frankenphp run coexistent. Le code de sortie reste 0, parce que le programme tourne bel et bien. Appliquez le remède affiché, voir l'étape 8.

Quand plus aucune boucle ne vit, la sortie est précédée du marqueur de maintenance, à 30 secondes près (période de vérification) :

maintenance depuis <horodatage ISO 8601>
programmes abandonnés : frankenphp messenger
frankenphp STOPPED pid=- child=- uptime=- last_exit=1 loops=0
messenger STOPPED pid=- child=- uptime=- last_exit=1 loops=0

Il explique à lui seul pourquoi le conteneur répond alors que plus rien n'est servi : le supervisor a cessé de relancer, mais il ne sort pas — sinon le conteneur emporterait votre shell. La suite de la recette reste valable telle quelle : corrigez la cause dans les journaux, puis relancez le ou les programmes.

Les relances de cette page ne font pas apparaître le marqueur : tant qu'une boucle relancée vit, le conteneur n'est pas en maintenance, même si les boucles lancées au démarrage du conteneur ont toutes été remplacées. Un marqueur présent alors que status affiche une ligne RUNNING disparaît à la vérification suivante. Règle complète : Worktrees — Mode maintenance.

3. Lire les journaux

Trois fichiers, tous dans le bind-mount /app — donc lisibles à l'identique depuis le conteneur et depuis l'hôte :

Fichier Contenu
var/log/supervisor/frankenphp.log Sortie de FrankenPHP + lignes de sa boucle de supervision.
var/log/supervisor/messenger.log Sortie -vv du worker : une ligne Received message puis Message handled par message traité. C'est ici qu'on prouve qu'un message est bien passé.
var/log/supervisor/supervisor.log Journal du supervisor lui-même (détachement des boucles, arrêts, entrées et sorties de maintenance).

Le dossier est créé au premier démarrage du supervisor : s'il est absent, c'est que le conteneur n'a jamais démarré ses programmes, pas que les journaux ont été perdus.

Les lignes du supervisor sont préfixées par le programme concerné, ce qui les rend filtrables :

tail -f var/log/supervisor/messenger.log
grep 'supervisor:messenger' var/log/supervisor/supervisor.log
[<horodatage ISO 8601>] [supervisor:messenger] sortie propre (code 0) après 3600s — recyclage normal.

Trois lignes valent un diagnostic à elles seules :

  • exit <code> après <n>s (crash <k>/5) — le programme redémarre en boucle ; la cause est au-dessus dans le même fichier.
  • 5 crashs consécutifs sans stabilisation — abandon de CE programme (les autres continuent). — la boucle a fait bail-out : elle ne relancera plus rien tant que vous n'aurez pas relancé la cible indiquée juste en dessous. Corrigez d'abord la cause, relancez ensuite.
  • toutes les boucles ont abandonné — MAINTENANCE : le conteneur reste debout pour être réparé. — plus aucune boucle ne vit : les deux programmes ont fait bail-out (ou ont été arrêtés par un stop all). Le conteneur ne sort pas, son healthcheck reste rouge, et il retente un spawn all toutes les 30 secondes : la stack repartira d'elle-même dès que la cause sera corrigée.

4. Relancer le worker Messenger

castor supervisor:worker-restart

La cible procède en deux temps :

  1. Arrêt gracieux — bin/console messenger:stop-workers pose un drapeau daté dans le pool cache.messenger.restart_workers_signal (adossé à Redis, donc partagé entre ce process CLI et le worker). Le worker finit le message en cours, sort en 0, et le supervisor le relance après une seconde.
  2. Preuve du recyclage — la cible attend que le PID du process surveillé change dans var/run/supervisor/messenger.child.pid (30 s de patience). Un PID qui change est la preuve ; le retour de messenger:stop-workers, lui, réussit même si personne n'écoute.

Si le PID n'a pas bougé au bout de 30 s (Redis injoignable, handler bloqué), la cible affiche un avertissement et escalade automatiquement vers le mode brutal. Vous pouvez aussi le demander d'emblée :

castor supervisor:worker-restart --hard

Le mode --hard arrête la boucle (SIGTERM, puis SIGKILL après 20 s) et la relance. Aucun des deux modes ne touche FrankenPHP.

Pourquoi passer par messenger:stop-workers plutôt que par un signal

SIGTERM est bien le signal natif de messenger:consume, mais l'arrêt « après le message en cours » qu'il déclenche exige l'extension ext-pcntl, absente de l'image de développement (seul posix est présent). Elle n'est installée que dans l'image de production, où le worker tourne dans son propre service et où docker stop l'arrête proprement (cf. pcntl dans le stage prod). Un SIGTERM tue donc le worker immédiatement, au milieu de son message. Ce n'est pas une perte de données : le message non acké est redélivré par RabbitMQ (garantie at-least-once). Mais le chemin propre reste messenger:stop-workers, qui n'utilise aucun signal — d'où l'existence des deux modes de cette cible.

Les redémarrages rapprochés du worker sont sûrs

Contrairement à FrankenPHP (voir l'étape suivante), le worker n'a aucune garde de délai : le lock du transport bolt de Mercure est tenu par le module Mercure de Caddy, jamais par un process PHP CLI. Enchaîner trois worker-restart d'affilée n'a aucun effet sur l'application servie.

5. Relancer FrankenPHP

castor supervisor:frankenphp-restart

La cible délègue à infra/supervisor/supervisor.sh restart frankenphp. Sous verrou, le supervisor arrête toutes les boucles frankenphp qu'il découvre, par /proc et par le PID file, puis en relance une. Résultat garanti : une seule boucle et un seul frankenphp run, même si le PID file avait disparu. Le worker Messenger n'est jamais signalé.

Refus si FrankenPHP a démarré il y a moins de 30 secondes

FrankenPHP a démarré il y a 8 s — trop récent pour un redémarrage.
Le hub Mercure tient encore le lock du transport bolt : relancer maintenant provoque
un crash-loop (`invalid transport: timeout`) qui laisse l'application à 000.
Ce refus n'est pas une précaution théorique : deux redémarrages rapprochés font échouer le module Mercure de Caddy sur provision http.handlers.mercure.bolt: invalid transport: timeout, FrankenPHP boucle sur le crash, le supervisor abandonne au bail-out, et l'application reste muette — pour un geste censé la réparer. Attendez la stabilisation. Si vous savez ce que vous faites (le process précédent est réellement mort, par exemple), passez outre :

castor supervisor:frankenphp-restart --force

Vérifiez ensuite :

curl -fsI http://127.0.0.1/ && echo "FrankenPHP répond"
tail -f var/log/supervisor/frankenphp.log

6. Un message reste bloqué

Un worker vivant ne garantit pas qu'un message soit passé. Comptez ce qui attend :

bin/console messenger:stats plugin_web async

Un Count à 0 sur les deux lignes signifie que les files sont vides : le message a été traité (cherchez-le dans var/log/supervisor/messenger.log), ou il n'a jamais été dispatché. Un Count qui ne descend pas alors que le worker est RUNNING signale un handler qui échoue en boucle : le message part au transport failed après ses trois tentatives de retry.

bin/console messenger:failed:show                 # liste les messages en échec
bin/console messenger:failed:show <id> -vv        # l'exception complète d'un message
bin/console messenger:failed:retry <id>           # le rejouer après correction

Le transport failed est adossé à Doctrine (doctrine://default?queue_name=failed, cf. config/packages/messenger.yaml) : les messages en échec survivent au redémarrage du worker et de la stack.

7. Ne lancez pas un second worker

castor messenger:consume

Cette cible refuse de démarrer tant que le worker supervisé tourne, et c'est voulu : deux consommateurs sur les mêmes transports traitent chaque message deux fois — un e-mail envoyé en double, un cache invalidé deux fois — sans qu'aucune trace ne dise pourquoi. Le refus vaut aussi depuis l'hôte, où la cible aboutit dans le même conteneur.

Si vous avez besoin d'un worker au comportement particulier (verbosité, transport unique, arrêt après N messages), arrêtez d'abord le worker supervisé :

infra/supervisor/supervisor.sh stop messenger
# … votre worker ad hoc …
infra/supervisor/supervisor.sh spawn messenger

stop messenger arrête toutes les boucles messenger découvertes, pas seulement celle du PID file. spawn messenger n'en relance une que si aucune n'est vivante.

castor console contourne le garde-fou

castor console "messenger:consume async" passe directement par bin/console : aucun contrôle n'y est fait, et vous obtenez la double consommation décrite ci-dessus. Réservez cette forme aux cas où le worker supervisé est arrêté.

8. Si rien ne repart

  • La boucle repart puis meurt aussitôt : la cause est applicative, pas dans le supervisor. Lisez le journal du programme concerné en remontant avant la première ligne crash 1/5.
  • status signale plusieurs boucles (loops=2, ligne … boucles actives … — attendu : 1) : relancez le programme désigné.

    infra/supervisor/supervisor.sh restart frankenphp   # ou messenger
    

    restart arrête toutes les boucles découvertes et n'en relance qu'une. Relancez ensuite status : la ligne doit afficher loops=1. Pour FrankenPHP, castor supervisor:frankenphp-restart produit le même effet et ajoute la garde des 30 secondes. - castor doctor reste rouge sur Transports Messenger joignables : RabbitMQ ne répond pas. Aucune commande in-container n'y peut quoi que ce soit — c'est une action hôte, affichée par le bloc « Remédiations ». - La stack entière semble absente (résolutions intra-stack ✗ KO, could not translate host name "database") : le conteneur est attaché à un réseau orphelin. Voir Diagnostiquer un blocage réseau sortant. - Vous n'êtes pas dans le conteneur : les deux cibles de relance refusent l'hôte. Depuis un terminal hôte, l'unité de manipulation est le conteneur entier (castor docker:up), et castor doctor affiche la ligne Worker Messenger vivant dans le conteneur php. - Les deux programmes sont abandonnés et rien ne redémarre : le conteneur est en maintenance. La cause est en amont des deux boucles — dépendances absentes, configuration illisible. Voir Réparer un worktree dont la stack ne démarre plus.

Voir aussi