Réparer un worktree dont la stack ne démarre plus¶
Vous êtes développeur·se sur Kirexo, castor wt:up <ticket> vient d'échouer — que vous l'ayez lancé vous-même ou que castor wt:shell / castor wt:claude l'aient déclenché pour vous — et le worktree ne sert rien. Cette recette vous fait entrer dans le conteneur malgré la panne, diagnostiquer, réparer depuis l'intérieur, puis vérifier que la stack est repartie.
Elle couvre le cas d'un worktree dont la stack est cassée. Le parcours nominal — créer, travailler, détruire — est dans Créer et détruire un worktree.
Prérequis¶
- Un terminal côté hôte, placé dans le répertoire du worktree en panne :
wt:shelletwt:clauden'ont pas d'argument, elles visent le worktree du répertoire courant. Les six ciblescastor wt:*sont par ailleurs hôte-only, il n'y a pas de socket Docker dans le conteneur. - Le répertoire du worktree existe — sans quoi il n'y a pas de stack à réparer, mais un worktree à créer :
castor wt:up <ticket>. - Docker démarré.
- Aucun prérequis côté worktree : ni
vendor/, ni conteneur vivant. C'est précisément l'objet de cette page.
Stack déjà cassée : KIREXO_WT_NO_AUTO_UP=1 pour aller droit au conteneur jetable
castor wt:shell et castor wt:claude lancent castor wt:up elles-mêmes quand le conteneur php ne répond pas — une seule fois, et en l'annonçant. Sur un worktree dont vous savez déjà que la stack est cassée, cette tentative va échouer, et elle n'est pas gratuite : elle peut reconstruire l'image et attendre un up --wait borné par le healthcheck.
Pour la sauter et obtenir le conteneur jetable tout de suite :
La variable se pose devant la commande, pour cet appel seulement, ou s'exporte pour la session de réparation entière. Elle vaut pour les deux cibles. Détail : Le démarrage automatique de la stack et KIREXO_WT_NO_AUTO_UP.
Le modèle mental en une phrase
Le conteneur php héberge FrankenPHP, le worker Messenger et le process claude : s'il meurt, le worktree perd son shell et son agent en même temps que son application. Deux mécanismes évitent l'enfermement : le supervisor bascule en mode maintenance au lieu de sortir, et castor wt:shell ouvre un conteneur jetable si même la maintenance n'a pas eu lieu.
1. Lire ce que wt:up affiche¶
Un up en échec ne rend plus la trace brute de Compose, mais un bloc qui nomme la porte de secours :
La stack du worktree ticket-185 n'est pas montée.
Le conteneur `php` reste debout tant qu'il peut, même quand FrankenPHP
abandonne : entre dedans et répare depuis le worktree, sans terminal hôte —
cd /…/kirexo-worktrees/ticket-185 && castor wt:shell
Une fois dedans : `castor doctor`, puis `castor supervisor:frankenphp-restart`.
Journaux : /…/kirexo-worktrees/ticket-185/var/log/supervisor/
Conteneur volontairement debout ? /…/kirexo-worktrees/ticket-185/var/run/supervisor/maintenance
État des conteneurs : cd /…/kirexo-worktrees/ticket-185 && docker compose -p kirexo-ticket-185 ps
La sortie de Compose reste affichée au-dessus : lisez-la, elle nomme le service qui n'est pas devenu healthy.
Un wt:up qui échoue à l'étape des dépendances, c'est une autre panne
Si la cible s'est arrêtée avant le démarrage, en affichant la sortie de Composer, la stack n'a jamais été lancée et rien n'est à réparer de l'intérieur. Suivez Le premier wt:up s'arrête sur l'installation des dépendances.
2. Entrer dans le worktree¶
La réparation commence par un cd. wt:shell ne prend pas de ticket : elle vise le worktree du répertoire courant, résolu par le WT du .env.worktree en remontant l'arborescence. C'est ce répertoire, et lui seul, qui décide de la stack visée.
Le chemin exact du worktree est donné par le bloc d'erreur de wt:up lu à l'étape 1 — il l'imprime avec le cd, prêt à coller. Sinon, castor wt:list en donne l'inventaire, et la commande lancée hors d'un worktree liste elle-même les chemins possibles avant de sortir en 1. castor wt:bash est un alias strictement équivalent.
Une fois dedans, les fichiers Compose sont empilés avec l'environnement du .env.worktree du worktree et le projet est désigné par un -p kirexo-<worktree> explicite : la commande vise le bon projet, même depuis un sous-dossier et même sans vendor/. Trois issues possibles, et il faut savoir laquelle vous avez obtenue.
Si la cible refuse avant même de tenter quoi que ce soit, aucune de ces trois issues ne s'applique : voir castor wt:shell refuse de démarrer sans avoir rien tenté.
Le conteneur php répond — vous êtes dans le conteneur de service, avec ses services liés (base, broker, cache). C'est le cas quand le supervisor est passé en maintenance : le conteneur est UP bien que son healthcheck soit rouge.
Le conteneur php ne répond pas — la cible tente d'abord de démarrer la stack, une fois, et l'annonce avant de partir :
La stack du worktree ticket-185 ne répond pas — démarrage automatique.
C'est `castor wt:up ticket-185`, lancé pour toi : il réconcilie la stack,
applique les migrations et attend le healthcheck. Compte une minute.
Pour t'en passer : KIREXO_WT_NO_AUTO_UP=1 castor wt:shell
La sortie de wt:up s'affiche en direct : c'est le rapport de réconciliation = ~ + ! habituel, suivi de son diagnostic s'il échoue. Lisez-la, elle est le premier élément du dépannage. Si la stack repart, le shell s'ouvre dans le conteneur de service et il n'y a rien d'autre à faire.
La stack ne répond toujours pas après cette tentative — la cible ouvre un conteneur jetable et le dit :
Le conteneur php du worktree ticket-185 ne répond toujours pas.
Ouverture d'un conteneur JETABLE, même image et même code.
Tu peux réparer (composer install, cache:clear, …).
Mais les services liés sont absents, et rien n'y survit hors du worktree.
Avec KIREXO_WT_NO_AUTO_UP=1, aucune tentative n'a lieu et le repli est immédiat ; la première ligne change en conséquence — Le conteneur php du worktree ticket-185 ne répond pas (démarrage automatique désactivé).
Ce que vous pouvez y faire, et ce que vous ne pouvez pas :
| Dans le conteneur jetable | Verdict |
|---|---|
composer install, bin/console importmap:install, bin/console tailwind:build |
Oui — l'écriture se fait dans le bind /app, donc dans le worktree, et survit à la fermeture. |
git status, git commit |
Oui — le git common dir est monté, compose.worktree.yaml étant empilé. |
| Toute commande qui parle à la base, à Redis ou à RabbitMQ | Non — --no-deps : les services liés ne sont pas démarrés. |
castor supervisor:frankenphp-restart |
Sans objet — le command: du service a été remplacé par bash : aucun supervisor ne tourne ici, il n'y a rien à relancer. Réparez, sortez, et rejouez castor wt:up <ticket>. |
Vérifiez au besoin que vous parlez au bon projet :
3. Diagnostiquer depuis l'intérieur¶
Trois lectures, dans cet ordre.
Le marqueur de maintenance dit si le conteneur est debout pour être réparé :
Fichier absent = pas de maintenance : soit au moins une boucle de supervision vit, soit le conteneur n'a jamais démarré. Le fichier reflète l'état présent, vérifié toutes les 30 secondes : l'horodatage est celui de la dernière bascule en maintenance.
L'état des deux boucles, marqueur compris :
Le diagnostic complet, avec ses remédiations séparées en « dans le conteneur » et « action hôte requise » :
Puis les journaux, tous dans var/log/supervisor/ — lisibles à l'identique depuis l'hôte, le bind /app étant le répertoire du worktree. Le dossier est créé au premier démarrage du supervisor : absent, il signale un conteneur qui n'a jamais lancé ses programmes, pas des journaux perdus.
| Fichier | Ce qu'on y cherche |
|---|---|
frankenphp.log |
La cause du crash, au-dessus de la première ligne crash 1/5. |
messenger.log |
Idem pour le worker. |
supervisor.log |
La ligne de bascule : toutes les boucles ont abandonné — MAINTENANCE : le conteneur reste debout pour être réparé. Plusieurs occurrences, séparées par boucle(s) de nouveau vivante(s) — fin de la MAINTENANCE., signalent une panne persistante : les relances automatiques abandonnent à leur tour. |
Le détail de la lecture des journaux et de l'identification du programme fautif est dans Relancer FrankenPHP ou le worker Messenger.
4. Réparer¶
Les trois causes qui couvrent la quasi-totalité des cas :
Dépendances absentes. Le journal FrankenPHP porte require_once(/app/vendor/autoload_runtime.php): Failed to open stream, et le dashboard de session Claude affiche 📦 Dépendances absentes. Depuis le conteneur :
Domaine refusé par le proxy sortant. La trace contient CONNECT tunnel failed, response 403. Le diagnostic se fait ici, le remède côté hôte — les allowlists sont montées en lecture seule dans le conteneur (invariant C4) :
Marche à suivre complète : Ouvrir un domaine dans l'allowlist.
Configuration ou code qui fait crasher FrankenPHP au boot. Corrigez la cause lue dans frankenphp.log, puis relancez le programme :
Corrigez avant de relancer
Relancer sans avoir corrigé rejoue les cinq crashs et ramène la maintenance. Et un redémarrage à moins de 30 secondes du précédent est refusé : le hub Mercure tient encore le lock du transport bolt.
5. Laisser la stack repartir¶
Rien d'autre à faire depuis l'hôte : le healthcheck Docker du service php détache un supervisor.sh spawn all au plus toutes les 30 secondes tant que FrankenPHP ne répond pas. Les boucles ayant effacé leurs PID files en abandonnant, ce spawn relance ce qui manque, et le marqueur de maintenance est effacé au passage. Si la cause n'est pas corrigée, les boucles relancées abandonnent à nouveau et le marqueur réapparaît au plus 30 secondes après leur abandon : c'est le signe qu'il reste à réparer.
Autrement dit : une fois la cause corrigée depuis le conteneur, la stack se remonte seule au cycle suivant. Suivez-la sans quitter le shell :
Si vous préférez ne pas attendre, ou si vous étiez dans un conteneur jetable, sortez et rejouez la séquence complète côté hôte :
Lancé depuis le worktree, wt:up propose d'abord d'aller dans le dépôt principal
C'est le contrôle du point de départ : depuis un arbre de travail lié, la cible demande aller d'abord dans le dépôt principal ?. En réparation, répondez non — vous voulez remonter cette stack-ci, pas repartir d'ailleurs. Le contrôle enchaîne alors sans un mot sur main, et rien n'est imposé dans un cas comme dans l'autre.
6. Vérifier¶
La ligne du worktree doit afficher up (n/n, m healthy) et ses trois URLs. Ouvrez https://app.ticket-185.localhost pour confirmer.
Ce tableau est utilisable comme diagnostic : le dénominateur compte les services déclarés par les fichiers Compose du worktree, pas ceux qui ont survécu. Un php mort donne donc partiel (1/2), et une stack dont aucun service attendu ne tourne donne arrêté, sans URLs.
Un ? en fin d'état : ne lisez pas le total
up (2/2) ? ou partiel (2/3) ? veut dire que docker compose config --services a échoué sur ce worktree — le plus souvent un .env.worktree antérieur à une variable devenue requise, comme KIREXO_SHARED_CLAUDE_DIR. Le total se replie sur les conteneurs qui existent encore : il borne par le bas, donc un service dont le conteneur a été supprimé y manque.
C'est aussi un symptôme à part entière — ce worktree est périmé. Le pied de tableau donne le remède, castor wt:up <ticket>, qui réconcilie le .env.worktree avant de démarrer.
Vérifiez enfin les données : un premier wt:up en échec laissait autrefois la base migrée mais vide. Ce n'est plus le cas — les fixtures sont chargées dès qu'aucune migration n'est appliquée, donc au premier passage réussi. Si votre base a été peuplée entre-temps par un wt:up de l'ancien comportement, forcez le rechargement :
Dépannage¶
castor wt:shell refuse de démarrer sans avoir rien tenté¶
Trois refus possibles, et ils ne disent pas la même chose.
Vous n'êtes pas dans un worktree. C'est le message que rend la commande depuis le dépôt principal, ou depuis n'importe quel autre dossier. Il porte le cd à jouer, prêt à coller :
`castor wt:shell` s'exécute DEPUIS le répertoire d'un worktree.
Le répertoire courant n'en est pas un (le dépôt principal non plus).
Où aller :
cd /…/kirexo-worktrees/ticket-185 && castor wt:shell
cd /…/kirexo-worktrees/ticket-231 && castor wt:shell
Détail des stacks : castor wt:list
Le worktree est annoncé, mais son chemin n'existe pas. Le .env.worktree du répertoire courant porte bien un WT, et le dossier attendu est introuvable :
Le worktree ticket-185 est annoncé par le `.env.worktree` du répertoire courant,
mais son chemin attendu n'existe pas :
/…/kirexo-worktrees/ticket-185
Le worktree a été déplacé, ou KIREXO_WORKTREES_DIR a changé depuis sa création.
Inventaire des worktrees réels : castor wt:list
Deux causes, deux remèdes : un worktree déplacé à la main se réenregistre avec git worktree move, et un KIREXO_WORKTREES_DIR modifié depuis la création se réaligne sur le chemin existant — wt:up ne déplace jamais un worktree de lui-même, cf. Le worktree est enregistré sur un autre chemin.
Le worktree n'a plus de configuration. .env.worktree a disparu, ou il a perdu sa clé COMPOSE_PROJECT_NAME :
La configuration du worktree ticket-185 est absente ou incomplète.
Fichier attendu : /…/kirexo-worktrees/ticket-185/.env.worktree
Régénère-le : castor wt:up ticket-185
Le remède est dans le message, et il se joue côté hôte. Contrairement à wt:shell, wt:up prend un ticket : le répertoire courant ne le contraint pas, et depuis le worktree il proposera simplement d'aller d'abord dans le dépôt principal.
Trois choses à savoir sur ce cas :
wt:shellne tente rien, pas même sous auto-démarrage actif. C'est délibéré : sans ce fichier, le worktree n'a ni réseau, ni tag d'image, ni port Xdebug, ni vhost RabbitMQ. Ouvrir un shell quand même ferait réapparaître la panne plus loin, sous un symptôme sans rapport.KIREXO_WT_NO_AUTO_UP=1ne change rien ici : ce n'est pas un démarrage qui est refusé, c'est l'entrée. Même comportement, même message, pourcastor wt:claude.castor wt:destroy <ticket>fonctionne quand même — c'est la seule cible qui continue sur cet état. Elle avertit, puis détruit le projet attendukirexo-<worktree>. Utile quand on ne veut pas régénérer un worktree pour pouvoir le supprimer ; vérifiez ensuite l'absence de résidus avecdocker compose lsetcastor wt:list.castor wt:listvous l'aurait dit : la ligne du worktree porte un⚠sur sa colonneétat, et le pied de tableau nomme le worktree avec le même remède. Un étatarrêtésans ce marqueur est, lui, un vrai constat.
Si le fichier est présent mais déclare un autre projet Compose que kirexo-<worktree> — une édition à la main —, rien ne s'arrête : les cibles avertissent en nommant les deux valeurs et continuent sur le projet attendu, qui est celui qu'elles imposent en -p. Détail : Le projet Compose visé par les cibles de worktree.
Le cas du répertoire supprimé à la main ne relève plus de cette page : il n'y a plus de répertoire d'où lancer la commande. wt:up sait s'en relever depuis le dépôt principal — voir J'ai supprimé le répertoire du worktree à la main.
Le conteneur php est UP mais le healthcheck reste rouge¶
C'est le comportement attendu en maintenance, et il est délibéré : un conteneur qui se déclarerait sain alors qu'il ne sert rien coûterait plus cher que la panne qu'il masque. docker compose up --wait échoue donc, et wt:up le dit — tout en vous laissant un conteneur à qui parler. Détail : Worktrees — Mode maintenance.
Le conteneur php n'existe pas du tout¶
La maintenance ne couvre que l'abandon des programmes supervisés. Un conteneur tué (docker rm, OOM killer, arrêt du démon) ou jamais créé n'existe pas. castor wt:shell traite ce cas comme les autres : elle tente d'abord son wt:up, qui recrée le conteneur — après un docker rm ou un OOM killer, le shell s'ouvre alors dans le conteneur de service et il n'y a rien à réparer. Ce n'est que si ce wt:up échoue à son tour que vous obtenez le conteneur jetable, dans lequel vous pouvez réparer le code et les dépendances avant de relancer castor wt:up <ticket> côté hôte.
Le conteneur jetable échoue sur network kirexo-egress … could not be found¶
wt:shell ne crée elle-même ni le réseau kirexo-egress, ni la stack mutualisée kirexo-shared : c'est le préalable de wt:up, joué avant le démarrage de la stack du worktree. Depuis que la cible lance ce wt:up toute seule, le cas est donc rare — un wt:up qui échoue sur le up --wait a déjà exécuté le préalable.
Il reste deux situations où l'erreur survient :
KIREXO_WT_NO_AUTO_UP=1— aucunwt:upn'a été tenté, donc aucun préalable joué ;- le
wt:upautomatique s'est arrêté avant le préalable — en pratique,compose.worktree.yamlabsent de la branche du worktree (les autres arrêts précoces, nom invalide ou chemin sous le dépôt principal, supposent un ticket saisi à la main, ce que ces cibles ne permettent plus). Le message dewt:upest resté affiché au-dessus : il nomme la cause.
Dans les deux cas, jouez castor wt:up <ticket> côté hôte — même s'il échoue ensuite sur le up, le préalable, lui, aura été exécuté — puis reprenez à l'étape 2.
castor wt:claude refuse de démarrer¶
Le conteneur php du worktree ticket-185 ne répond pas.
Le démarrage automatique a échoué — relance : castor wt:up ticket-185
Stack cassée ? castor wt:shell (conteneur jetable, depuis ce répertoire)
wt:claude fait un exec dans le conteneur de service et n'a aucun repli en conteneur jetable : sans conteneur vivant, il n'y a personne à qui parler. Elle a donc tenté un castor wt:up avant de sortir — la sortie de cette tentative est affichée au-dessus du bloc et porte la cause réelle. Ce message veut dire que la stack est cassée, pas simplement arrêtée : c'est wt:shell et son conteneur jetable qui donnent la porte d'entrée. Elle se joue depuis ce même répertoire — vous y êtes déjà, c'est ce qui a permis à wt:claude de résoudre le worktree. Reprenez à l'étape 2, réparez, puis relancez la session.
La deuxième ligne change sous KIREXO_WT_NO_AUTO_UP=1 — Démarrage automatique désactivé (KIREXO_WT_NO_AUTO_UP=1) — lance : castor wt:up ticket-185. Rien n'a alors été tenté, et un wt:up manuel peut suffire.
Si wt:up échoue à son tour sur le proxy hôte, la panne n'est pas dans le worktree : c'est le réseau kirexo-proxy dont l'adresse statique a été raflée. Le remède est castor proxy:migrate, décrit dans wt:up s'arrête sur le proxy hôte.
Une session Claude s'ouvre dans un worktree en panne¶
Elle s'ouvre normalement, et c'est voulu : le gate SessionStart mesure le confinement, jamais la santé de la stack. Une stack morte ne doit pas empêcher d'ouvrir la session qui vient la réparer. Le dashboard signale en revanche les dépendances absentes et rappelle ses deux remèdes — cf. Dépendances absentes.
Un confinement rouge, lui, continue de bloquer. Le cas le plus fréquent dans un worktree neuf est C4 : un répertoire root-owned à la place de infra/firewall/whitelist.local.txt, décrit dans castor firewall:status affiche n'importe quoi dans mon worktree.
wt:list affichait up alors que la stack était morte¶
Symptôme historique, corrigé : le dénominateur de la colonne état était tiré de docker compose ps, qui ne rend que les conteneurs vivants. Un service mort quittait donc numérateur et dénominateur du même geste, et la ligne affichait up (2/2, 2 healthy) avec son php en exited depuis des heures — envoyant chercher la panne ailleurs.
Le dénominateur vient désormais des services déclarés ; le tableau est utilisable comme diagnostic. Si vous lisez encore un up (n/n) sur une stack morte, vérifiez d'abord qu'il ne porte pas un ? : le repli qui produit ce marqueur ne compte, lui, que les conteneurs existants. Voir castor wt:list.
castor s'adressait à la mauvaise stack¶
Symptôme historique, corrigé : lancées depuis un worktree sans vendor/, les cibles ne publiaient ni COMPOSE_PROJECT_NAME ni KIREXO_NETWORK, et Compose retombait sur le basename du répertoire — donc sur une autre stack, ou sur aucune, sans un mot. La lecture de .env.worktree a désormais un repli en Bash pur : le répertoire courant est une base fiable, y compris sur un worktree neuf ou dont l'installation Composer a échoué. C'est heureux, puisque c'est désormais le seul mécanisme de résolution de wt:shell et wt:claude. Voir Castor lit .env.worktree même sans vendor/.
Le même symptôme avait une seconde cause, fermée depuis : le fichier lui-même pouvait manquer, et le repli n'avait alors rien à lire. Les commandes Compose des cibles wt:* portent donc un -p kirexo-<worktree> calculé à partir du worktree résolu — la stack visée est juste en toute circonstance, et le fichier manquant est signalé plutôt que contourné. Voir Le projet Compose visé par les cibles de worktree.
Voir aussi¶
castor wt:shell— les deux chemins de la cible, sa sonde de vitalité et ses limites.castor wt:claude— pourquoi elle exige, elle, un conteneur vivant.- Le démarrage automatique de la stack — le déclencheur unique, la tentative unique et l'échappatoire
KIREXO_WT_NO_AUTO_UP=1. - Le worktree visé — la résolution par le répertoire courant, et ce que rend la commande lancée d'ailleurs.
- Le projet Compose visé par les cibles de worktree — le
-pexplicite, les trois verdicts et ce que chaque cible en fait. - Worktrees — Mode maintenance — ce que la maintenance change, marqueur, healthcheck et relance automatique.
- Relancer FrankenPHP ou le worker Messenger — quand la stack tourne mais qu'un seul des deux programmes est mort.
- Diagnostiquer un blocage réseau sortant — quand le symptôme est un
403du proxy. - Créer et détruire un worktree — le parcours nominal.