Aller au contenu

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:shell et wt:claude n'ont pas d'argument, elles visent le worktree du répertoire courant. Les six cibles castor 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 :

KIREXO_WT_NO_AUTO_UP=1 castor wt:shell

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.

cd /…/kirexo-worktrees/ticket-185
castor wt:shell

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 :

hostname   # kirexo-ticket-185-php-… ou kirexo-ticket-185-php-run-…

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é :

cat var/run/supervisor/maintenance
maintenance depuis <horodatage ISO 8601>
programmes abandonnés : frankenphp messenger

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 :

infra/supervisor/supervisor.sh status

Le diagnostic complet, avec ses remédiations séparées en « dans le conteneur » et « action hôte requise » :

castor doctor

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 :

composer install

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) :

castor firewall:status          # dans le conteneur : ce qui est réellement appliqué
castor firewall:whitelist-add <domaine>   # côté hôte

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 :

castor supervisor:frankenphp-restart

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 :

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

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 :

castor wt:up 185

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

castor wt:list                        # état, santé et URLs de tous les worktrees

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 :

castor wt:up 185 --fixtures           # DESTRUCTIF : la base est purgée puis rechargée

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.

castor wt:up 185

Trois choses à savoir sur ce cas :

  • wt:shell ne 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=1 ne change rien ici : ce n'est pas un démarrage qui est refusé, c'est l'entrée. Même comportement, même message, pour castor 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 attendu kirexo-<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 avec docker compose ls et castor wt:list.
  • castor wt:list vous 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 état arrê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 — aucun wt:up n'a été tenté, donc aucun préalable joué ;
  • le wt:up automatique s'est arrêté avant le préalable — en pratique, compose.worktree.yaml absent 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 de wt:up est 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