Profils de ressources et mutualisation des services¶
Kirexo fait tourner plusieurs worktrees en parallèle, chacun avec sa stack Docker. Cette page explique pourquoi la stack par défaut d'un worktree ne compte que trois conteneurs, ce que le profil full coûte et ce qu'il rend, et surtout pourquoi partager Redis, RabbitMQ et Typesense entre plusieurs branches n'est pas une négligence.
L'inventaire factuel — quel service dans quel profil, quel projet Compose, quelles variables — est dans Worktrees et environnement de développement. Cette page dit le pourquoi.
Le problème : la stack ne passe pas à l'échelle¶
Une stack Kirexo complète, c'est huit services : php, database, docs, redis, rabbitmq, typesense, gotenberg, mailer. Tant qu'il n'y en a qu'une, ce chiffre ne pose aucune question.
Le jour où l'on veut travailler sur trois tickets en parallèle — un en revue, un en développement, un pour un correctif urgent — il en faudrait vingt-quatre. Sur un poste de développement ordinaire, ce n'est pas une gêne théorique : Typesense, RabbitMQ et PostgreSQL réservent chacun leur mémoire au démarrage, et trois instances de chaque suffisent à faire ramer l'ensemble. On finit par ne plus lancer qu'un worktree à la fois — ce qui annule l'intérêt d'en avoir plusieurs.
Le constat qui tranche : tous les services ne se valent pas¶
En observant ce qu'on fait réellement de chaque service pendant une journée de développement, deux familles apparaissent.
D'un côté, ceux dont l'état est le travail lui-même. La base de données porte les fixtures et les migrations de la branche : deux worktrees sur deux branches n'ont pas le même schéma, et faire tourner une migration de l'un casserait l'autre. Le conteneur php porte le code, l'image, les ports Xdebug. Le service docs sert une documentation qui vit dans le worktree. Ces trois-là ne peuvent pas être partagés : les mutualiser reviendrait à ne plus avoir qu'un seul worktree, avec plus d'étapes.
De l'autre, ceux qui sont des infrastructures fongibles. Redis stocke un cache et des sessions. RabbitMQ transporte des messages. Typesense indexe des articles. Gotenberg convertit des documents, sans état du tout. Mailpit reçoit des e-mails de test. Aucun de ces services ne porte quoi que ce soit qu'on ne puisse recalculer, et surtout : chacun sait déjà cloisonner ce qu'on lui confie.
C'est ce second point qui rend la mutualisation possible. Sans lui, elle serait juste dangereuse.
L'isolation est logique, pas structurelle¶
Les cinq backing services mutualisés vivent dans un projet Compose unique, kirexo-shared, partagé par tous les worktrees. Chaque worktree y écrit dans son propre compartiment, désigné par une variable dérivée de WT :
| Service | Mécanisme d'isolation | Variable |
|---|---|---|
| RabbitMQ | vhost dédié — espace de noms complet, avec ses queues, ses exchanges et ses permissions | RABBITMQ_VHOST=ticket-185 |
| Redis | index de base dédié dans l'instance (1…15, 0 restant au dépôt principal) |
REDIS_DB_INDEX=1 |
| Typesense | préfixe de collection | TYPESENSE_COLLECTION_PREFIX=ticket-185_ |
| Mailpit | pas d'isolation — boîte volontairement commune, avec un expéditeur préfixé | MAIL_FROM=[ticket-185] Kirexo <…> |
| Gotenberg | sans état : rien à isoler | — |
Ce sont des mécanismes que ces services implémentent nativement, pas des conventions posées par-dessus. Un worktree qui publierait dans son vhost RabbitMQ ne touche pas les queues du voisin, de la même façon qu'un SELECT dans une base ne voit pas les tables d'une autre.
Un vhost ne s'auto-crée pas
C'est la contrepartie de ce choix : castor wt:up doit créer et autoriser le vhost RabbitMQ du worktree, sinon le worker Messenger part en ACCESS_REFUSED au premier message. Le symptôme n'est pas une erreur visible — ce sont des e-mails qui ne partent plus et des articles publiés qui n'atteignent plus leur site, pendant que le worker tourne. L'appel est idempotent et non bloquant (un vhost existant ou un broker pas encore prêt ne doit pas faire échouer un wt:up par ailleurs correct) ; sa contrepartie est d'être observé ailleurs, par la ligne du rapport de réconciliation et par une vérification rabbitmqctl list_vhosts.
Mailpit est le cas assumé sans isolation : une boîte unique pour N worktrees est plus pratique que N boîtes qu'il faut savoir choisir. Le préfixe [ticket-185] dans l'expéditeur suffit à retrouver la provenance d'un message.
Le plafond : 17 conteneurs pour 3 worktrees¶
En profil light, un worktree n'instancie que trois conteneurs : php, database, docs. S'y ajoutent, une fois pour le poste, les sept services de kirexo-shared (egress-proxy, redis, rabbitmq, typesense, gotenberg, mailer, autoheal) et le caddy-proxy du projet kirexo-proxy.
Ce que ce chiffre dit vraiment, c'est que le coût marginal d'un worktree supplémentaire est de trois conteneurs, pas de huit. C'est ce qui rend tenable d'en garder deux ou trois ouverts en permanence — et c'est bien la capacité recherchée, pas l'économie de mémoire en soi.
Deux conteneurs n'apparaissent dans aucun profil de worktree parce qu'ils ne sont pas des services de stack : caddy-proxy est le point d'entrée unique de tout l'environnement de développement, et autoheal sélectionne ses cibles par label sur tout le démon, sans filtre de projet Compose. Une instance d'autoheal par worktree veillerait à N sur les mêmes conteneurs, et à zéro sur le proxy mutualisé quand aucun worktree n'est démarré.
Ce que rend le profil full¶
castor wt:up 185 --profile=full réinstancie localement les cinq backing services. Le mécanisme n'est pas un empilement de fichiers Compose différents — les mêmes fichiers sont chargés dans les deux cas — mais la valeur de COMPOSE_PROFILES, qui active les services portant profiles: ["full"].
Ce profil existe pour trois usages qui ne se satisfont pas d'une isolation logique :
- reproduire un bug lié à l'infrastructure elle-même — une version de Redis, un comportement de RabbitMQ, un paramétrage Typesense : il faut alors pouvoir tordre le service sans casser les autres worktrees ;
- travailler sur la configuration d'un de ces services — modifier
compose.yamlou les variables d'un backing service demande de le voir démarrer dans son propre projet ; - isoler une campagne destructrice — purger un index ou une queue en profil
lighttoucherait le compartiment du worktree, mais unFLUSHALLou unrabbitmqctlmal ciblé, lui, ne connaît pas les compartiments.
Le coût est exactement l'inverse du gain de light : cinq conteneurs de plus par worktree, soit huit au lieu de trois. C'est pourquoi full est une exception explicite et non le défaut.
Le profil est mémorisé dans .env.worktree et réutilisé si l'option est omise. Sans cette mémorisation, un second wt:up ferait silencieusement retomber une stack full en light, et le dev chercherait longtemps pourquoi ses conteneurs ont disparu.
egress-proxy, autoheal et caddy-proxy ne repassent jamais en dédié, même en full : le proxy sortant applique une politique de sortie commune à tout le poste, et la dupliquer en dupliquerait les trous.
Ce que la mutualisation coûte au confinement¶
Partager des services a une conséquence directe sur l'isolation entre worktrees, et elle est assumée noir sur blanc dans le contrat de confinement.
L'invariant C10 porte le cloisonnement inter-worktrees : le conteneur d'un worktree ne doit pas atteindre l'application d'un worktree voisin. Il est tenu par une règle DOCKER-USER posée côté hôte sur le bridge du proxy. Mais depuis la mise en place des services mutualisés, les conteneurs php de deux worktrees partagent le réseau kirexo-services : ils sont donc mutuellement joignables au niveau IP. L'isolation qui subsiste entre eux est celle décrite plus haut — vhost, index, préfixe — c'est-à-dire logique et non structurelle.
Cette exception est la raison pour laquelle C10 est classé advisory et jamais blocking : la garantie est réelle mais hôte-only et volatile, le conteneur peut l'observer sans pouvoir la poser. Le risque résiduel est borné et connu : un agent peut atteindre l'application HTTP d'un worktree voisin, mais pas son système de fichiers (invariant C8, porté par les binds) et pas Internet (le réseau reste internal).
Le contrat exécutable — la liste des invariants, leurs sondes, leurs profils et leurs sévérités — vit dans .claude/skills/_shared/confinement.md, source de vérité unique. Le raisonnement complet sur la sévérité de C10 est dans Modèle de menace et contrat de confinement.
Un singleton est parenté sur le répertoire qui l'a créé¶
Le coût précédent était connu d'avance. Celui-ci ne l'était pas, et il tient en une propriété de Compose : les bind mounts d'un conteneur sont figés en chemins absolus au moment où il est créé. ./infra/egress n'est pas réévalué à chaque démarrage — il est résolu une fois, contre le répertoire d'où la commande a été lancée, et le daemon conserve ce chemin tel quel pour toute la vie du conteneur.
Sur un projet dédié au worktree, cela ne dit rien de neuf : le conteneur et le répertoire naissent et meurent ensemble. Sur un projet singleton, en revanche, cela crée un lien que rien n'affiche. kirexo-shared et kirexo-proxy sont créés une fois, par la première cible qui les démarre — wt:up depuis un worktree, mais aussi bien docker:up, docs:build ou image:refresh depuis le dépôt principal. Le répertoire d'où cette commande-là est partie devient le fondateur, et c'est en pratique un worktree, puisque c'est de là qu'on travaille. Six mois plus tard, le proxy sortant qui dessert cinq worktrees monte toujours sa configuration depuis le répertoire du premier ticket venu.
Détruire ce worktree-là laisse des conteneurs pointant sur un chemin disparu. Docker n'échoue pas pour autant : au redémarrage suivant, il recrée les chemins manquants en dossiers vides root-owned, et le service meurt sur un fichier introuvable.
Le 2026-09-17, c'est exactement ce qui s'est produit : le worktree fondateur détruit, restart: unless-stopped a relancé egress-proxy 1029 fois, pendant près de dix-sept heures, sans que rien ne casse ce cycle. Le réseau kirexo-egress étant internal: true, il n'existe aucune route sortante sans ce proxy : plus de composer, plus de npm, plus aucune session Claude Code — dans aucun worktree, pas seulement celui qu'on avait détruit. Le symptôme perçu, « impossible de se connecter à l'API », ne désigne rien de ce qui s'était réellement passé, et c'est la signature de tout ce qui touche à une ressource mutualisée : la panne se déclare chez le voisin.
Le cas le plus dangereux est celui qui ne se voyait pas¶
Le Caddy hôte portait le même défaut, en sommeil. Son bind est ./Caddyfile : un bind de fichier, donc d'inode. Un inode survit à la disparition de son entrée de répertoire tant qu'un processus le tient ouvert — le conteneur tournait donc encore, healthy, servant une configuration lue dans un fichier que le système de fichiers ne connaissait plus. La panne n'attendait qu'un docker restart ou un reboot pour se déclarer, sur le seul point d'entrée web de tout l'environnement de développement.
C'est la même leçon que celle du montage :ro de l'allowlist, prise par l'autre bout : un bind de fichier ne suit pas le fichier, il suit l'inode. Là-bas, cela faisait lire un contenu périmé sans le dire ; ici, cela fait survivre un conteneur condamné sans le dire. Dans les deux cas, l'état affiché est vert et l'information manquante est la même.
Pourquoi réparer, et non refuser¶
Un refus était possible — « ce worktree est le fondateur d'un singleton, détruisez-le depuis ailleurs ». Il a été écarté : le fondateur n'est pas un choix, c'est un accident d'ordonnancement, et rien dans l'interface n'en informe l'utilisateur au moment où il crée son worktree. Faire payer à la destruction une décision prise six mois plus tôt par un wt:up revient à transformer un nettoyage de routine en énigme.
castor wt:destroy re-parente donc les singletons sur le dépôt principal — le seul répertoire dont on sait qu'il survivra, puisqu'il porte le worktree et ne peut donc pas être ce worktree. Deux contraintes encadrent ce geste.
Il a lieu avant git worktree remove, jamais après. Après, le répertoire a disparu ; les dossiers vides que Docker y recrée appartiennent à root, et les retirer demanderait un sudo qu'aucune cible Castor ne joue. Réparer d'abord, supprimer ensuite : l'ordre n'est pas une préférence, c'est ce qui sépare une commande idempotente d'un nettoyage manuel privilégié.
Le signal qui décide n'est pas celui qu'on croit. Compose pose le label com.docker.compose.project.working_dir sur tous les conteneurs d'un projet, pas seulement sur ceux qui portent un bind. Quand la stack mutualisée a été démarrée entière depuis un worktree — le cas nominal — ce label vaut pour Redis, RabbitMQ, Typesense, Gotenberg et Mailpit autant que pour le proxy sortant. Recréer sur ce signal reviendrait à couper les backing services de tous les autres worktrees pour réparer celui qu'on détruit : le remède aurait alors la portée exacte de la panne qu'il prétend éviter.
La décision est donc prise sur le seul signal qui annonce une panne certaine — un bind mount dont la source est dans le worktree. Les autres conteneurs sont signalés et laissés en marche : leur label pointe un répertoire disparu, ce qui gêne un docker compose lancé sans -f, et rien d'autre. Un service qui tourne avec une étiquette périmée vaut mieux qu'un service correctement étiqueté que l'on vient d'éteindre pour trois autres branches.
La contrepartie est assumée et annoncée à l'écran : recréer egress-proxy, c'est détruire et reconstruire son conteneur, donc couper les tunnels CONNECT ouverts — un téléchargement en cours dans un autre worktree échoue et doit être relancé — et lui donner au passage une nouvelle adresse sur kirexo-egress. La coupure dure le temps du up --wait ; elle est sans commune mesure avec la panne qu'elle évite, qui ne s'arrête pas toute seule.
Enfin, la réparation vise toujours un service, jamais un projet : up -d --force-recreate sur le service nommé, jamais un down -v qui emporterait caddy_proxy_data et, avec lui, la CA racine locale émise pour dix ans. Le détail de la procédure, des sorties affichées et des codes de retour est dans castor wt:destroy — Le re-parentage des projets singletons.
Réparer à la destruction, c'est encore arriver après¶
Le re-parentage ci-dessus traite le symptôme au seul moment où on le voit venir. Il laisse deux fenêtres ouvertes : un répertoire de worktree supprimé à la main ne passe par aucune cible, et surtout, entre la création du singleton et la destruction du worktree fondateur, l'environnement entier dépend d'un répertoire que personne n'a choisi et que rien n'affiche.
La décision D13 ferme la question par l'autre bout : les deux projets singletons ne sont plus créés que depuis le dépôt principal, quel que soit le checkout d'où part la commande. Le dépôt principal porte les worktrees ; il ne peut donc être aucun d'entre eux, et castor wt:destroy ne peut pas le détruire. Le fondateur cesse d'être un accident d'ordonnancement pour devenir une propriété du dispositif — la classe de panne n'est plus rattrapée, elle n'existe plus.
L'ancrage est porté par un helper unique de castor.php, kirexo_main_repo(), et son pendant kirexo_main_repo_context() qui en fait un répertoire de travail. Il sert à trois endroits :
shared_stack_up()— le préalable commun aux cibles qui démarrent une stack — exécute depuis le dépôt principal toutes ses étapes qui touchent au dépôt, et passe audocker compose updekirexo-sharedun chemin absolu verscompose.shared.yaml;proxy_compose_args()fait de même pourinfra/proxy/compose.proxy.yaml, ce qui ancre toutes les ciblesproxy:*par le seul chemin, sans qu'elles aient à s'en soucier ;- les cibles
firewall:*(castor/firewall.php) lisent et écrivent les whitelists du dépôt principal, et y rendent l'allowlist.
C'est le premier -f d'un docker compose up qui fixe le répertoire de projet, et donc la résolution des binds : un chemin absolu suffit à décider du parentage, là où un répertoire de travail se transmet mal d'un appel à l'autre.
Le parentage n'est pas le seul mécanisme en jeu
Les scripts d'infra/ résolvent leurs fichiers depuis leur propre emplacement ($BASH_SOURCE), jamais depuis le répertoire d'appel. Pour eux, ce que le répertoire de travail décide, c'est quel exemplaire du script s'exécute quand on le désigne par un chemin relatif. C'est exactement ce qui faisait diverger l'allowlist : render-allowlist.sh lancé depuis un worktree était celui du worktree, et il rendait l'allowlist du worktree, pendant que le proxy appliquait celle de son fondateur. Confondre les deux mécanismes conduit à croire cassé un appel qui ne l'est pas, ou l'inverse.
La contrepartie est assumée : la whitelist locale devient commune à tous les worktrees. C'était déjà la réalité de fait — un seul proxy, une seule allowlist — elle devient simplement explicite, et castor firewall:whitelist-add écrit désormais là où le proxy lit. Le détail est dans Une seule whitelist, celle du dépôt principal.
Ce que cela ne couvre pas¶
L'ancrage n'existe que sur l'hôte. Depuis un conteneur, kirexo_main_repo() rend /app sans même chercher : le chemin du dépôt principal est un chemin de l'hôte, et ce dépôt n'est pas monté dans la cellule d'un worktree. Rien de ce qui touche au parentage des conteneurs ne se joue de toute façon là — C2 interdit le socket Docker — mais les cibles de lecture y passent, et leur affichage peut alors ne pas décrire ce que le proxy applique. Voir Une seule whitelist, celle du dépôt principal.
Les conteneurs créés avant cette décision gardent leur parentage. Compose le fige à la création : seule une recréation le change. Le premier castor docker:up joué après la mise à jour du dépôt recrée donc les deux singletons — cf. l'encadré d'exploitation dans Préalable commun aux cibles qui démarrent une stack.
Le re-parentage de wt:destroy reste en place, et ce n'est pas un doublon : il couvre précisément ces conteneurs-là, et tout ce qu'un docker compose up lancé à la main depuis un worktree pourrait encore créer. Un rm -rf du répertoire d'un worktree ne passe, lui, par aucune cible : sur un singleton hérité, la panne se déclarera au redémarrage suivant, éventuellement des semaines plus tard. Le geste de reprise est le même que celui de la commande — recréer le service depuis le dépôt principal — et il est décrit dans Diagnostiquer un blocage réseau sortant.
Alternatives écartées¶
| Option | Pourquoi elle a été écartée |
|---|---|
| Une stack complète par worktree (l'état antérieur) | 24 conteneurs pour 3 worktrees. En pratique, on ne lance qu'un worktree à la fois — la capacité recherchée disparaît. |
| Tout mutualiser, y compris PostgreSQL | Le schéma de la base est le travail de la branche. Une migration jouée dans un worktree casserait les autres, sans le moindre signal. |
| Mutualiser par base de données PostgreSQL au sein d'une instance unique | Techniquement possible, mais les migrations, les fixtures et les purges de castor test:e2e visent une base entière : le cloisonnement serait à la merci d'une commande mal ciblée, pour un gain d'un conteneur par worktree. |
| N instances de Mailpit, une par worktree | Un conteneur de plus par worktree pour un service dont l'intérêt est justement de tout voir au même endroit. Le préfixe d'expéditeur résout le besoin réel. |
Un autoheal par worktree |
Il sélectionne ses cibles par label sur tout le démon : N instances veillent toutes sur les mêmes conteneurs, et aucune ne couvre le proxy mutualisé quand tous les worktrees sont arrêtés. |
| Refuser la destruction d'un worktree fondateur de singleton | Être fondateur est un accident d'ordonnancement, jamais un choix : le refus ferait payer à un nettoyage de routine une décision invisible prise des mois plus tôt. |
Recréer les singletons sur le label working_dir plutôt que sur les binds |
Compose pose ce label sur tous les conteneurs du projet : le remède couperait Redis, RabbitMQ et Typesense pour tous les autres worktrees — exactement la portée de la panne qu'il évite. |
S'en tenir au re-parentage de wt:destroy, sans ancrer la création |
Réparer à la destruction arrive toujours après, et ne couvre pas un répertoire supprimé à la main. Entre-temps, tout l'environnement dépend d'un répertoire que personne n'a choisi. |
| Garder une whitelist locale par worktree, appliquée pour ce worktree | Il n'y a qu'un proxy, donc qu'une politique Squid : « par worktree » n'aurait pas de sens côté application. Ce que l'on gardait, c'était un fichier lu par personne — et un tableau de firewall:status qui affichait une allowlist sans rapport avec la réalité. |
Pour aller plus loin¶
- L'inventaire des services par profil, le décompte et les variables d'isolation : Worktrees et environnement de développement.
- Le geste de création, de bascule de profil et de destruction : Créer et détruire un worktree.
- Pourquoi le proxy sortant reste unique pour tout le poste : Pourquoi la sortie réseau passe par un proxy à allowlist.
- Comment les trois URLs d'un worktree sont routées, et ce que cloisonne la règle
DOCKER-USER: Routage des worktrees : DNS, TLS et cloisonnement réseau.