Worktrees et environnement de développement¶
Référence factuelle de l'environnement de développement Kirexo : un worktree git par ticket, chacun avec sa stack Docker isolée, son réseau, ses URLs et son fichier d'état. Cette page décrit ce qui existe ; pour les gestes, voir Créer et détruire un worktree ; pour le raisonnement, voir Profils de ressources et mutualisation des services.
Le contenu de l'image exécutée par ces stacks vit dans Image de développement kirexo-dev.
Anatomie d'un worktree¶
Tout dérive d'un identifiant unique, WT (par exemple ticket-185), matérialisé dans un fichier .env.worktree gitignoré à la racine du worktree.
| Élément | Valeur | Où c'est écrit |
|---|---|---|
| Identifiant | WT=ticket-185 — motif [a-z0-9][a-z0-9_-]{0,30} |
.env.worktree |
| Chemin | <parent du dépôt principal>/kirexo-worktrees/ticket-185, ou la racine fixée par KIREXO_WORKTREES_DIR |
wt_worktrees_dir(), infra/worktree/wt.lib.sh |
| Projet Compose | kirexo-ticket-185 — préfixe des conteneurs, volumes et réseaux. Déclaré par COMPOSE_PROJECT_NAME, et imposé en -p par les cibles wt:*, qui le calculent à partir du nom du worktree |
.env.worktree ; ComposeProject::expected(), castor/src/Worktree/ComposeProject.php |
| Réseau de la stack | KIREXO_NETWORK=kirexo-ticket-185, déclaré internal: true |
compose.override.yaml, bloc networks.default |
| Image | kirexo-dev-local:ticket-185 (KIREXO_IMAGE_TAG) |
compose.override.yaml, service php |
| Branche | Le nom du worktree, sauf si une branche <numéro>-* existe déjà en local ou sur origin — auquel cas elle est réutilisée |
wt_resolve_branch(), castor/worktree.php |
| Fichiers Compose empilés | compose.yaml + compose.override.yaml + compose.worktree.yaml (+ compose.full.yaml en profil full) |
wt_compose_files(), castor/worktree.php |
var/claude |
Lien vers <dépôt principal>/var/claude (KIREXO_SHARED_CLAUDE_DIR), monté au même chemin absolu dans le conteneur |
wt_reconcile_shared_claude(), castor/worktree.php ; bind dans compose.worktree.yaml |
Le worktree git est créé avec --lock : dans le conteneur, le gitdir des autres worktrees pointe un chemin hôte inexistant, et un git worktree prune — appelé aussi par git gc — supprimerait leurs métadonnées. castor wt:destroy lève le verrou explicitement.
Un worktree ne vit jamais sous le dépôt principal
wt:up refuse un chemin situé sous le dépôt principal : il entrerait dans son bind .:/app et ferait tomber les invariants de confinement C1 et C8. C'est une contrainte de confinement, pas une préférence.
Aucune subnet n'est allouée par le projet. Docker est l'IPAM : il choisit la plage, garantit la non-superposition et refuse le up en cas de conflit. WT_GATEWAY_IP est relevée sur le réseau réel après le premier up, jamais calculée.
Services : dédiés vs mutualisés¶
Le profil de ressources est porté par COMPOSE_PROFILES dans .env.worktree — light par défaut, mémorisé d'un wt:up à l'autre. Les fichiers Compose empilés sont les mêmes dans les deux profils : ce qui change est la valeur de COMPOSE_PROFILES, qui active (ou non) les services marqués profiles: ["full"].
| Service | Profil light |
Profil full |
|---|---|---|
php (FrankenPHP + worker Messenger) |
dédié au worktree | dédié |
database (PostgreSQL) |
dédié au worktree | dédié |
docs (mkdocs serve) |
dédié au worktree | dédié |
redis |
mutualisé (kirexo-shared) |
dédié — défini par compose.yaml, rattaché au réseau du worktree par compose.full.yaml |
rabbitmq |
mutualisé (kirexo-shared) |
dédié, même mécanique |
typesense |
mutualisé (kirexo-shared) |
dédié, même mécanique |
gotenberg |
mutualisé (kirexo-shared) |
dédié, même mécanique |
mailer (Mailpit) |
mutualisé (kirexo-shared) |
dédié — entièrement redéclaré par compose.full.yaml, ce service n'existant pas dans compose.yaml |
egress-proxy (Squid) |
mutualisé (kirexo-shared) |
mutualisé — jamais dédié |
autoheal |
mutualisé (kirexo-shared) |
mutualisé — jamais dédié |
caddy-proxy |
mutualisé (kirexo-proxy) |
mutualisé — jamais dédié |
Décompte en profil light avec trois worktrees actifs :
| Projet Compose | Conteneurs |
|---|---|
kirexo-ticket-a, kirexo-ticket-b, kirexo-ticket-c |
3 × 3 = 9 |
kirexo-shared |
7 (egress-proxy, redis, rabbitmq, typesense, gotenberg, mailer, autoheal) |
kirexo-proxy |
1 (caddy-proxy) |
| Total | 17 |
Le décompte se relève côté hôte :
docker ps -q --filter 'name=^kirexo' | wc -l
docker ps --filter 'label=com.docker.compose.project' \
--format '{{.Label "com.docker.compose.project"}}' | sort | uniq -c
autoheal et caddy-proxy sont des singletons de poste, pas des services de stack : ils ne réapparaissent pas en profil full. Le raisonnement — et l'isolation logique qui rend la mutualisation sûre — est dans Profils de ressources et mutualisation des services.
Les deux projets singletons, kirexo-shared et kirexo-proxy, sont créés une fois pour le poste — donc depuis le répertoire de la première stack démarrée, souvent un worktree, dont Compose fige les chemins de bind mount en absolu. Le parentage se relève par conteneur :
docker inspect -f '{{index .Config.Labels "com.docker.compose.project.working_dir"}}' kirexo-shared-egress-proxy-1
docker inspect -f '{{range .Mounts}}{{.Source}}{{"\n"}}{{end}}' kirexo-shared-egress-proxy-1
castor wt:destroy défait ce parentage avant de retirer un worktree ; un répertoire supprimé à la main le laisse en place, avec la panne décrite dans Un singleton est parenté sur le répertoire qui l'a créé. Les fichiers qui les décrivent, et que wt:destroy passe en -f lors d'une recréation, sont compose.shared.yaml et infra/proxy/compose.proxy.yaml (wt_singleton_projects(), castor/worktree.php).
Réseaux¶
Le conteneur php est attaché à quatre réseaux, tous sans route par défaut.
| Réseau | Déclaré par | Rôle |
|---|---|---|
${KIREXO_NETWORK:-kirexo} (réseau default du projet) |
compose.override.yaml, internal: true |
Trafic intra-stack : database, docs. Nom paramétré par worktree. |
kirexo-egress (external: true) |
compose.shared.yaml, projet kirexo-shared |
Lien vers le proxy sortant mutualisé. |
kirexo-proxy (external: true) |
infra/proxy/proxy-net.sh |
Lien vers le proxy Caddy hôte, qui sert les URLs. |
kirexo-services (external: true) |
compose.shared.yaml |
Lien vers les backing services mutualisés. |
Un seul réseau non-internal annulerait l'isolation
Attacher au conteneur php un réseau qui n'est pas internal lui rendrait une route par défaut vers Internet — sans aucun signal applicatif. C'est ce que l'invariant C3 vérifie par son effet. Seuls egress-proxy et caddy-proxy voient à la fois un réseau interne et un bridge NAT.
Les réseaux external doivent exister avant tout docker compose up, sinon Compose échoue sur network <nom> declared as external, but could not be found. C'est le helper shared_stack_up() de castor.php qui les crée ; il est appelé par castor docker:up, castor docs:build, castor wt:up et castor image:refresh.
Nommage DNS et URLs¶
Chaque worktree expose trois URLs, servies par le proxy Caddy hôte sur 127.0.0.1 :
| URL | Upstream |
|---|---|
https://app.<worktree>.localhost |
php-<worktree>:8080 |
https://docs.<worktree>.localhost |
docs-<worktree>:8000 |
https://mailpit.<worktree>.localhost |
mailpit-shared:8025 — boîte mutualisée, seul le nom d'hôte est par worktree |
Les trois portent un préfixe de service, application comprise : c'est ce qui leur donne au moins deux labels sous .localhost, donc un certificat valide. Un nom d'un seul label recevrait le wildcard *.localhost du repli, qu'aucun client n'accepte — cf. Pourquoi tout nom servi a au moins deux labels. Elles sont rendues par wt_urls (infra/worktree/wt.lib.sh).
Le dépôt principal utilise le suffixe main (https://app.main.localhost, https://docs.main.localhost, https://mailpit.main.localhost) : les alias réseau sont rendus par php-${WT:-main} et docs-${WT:-main}. Le nom vient de la branche que porte l'arbre de travail principal.
Un worktree par défaut est désigné dans la configuration du proxy (repère * dans castor wt:list) : il sert *.localhost et le bloc explicite app.demo.localhost, donc les domaines de site publics, et reçoit la redirection 308 de https://localhost.
Noms de worktree réservés
app, demo, mailpit, localhost, www, shared et proxy sont refusés par wt:up (KIREXO_PROXY_RESERVED_WT, infra/proxy/proxy.lib.sh), pour trois motifs distincts : demo seul produirait une adresse de site dupliquée (app.demo.localhost, déjà déclarée dans le repli) ; app, mailpit, localhost et www sont écartés pour ambiguïté de lecture ou de routage, sans qu'aucune adresse ne soit dupliquée ; shared et proxy pour collision de nom de projet Compose, pas de routage. main l'est aussi, mais par un autre chemin — wt_normalize_name et proxy_write_site le refusent comme nom de worktree utilisateur tout en l'acceptant comme worktree par défaut. Motif nom par nom : wt:up refuse le nom que je lui donne.
Aucun service de stack ne publie de port. Le seul conteneur qui publie quoi que ce soit est caddy-proxy, et uniquement sur la loopback : 127.0.0.1:80, 127.0.0.1:443/tcp et 127.0.0.1:443/udp (HTTP/3). Le détail du routage, du TLS interne et du cloisonnement est dans Routage des worktrees : DNS, TLS et cloisonnement réseau.
Fichiers d'allowlist de la sortie réseau¶
| Fichier | Suivi par git | Rôle |
|---|---|---|
infra/firewall/baseline-domains.txt |
oui | Source de vérité de l'allowlist partagée par l'équipe. Une ligne = un FQDN exact sans point de tête ; # en début de ligne pour commenter. Lu côté bash par infra/egress/render-allowlist.sh et côté PHP par castor/src/Firewall/FirewallWhitelist.php. |
infra/firewall/whitelist.local.txt |
non (gitignoré) | Override du poste, même format. Créé depuis whitelist.local.txt.dist par castor wt:up et par le préalable des cibles de démarrage. |
infra/egress/generated/allowlist.conf |
non | Fichier généré, lu par l'ACL dstdomain de Squid. Chaque entrée y est rendue sous la forme .<domaine>, qui couvre le domaine et tous ses sous-domaines. |
Ces trois chemins sont ceux du dépôt principal, pas du worktree
Les cibles firewall:* lisent, écrivent et rendent dans le dépôt principal, quel que soit le checkout d'où elles sont lancées : c'est de là que le proxy mutualisé est démarré, et donc de là que ses montages sont résolus. Les exemplaires d'un worktree existent bien sur disque — castor wt:up crée le whitelist.local.txt du worktree — mais servent uniquement de substrat au bind :ro ci-dessous ; ils n'alimentent pas l'allowlist. Cf. Une seule whitelist, celle du dépôt principal.
Les dossiers infra/firewall/, infra/lib/ et infra/egress/ sont bind-montés en lecture seule dans le conteneur : une écriture y échoue en EROFS, au niveau du noyau. C'est la moitié « noyau » du double verrou de l'invariant C4 ; l'autre moitié est la restriction hôte-only des cibles de rechargement.
Deux autres dossiers d'infra/ portent le même bind :ro, pour une raison voisine mais distincte : infra/healthcheck/ et infra/supervisor/. Leurs scripts sont exécutés en boucle par Docker (le healthcheck du service php) et par le conteneur lui-même (command: du service, qui lance supervisor.sh start all). Réinscriptibles depuis /app, ils permettraient de neutraliser la détection de panne ou de détourner ce qui est lancé au démarrage.
Ce sont des dossiers qui sont montés, jamais des fichiers
Un bind de fichier attache un inode, pas un chemin. Une écriture côté hôte en write + rename — sed -i, un éditeur, un script de patch — crée un nouvel inode, et le conteneur reste attaché à l'ancien : il verrait l'ancien contenu au sein d'un /app par ailleurs à jour, sans le moindre signal. Le bind de dossier résout les entrées à chaque accès.
Recette d'ajout : Ouvrir un domaine dans l'allowlist du proxy sortant.
Variables d'environnement du worktree¶
.env.worktree porte 16 clés générées et réconciliées par castor wt:up (wt_managed_keys(), infra/worktree/env.lib.sh). Les clés hors contrat qu'un développeur y ajoute sont préservées.
| Clé | Valeur pour ticket-185 |
Ce qu'elle isole |
|---|---|---|
WT |
ticket-185 |
L'identifiant dont tout le reste dérive. |
COMPOSE_PROJECT_NAME |
kirexo-ticket-185 |
Conteneurs, volumes, réseaux. |
COMPOSE_PROFILES |
light ou full |
Le profil de ressources. |
KIREXO_NETWORK |
kirexo-ticket-185 |
Le réseau de la stack. |
KIREXO_IMAGE_TAG |
ticket-185 |
Le tag de la surcouche locale. |
KIREXO_GIT_COMMON_DIR |
chemin hôte absolu | Le common dir git, monté au même chemin dans le conteneur. |
KIREXO_SHARED_CLAUDE_DIR |
chemin hôte absolu (<dépôt principal>/var/claude) |
L'espace de travail des skills, partagé avec le dépôt principal : monté au même chemin dans le conteneur, et var/claude du worktree en devient un lien. |
KIREXO_RESERVED_DOMAINS |
localhost,127.0.0.1,app.ticket-185.localhost,ticket-185.localhost |
Empêche la résolution multi-tenant de prendre l'URL du worktree pour un domaine de site. L'ancien nom sans préfixe y reste listé pour les signets : il n'existe que dans la liste déjà régénérée, et ne couvre donc aucune fenêtre de migration (détail). |
MAIL_FROM |
[ticket-185] Kirexo <noreply@kirexo.local> |
Rend lisible la boîte Mailpit mutualisée. |
REDIS_DB_INDEX |
1…15 (0 réservé au dépôt principal) |
L'index Redis dans l'instance mutualisée. |
RABBITMQ_VHOST |
ticket-185 |
Le vhost RabbitMQ, créé et autorisé par wt:up. |
TYPESENSE_COLLECTION_PREFIX |
ticket-185_ |
Le préfixe des collections Typesense. |
XDEBUG_CLIENT_PORT |
9004…9066 (9003 réservé au dépôt principal) |
Le port d'écoute de la fenêtre PhpStorm de ce worktree. |
XDEBUG_CONFIG |
client_host=… client_port=… idekey=ticket-185 |
La valeur qui fait foi côté conteneur. |
PHP_IDE_CONFIG |
serverName=ticket-185 |
Le rattachement d'une session CLI au path mapping de l'IDE. |
WT_GATEWAY_IP |
relevée après le premier up |
L'adresse hôte joignable depuis un réseau internal (extra_hosts). |
XDEBUG_CLIENT_PORT et REDIS_DB_INDEX sont alloués une fois puis réutilisés tels quels : réallouer à chaque wt:up casserait la configuration PhpStorm du développeur. L'allocation est sérialisée par le verrou ~/.kirexo/wt-alloc.lock.
.env.worktree absent = mode mono-worktree : chaque variable retombe sur son défaut historique et la stack se comporte comme avant l'introduction des worktrees. C'est le mode du dépôt principal.
Dans un worktree, en revanche, ce fichier ne manque jamais normalement : son absence est un état cassé, pas un mode. Les cibles wt:* visent alors quand même la bonne stack — elles passent -p kirexo-<worktree>, calculé sans le fichier — mais elles le disent au lieu de se replier en silence : wt:shell et wt:claude sortent en 1, wt:destroy avertit et détruit, wt:list marque la ligne. Détail : Le projet Compose visé par les cibles de worktree.
Les définitions complètes, leurs lecteurs et leur précédence sont dans Variables de worktree. Les variables de sortie réseau (HTTP_PROXY, HTTPS_PROXY, NO_PROXY et leurs formes minuscules, NODE_USE_ENV_PROXY) ne vivent pas dans .env.worktree : elles sont posées par l'ancre x-proxy-env de compose.override.yaml — cf. Sortie réseau via le proxy. CLAUDE_CONFIG_DIR et GITLAB_TOKEN relèvent de l'espace commun ~/.kirexo — cf. Espace Claude et jeton GitLab. La configuration git du conteneur (GIT_CONFIG_*, identité, core.hooksPath) n'y vit pas non plus : elle est posée par compose.override.yaml, commun au dépôt principal et aux worktrees — cf. Git dans le conteneur.
var/claude est commun, var/claude/.session/<worktree>/ ne l'est pas
Le dossier partagé porte la mémoire de travail des skills (cadrage d'étape, specs de lots, scripts de ship). L'état d'une session — checklist de clôture, quota de fichiers PHP, compteur de blocage, verdict de revue, checkpoints des sous-agents — reste namespacé par worktree, sous var/claude/.session/<worktree>/ (main pour le dépôt principal). Sans ce namespace, deux agents en parallèle s'écraseraient mutuellement leur état. Résolution : .claude/hooks/lib/session-dir.sh ; détail des fichiers : Hooks Claude Code.
Supervision des process long-running¶
Le conteneur php fait tourner deux programmes de longue durée sous un supervisor unique, infra/supervisor/supervisor.sh. En développement, il n'existe pas de service Compose worker : le worker Messenger vit dans le même conteneur que FrankenPHP. La production, elle, sépare les deux en services distincts — cf. Pourquoi un worker Messenger dédié et un verrou sur le planificateur.
| Programme | Commande supervisée | Journal |
|---|---|---|
frankenphp |
frankenphp run --config /etc/caddy/Caddyfile --watch |
var/log/supervisor/frankenphp.log |
messenger |
php bin/console messenger:consume ${KIREXO_WORKER_TRANSPORTS:-scheduler_default plugin_web async} --time-limit=3600 --memory-limit=192M -vv |
var/log/supervisor/messenger.log |
Le défaut de KIREXO_WORKER_TRANSPORTS est le même que celui du service worker de production, et comprend scheduler_default : le worker de développement déclenche donc les tâches périodiques, dont la purge de la corbeille. Détail de la variable : Worker Messenger.
Le supervisor journalise lui-même dans var/log/supervisor/supervisor.log.
Le point de vérité de ce chemin est supervisor_log_dir() (infra/supervisor/supervisor.lib.sh), en miroir de var/run/supervisor/ qui porte les PID files des mêmes programmes — cf. Variables internes aux scripts du conteneur.
Sous-commandes (infra/supervisor/supervisor.sh <commande> [all|<programme>]) :
| Commande | Comportement |
|---|---|
start all |
Supervise en avant-plan : c'est le command: du service php. Lance chaque boucle comme un vrai process supervisor.sh start <p>, identifiable par /proc. Un bail-out isolé ne fait pas tomber les autres. |
start <p> |
Exécute la boucle d'un seul programme, en avant-plan. Primitive non idempotente : elle ne vérifie pas si une boucle existe déjà. La voie de relance est spawn. |
spawn [all\|<p>] |
Détache la ou les boucles puis rend la main. Idempotent : ne démarre rien si une boucle du programme est vivante, qu'elle soit découverte par /proc ou par le PID file. Attend jusqu'à SUPERVISOR_SPAWN_WAIT que la boucle lancée soit visible, sinon rend 1. |
stop [all\|<p>] |
Arrête toutes les boucles découvertes du programme, jamais le programme seul, qui serait aussitôt relancé. SIGTERM à toutes, puis SIGKILL à chaque survivante et à ses enfants après STOP_GRACE + 2 s (STOP_GRACE vaut 20 s par défaut). N'envoie jamais de signal au PID 1. |
restart <p> |
stop puis spawn du seul programme désigné, sous un même verrou. all est refusé. |
status [all\|<p>] |
Une ligne par programme : <p> <RUNNING\|STOPPED> pid=<pids séparés par des virgules, ou -> child=… uptime=… last_exit=… loops=<N>. Si N > 1, une ligne d'anomalie suit : <p> : <N> boucles actives (pid <liste>) — attendu : 1. Remède : infra/supervisor/supervisor.sh restart <p>. Exit 0 si tous les programmes demandés tournent, y compris avec N > 1. Ne prend pas le verrou. |
status rend 0 même avec plusieurs boucles, parce que castor messenger:consume et supervisor_program_running() (castor/supervisor.php) lisent ce code comme « le programme tourne ». Un 1 ferait lancer un consommateur de plus, et aggraverait l'anomalie.
Une seule boucle par programme¶
Le supervisor garantit une seule boucle, et donc un seul process surveillé, par programme et par espace de travail. Trois mécanismes y concourent :
| Mécanisme | Règle |
|---|---|
Découverte par /proc |
supervisor_loop_pids <p> [<workspace>] (infra/supervisor/supervisor.lib.sh) retient un process si sa ligne de commande se termine exactement par supervisor.sh start <p>, et si le KIREXO_WORKSPACE de son /proc/<pid>/environ vaut l'espace de travail demandé (/app s'il est absent). Un process dont l'environ est illisible n'est pas retenu. Les sous-shells éphémères d'une boucle, qui portent un instant la même ligne de commande, ne sont pas comptés : un candidat dont un ancêtre est lui-même une boucle est écarté. Une boucle dont le PID file a été effacé reste visible. |
| Verrou | spawn, stop et restart s'exécutent sous un verrou flock exclusif sur var/run/supervisor/supervisor.lock, attendu au plus SUPERVISOR_LOCK_TIMEOUT secondes, puis abandon en code 75. La relance automatique du healthcheck passe par spawn et attend donc la fin d'un restart en cours. start all tient le verrou pendant sa phase de lancement, puis le temps de chaque vérification de la veille du marqueur de maintenance, qu'il tente sans attendre (flock -n). Les boucles lancées n'héritent pas du verrou. |
| Propriété des PID files | Une boucle qui s'arrête ou abandonne ne supprime <p>.pid et <p>.child.pid que s'ils portent ses PID. Elle ne peut donc pas effacer le PID file d'une autre boucle. |
Transition : boucles lancées avant ce mécanisme
Les boucles lancées par une version antérieure de start all ont la ligne de commande supervisor.sh start all : /proc ne les reconnaît pas. spawn, stop et status les voient quand même, par l'union avec le PID file. Le garde du healthcheck, lui, ne consulte que /proc ; le spawn all qu'il déclenche voit l'ancienne boucle par son PID file et ne relance rien. La transition se termine au redémarrage du conteneur php.
Les fichiers d'état vivent sous var/run/supervisor/ : <p>.pid (PID de la boucle), <p>.child.pid (PID du process surveillé — son changement prouve un recyclage), <p>.started_at, <p>.last_exit, et supervisor.lock (verrou de spawn/stop/restart, un par espace de travail).
Paramètres du supervisor, lus dans l'environnement de supervisor.sh. Aucun n'est déclaré dans compose*.yaml, .env* ni le Dockerfile : les valeurs par défaut s'appliquent.
| Variable | Défaut | Rôle |
|---|---|---|
SUPERVISOR_LOCK_TIMEOUT |
60 (s) |
Attente maximale du verrou par spawn, stop et restart. Supérieure à la durée d'un restart (STOP_GRACE + 2 puis SUPERVISOR_SPAWN_WAIT), pour qu'un spawn all du healthcheck passe derrière. |
SUPERVISOR_SPAWN_WAIT |
5 (s) |
Délai maximal pour qu'une boucle lancée devienne visible par /proc. Le verrou n'est relâché qu'une fois la boucle visible. |
SUPERVISOR_MAINTENANCE_POLL |
30 (s) |
Période de la veille du marqueur de maintenance par start all, alignée sur le healthcheck. Toute valeur qui n'est pas un entier strictement positif est remplacée par 30, avec une ligne SUPERVISOR_MAINTENANCE_POLL invalide (« <valeur> ») — 30 s. dans supervisor.log. Voir Mode maintenance. |
SUPERVISOR_TEST_COMMAND |
(vide) | Tests uniquement, jamais déclarée. Non vide, elle remplace la commande de tout programme valide (mots séparés par des espaces), ce qui permet aux bats de lancer de vraies boucles isolées. Sans effet sur un programme inconnu. |
Les deux boucles sont indépendantes : backoff, compteur de crashs, bail-out, PID files et journaux sont par programme. Recette de relance : Relancer FrankenPHP ou le worker Messenger.
Mode maintenance¶
Quand les boucles lancées par start all sont toutes terminées, le supervisor ne sort pas. Il entre en veille jusqu'au SIGTERM du conteneur, et maintient var/run/supervisor/maintenance en accord avec l'état présent : le conteneur est en maintenance tant qu'aucune boucle de supervision ne vit, quel que soit le programme.
Une boucle d'origine se termine de deux façons : un bail-out (MAX_CRASHES = 5 crashs consécutifs), ou un stop — y compris celui d'un restart <p>, qui la remplace par une boucle détachée que start all n'a pas lancée. La fin des boucles d'origine ne vaut donc pas maintenance à elle seule ; c'est la veille qui tranche.
| Veille | Règle |
|---|---|
| Entrée | Une ligne dans supervisor.log : boucles d'origine terminées — veille du marqueur de maintenance toutes les <N>s. |
| Rythme | Une première vérification dès l'entrée en veille, puis une toutes les SUPERVISOR_MAINTENANCE_POLL secondes (30 par défaut). |
| Boucles comptées | Toutes les boucles de l'espace de travail découvertes par /proc (supervisor_any_loop_alive, infra/supervisor/supervisor.lib.sh), boucles relancées par spawn comprises. Le PID file n'est pas lu, et le parent start all n'est jamais compté. |
| Verrou | Chaque vérification tente le verrou du supervisor sans attendre. S'il est tenu (spawn, stop ou restart en cours), la vérification est sautée, sans log ni changement du marqueur, et rejouée à la période suivante. |
| Aucune boucle vivante, marqueur absent | Le marqueur est écrit, et deux lignes sont journalisées : toutes les boucles ont abandonné — MAINTENANCE : le conteneur reste debout pour être réparé. puis journaux : <dossier des journaux>/ · relance : castor supervisor:frankenphp-restart. |
| Au moins une boucle vivante, marqueur présent | Le marqueur est effacé, et une ligne est journalisée : boucle(s) de nouveau vivante(s) — fin de la MAINTENANCE. |
| État inchangé | Rien : ni écriture, ni log. L'horodatage du marqueur reste celui de la dernière bascule. |
Les lignes de la veille sont émises sur la sortie du conteneur et ajoutées à var/log/supervisor/supervisor.log.
Conséquences de cette règle :
- après
castor supervisor:frankenphp-restartetcastor supervisor:worker-restart --hard, les boucles relancées vivent : aucun marqueur n'apparaît ; - un
stop allvolontaire sousstart alllaisse le conteneur sans boucle : le marqueur est écrit à la vérification suivante, avecprogrammes abandonnés : frankenphp messenger, jusqu'au prochainspawn; - en panne persistante, le marqueur alterne :
spawn all(healthcheck) l'efface, les boucles relancées abandonnent à leur tour, la veille le réécrit. Chaque bascule réelle produit sa propre ligne de log.
start all est le command: du service php (compose.override.yaml) : sortir ici ferait sortir le conteneur, et emporterait avec lui le shell et le process claude, qui vit dedans. Le worktree deviendrait irréparable de l'intérieur — la panne se refermant sur elle-même : vendor/ absent → FrankenPHP en bail-out → conteneur mort → aucun moyen d'installer vendor/.
Ce que la maintenance change, et ce qu'elle ne change pas :
| Élément | En maintenance |
|---|---|
Conteneur php |
UP. castor wt:shell, lancée depuis le répertoire du worktree, y ouvre un shell par exec, sans conteneur jetable. |
| Healthcheck Docker | ROUGE, volontairement. FrankenPHP ne répond pas : l'état n'est pas maquillé, docker compose up --wait échoue et castor wt:up le dit. |
| Marqueur | var/run/supervisor/maintenance, contenant l'horodatage de la dernière bascule et la liste des programmes de start all (supervisor_maintenance_notice, infra/supervisor/supervisor.lib.sh). |
supervisor.sh status |
Affiche le contenu du marqueur avant les lignes par programme, qui valent toutes STOPPED. |
| Relance automatique | Maintenue. Quand FrankenPHP ne répond pas et qu'aucune boucle frankenphp n'est découverte par /proc (supervisor_loop_pids), le healthcheck détache un supervisor.sh spawn all au plus toutes les 30 s (infra/healthcheck/php-healthcheck.sh). Ce spawn passe par le verrou du supervisor : il ne s'intercale jamais dans un restart en cours. |
| Redémarrage du conteneur | Aucun. php garde restart: no (compose.yaml) et ne porte pas le label autoheal — dans la stack du worktree, seul docs le porte (egress-proxy aussi, mais il vit dans kirexo-shared). Un redémarrage automatique remplacerait la panne par une boucle. |
Conséquence directe : une réparation faite depuis le conteneur (un composer install, une correction de configuration) fait repartir la stack d'elle-même au cycle de healthcheck suivant, sans repasser par un terminal hôte. Le marqueur est effacé sans condition par start all à son lancement et par spawn, et par la veille dès qu'une boucle vit ; la veille le réécrit si plus aucune boucle ne vit.
Deux exceptions à connaître :
start <programme>(un seul programme) n'a pas de veille et n'écrit jamais le marqueur : cette forme sert lespawnd'un programme isolé, pas lecommand:du service ;- un bail-out partiel — un seul programme abandonné, l'autre vivant — n'est pas une maintenance : aucun marqueur n'est écrit, et le programme survivant continue de servir.
La recette est dans Réparer un worktree dont la stack ne démarre plus.
TLS interne du conteneur : skip_install_trust¶
Le bloc global de frankenphp/Caddyfile active skip_install_trust, qui empêche Caddy d'installer sa CA racine dans le trust store du conteneur. Sans cette directive, Caddy tenterait d'écrire dans /usr/local/share/ca-certificates/ au démarrage — ce qui exige des privilèges que le conteneur n'a plus (sudo n'est plus installé, cf. Image de développement).
Conséquence : la CA de Caddy n'est pas dans le trust store du conteneur. Aucun client TLS interne n'en a besoin — le seul client TLS concerné est le navigateur côté hôte, qui fait confiance à la racine du proxy via castor cert:trust. Sans effet en production : Let's Encrypt n'utilise pas la PKI locale.
Cibles Castor : hôte-only ou in-container¶
castor.php détecte l'intérieur du conteneur via is_inside_container() : la variable KIREXO_INSIDE_CONTAINER=1 ou la présence de /.dockerenv. Sans ce second signal, un docker compose exec php castor … lancé depuis l'hôte croirait être sur l'hôte et retenterait un docker compose exec à l'intérieur, sans socket Docker.
Cibles refusées à l'intérieur (hôte uniquement)¶
Elles appellent assert_outside_container() et sortent en erreur avec un message qui indique où relancer.
| Cible | Raison |
|---|---|
castor docker:up / docker:down / docker:build / docker:logs / docker:sh |
Pilotage de la stack — exige le démon Docker. |
castor wt:up / wt:shell (alias wt:bash) / wt:claude / wt:list / wt:destroy / wt:gc |
Cycle de vie des stacks de worktree. wt:shell ouvre un shell dans le conteneur php du worktree du répertoire courant et wt:claude y lance Claude Code — depuis le conteneur, vous y êtes déjà. Le refus nomme l'endroit d'où relancer : la racine du dépôt principal pour les quatre cibles qui prennent un ticket, le répertoire du worktree pour wt:shell et wt:claude, qui n'en prennent pas. |
castor proxy:up / proxy:down / proxy:reload / proxy:migrate / proxy:status |
Proxy Caddy hôte. proxy:migrate recrée en plus le réseau kirexo-proxy : elle descend les stacks attachées, ce qui exige le démon Docker de l'hôte. |
castor cert:trust |
Extraction de la CA depuis le volume Caddy + installation dans le trust store hôte. |
castor docs:build |
docker compose build + run du service mkdocs. |
castor image:upgrade-tools / image:refresh |
Réécriture des ARG du Dockerfile, appels à des CDN hors allowlist, pilotage d'images. |
castor firewall:reload / firewall:whitelist-add / firewall:whitelist-remove |
Moitié « procédurale » du double verrou de C4 : les whitelists sont montées :ro dans le conteneur. |
castor monitor |
TUI branché sur l'admin API du service FrankenPHP depuis l'hôte. |
castor host:check |
Checklist des fichiers d'infrastructure que le conteneur ne devrait pas — ou ne peut pas — modifier. |
castor ci:local <job> |
Exécution réelle d'un job — sibling containers. (castor ci:local sans argument valide la config des deux côtés.) |
castor dod:check / dod:tls / dod:clean |
Sondes de Definition of Done (infra/dod/) : elles pilotent Docker, créent et détruisent des worktrees et recréent des conteneurs de la stack mutualisée. Le refus nomme le terminal hôte. Détail : Definition of Done. |
Cibles réservées à l'intérieur du conteneur¶
| Cible | Raison |
|---|---|
castor supervisor:frankenphp-restart |
Relance le programme FrankenPHP supervisé sans toucher au worker. Refuse un redémarrage à moins de 30 s du précédent — le hub Mercure tient encore le lock du transport bolt ; --force outrepasse. |
castor supervisor:worker-restart |
Recycle le worker Messenger : arrêt gracieux par messenger:stop-workers, puis attente d'un changement de PID enfant. --hard tue la boucle et le process. |
Cibles qui s'adaptent¶
| Cible | Adaptation |
|---|---|
cs:fix, phpstan, lint, lint:shell, test:unit, test:bash, test:e2e, test:path-coverage, composer, console, php, cache:clear, tailwind:build, install, reinstall, messenger:consume, doctrine:*, fixtures:load, mate |
Exécution directe à l'intérieur (pas de wrap docker compose exec). Cf. php_exec() dans castor.php. |
castor audit |
Exécution directe à l'intérieur (composer y est présent) ; depuis l'hôte, conteneur composer:2 jetable qui monte le dépôt. --locked ne lit que composer.lock : ni la stack ni vendor/ ne sont nécessaires. |
castor composer:validate |
Même schéma que castor audit : composer à l'intérieur, conteneur composer:2 jetable depuis l'hôte. Seuls composer.json et composer.lock sont lus — la stack du worktree peut être arrêtée. |
castor firewall:status |
Tourne des deux côtés, sans garde : c'est la capacité de lecture volontairement laissée à l'agent. Les sondes ne sont pertinentes que depuis le conteneur. |
castor confinement:check |
--profile=container (défaut), ci ou host. Le profil host porte la sonde C2h et ne tourne que depuis un terminal hôte. |
castor doctor |
Diagnostic des deux côtés : depuis l'hôte (binaires, stack, migrations), depuis le conteneur (amorçage, sortie réseau, supervision, transports, résolution intra-stack). |
castor ts:check |
Utilise le binaire node de l'image à l'intérieur ; démarre un conteneur node:22-alpine jetable depuis l'hôte. |
castor test:coverage |
Comme test:unit, avec XDEBUG_MODE=coverage. Le préflight « stack healthy » de --with-e2e est sauté à l'intérieur. |
Le détail des options de chaque cible est dans Commandes Castor.
Voir aussi¶
- Créer et détruire un worktree — le geste.
- Réparer un worktree dont la stack ne démarre plus —
castor wt:shell, mode maintenance, réparation depuis l'intérieur. - Brancher PhpStorm sur un worktree — interpréteur distant, path mappings, Xdebug.
- Image de développement
kirexo-dev— contenu de l'image, versions figées, autocomplétion. - Profils de ressources et mutualisation des services — pourquoi
lightpar défaut. - Amorcer
vendor/plutôt que le retélécharger — ce que coûte un worktree neuf, et ce que la copie évite. - Routage des worktrees : DNS, TLS et cloisonnement réseau — le pourquoi du proxy hôte.
- Modèle de menace et contrat de confinement — les invariants et leur raison d'être.
- Variables de worktree — la fiche de chaque clé.