Routage des worktrees : DNS, TLS et cloisonnement réseau¶
Cette page explique pourquoi l'environnement de développement de Kirexo est servi par un unique proxy Caddy côté hôte, pourquoi les noms prennent la forme <service>.<worktree>.localhost et pas l'inverse, pourquoi tout nom servi compte au moins deux labels sous .localhost, et ce que garantit — ou non — le cloisonnement entre les stacks voisines.
Pour les gestes : Installer la CA du proxy de développement et la référence des cibles Castor proxy:*. Pour la sortie réseau (le sens inverse, du conteneur vers Internet), voir Pourquoi la sortie réseau passe par un proxy à allowlist : ce sont deux proxys distincts, qui ne se rencontrent jamais.
Onze ports publiés pour une seule loopback¶
Le dispositif d'origine donnait à chaque service de la stack sa propre publication de port sur l'hôte : 443 pour l'application, 8000 pour la documentation, 8025 pour Mailpit, plus PostgreSQL, RabbitMQ, Typesense et Gotenberg — onze publications réparties sur sept blocs ports: de compose.override.yaml.
Tant qu'une seule stack tourne, le dispositif fonctionne. Dès la deuxième, il tombe : deux stacks se disputent 127.0.0.1:443, et la seconde échoue au up sur un address already in use. La parade évidente — décaler les ports de chaque worktree — déplace le problème dans la tête du développeur : il faut retenir que le ticket 185 est sur :8443 et le 212 sur :8444, et le multi-tenant de Kirexo, qui aiguille sur le Host, ne voit plus la différence entre les deux.
Tous ces blocs ports: ont donc disparu. Le seul publisher de tout l'environnement de développement est le conteneur caddy-proxy (infra/proxy/compose.proxy.yaml), sur 127.0.0.1:80 et 127.0.0.1:443 — un singleton, hors du projet Compose de chaque worktree, qui route par nom d'hôte. Le nom devient le discriminant à la place du port, et il n'y a plus rien à retenir.
Corollaire assumé : l'accès direct à PostgreSQL, RabbitMQ ou Typesense depuis l'hôte n'existe plus. Un client SQL ne se connecte plus sur localhost:5432 ; on passe par docker compose exec. Ce n'est pas un effet de bord à corriger en réintroduisant un ports:, c'est la propriété recherchée : la surface exposée sur la loopback de la machine se réduit à un port HTTP et un port HTTPS.
Pourquoi le nom du service passe avant celui du worktree¶
Dans une adresse de bloc de site Caddy, le * ne remplace qu'un seul label, et ce label doit être le plus à gauche. *.localhost matche notes.localhost, mais pas mailpit.ticket-185.localhost, qui compte deux labels sous .localhost ; et mailpit.*.localhost ne s'écrit pas.
Cette contrainte porte sur le routage. Elle a un pendant côté certificats, qui décide non plus de l'ordre des labels mais de leur nombre — voir Pourquoi tout nom servi a au moins deux labels. Elle suffit en tout cas à trancher entre les deux nommages possibles, parce qu'elle décide de ce qui tient dans un seul fichier de conf.
| Nommage | Suffixe commun aux noms d'un worktree | Conséquence |
|---|---|---|
<service>.<worktree>.localhost (retenu) |
.ticket-185.localhost — un par worktree |
Tous les noms d'un worktree partagent un suffixe, donc un fichier, écrit par wt:up et retiré par wt:destroy. L'unité de nommage coïncide avec l'unité de cycle de vie ; ajouter un service ajoute un bloc dans le gabarit, rien de plus. |
<worktree>.<service>.localhost (écarté) |
.mailpit.localhost, .docs.localhost, … — un par service |
L'unité serait le service : la conf d'un worktree se retrouverait éparpillée sur autant de fichiers et de suffixes qu'il y a de services, et ajouter un service créerait un suffixe global de plus. |
Autrement dit, on a choisi le nommage qui fait coïncider l'unité de configuration avec l'unité de vie. Créer un worktree ajoute un fichier dans ~/.kirexo/proxy/sites/ ; le détruire le retire. Rien d'autre ne bouge.
« Un seul certificat par worktree » est une approximation
Caddy émet une feuille par nom exact déclaré — trois par worktree, d'après infra/proxy/site.caddy.tpl. Leur nombre est sans objet : l'émission est locale, instantanée, et le renouvellement automatique. Ce que le nommage achète réellement, c'est une seule CA à installer, un seul suffixe de routage et un seul fichier de conf par worktree.
Une conséquence à connaître : mailpit.ticket-185.localhost compte deux labels sous .localhost, donc le *.localhost du repli ne l'atteint pas. Sans bloc de site dédié, aucun bloc ne le servirait — il n'y a pas de catch-all dans infra/proxy/Caddyfile. D'où la forme retenue dans infra/proxy/site.caddy.tpl : un nom par worktree, mais un upstream mutualisé (mailpit-shared). Il n'y a qu'une boîte, quelle que soit la porte par laquelle on entre.
Le repli a longtemps porté en plus une URL canonique mailpit.localhost, censée survivre à la destruction du dernier worktree. Elle a disparu : un seul label la condamnait au certificat wildcard décrit plus bas, et elle était de toute façon redondante avec mailpit.main.localhost, servi par la conf du dépôt principal — qui, elle, ne se détruit jamais.
Une CA locale, installée une seule fois¶
Le proxy déclare tls internal sur chacun de ses blocs de site. Caddy signe alors chaque nom avec sa CA locale, sans ACME et sans réseau : aucune démarche d'émission n'est nécessaire au moment de créer un worktree, seulement l'ajout d'un bloc et un rechargement de configuration.
Cette CA a trois durées de vie superposées, qui sont les défauts de Caddy :
| Élément | Validité | Qui le renouvelle |
|---|---|---|
| Feuille (le certificat du nom servi) | 12 h | Le proxy, automatiquement, tant qu'il tourne |
| Intermédiaire | 7 j | Idem |
| Racine | 10 ans | Personne — elle est créée une fois |
C'est le troisième étage qui fait tout l'intérêt du dispositif : seule la racine est installée dans le trust store de l'hôte. castor cert:trust l'extrait du volume nommé caddy_proxy_data et l'installe une bonne fois pour toutes. Elle couvre donc tous les worktrees, présents et futurs : un worktree créé dans six mois est servi sans avertissement, sans nouveau geste.
Deux propriétés en découlent, et elles ne sont pas anecdotiques :
- Un proxy éteint une semaine ne casse rien. Feuille et intermédiaire sont périmés, mais ils sont ré-émis instantanément par la même racine au redémarrage. C'est aussi pourquoi
castor proxy:downn'utilise jamais-v: détruire le volume détruirait la racine, et il faudrait rejouercert:trustsur tous les postes. - Le trust store du conteneur proxy, lui, ne sert à rien.
infra/proxy/Caddyfileposeskip_install_trust: aucun client TLS ne vit dans ce conteneur, et l'installation ne produirait que des avertissements Java/Firefox à chaque démarrage. C'est le même raisonnement que pourfrankenphp/Caddyfile, décrit dans TLS interne du conteneur :skip_install_trust.
FrankenPHP continue d'émettre son propre certificat interne pour localhost et *.localhost — les tests E2E, qui tournent dans le conteneur et visent https://localhost, en dépendent. Mais plus personne n'a besoin de lui faire confiance : faute de port publié, ce FrankenPHP n'est pas joignable directement depuis l'hôte. La seule CA qui compte pour le navigateur du développeur est celle du proxy.
Pourquoi tout nom servi a au moins deux labels¶
Une CA installée ne suffit pas : encore faut-il que le certificat présenté vaille pour le nom demandé. C'est cette contrainte-là — et non un souci de rangement — qui a fixé la forme de tous les noms de l'environnement de développement : app., docs., mailpit., chacun devant l'identifiant du worktree.
Tous les blocs du proxy déclarent tls internal, les blocs de nom exact comme le bloc de repli *.localhost (infra/proxy/site.caddy.tpl, infra/proxy/fallback.caddy.tpl). Caddy provisionne alors chaque adresse déclarée au chargement de la configuration, avant toute visite. Pour le repli, l'adresse déclarée est le joker lui-même : le certificat émis porte le nom *.localhost. Or un wildcard qui ne couvre qu'un seul label sous un domaine de premier niveau n'est accepté ni par OpenSSL ni par les navigateurs — Caddy le dit d'ailleurs lui-même au chargement, most clients do not trust second-level wildcard certificates (*.tld).
C'est ce certificat-là qui était servi à tout nom d'un seul label, y compris quand ce nom avait son propre bloc de site. Mesuré sur le SAN du certificat réellement présenté, avant le renommage :
ticket-215.localhost → X509v3 Subject Alternative Name: DNS:*.localhost
docs.ticket-215.localhost → X509v3 Subject Alternative Name: DNS:docs.ticket-215.localhost
La dissymétrie ressemblait à un défaut d'installation de la CA ; elle en était l'exact inverse. docs.<worktree>.localhost et mailpit.<worktree>.localhost passaient sans un mot parce que deux labels sous .localhost sont hors de portée d'un wildcard à un niveau : ces noms forçaient une feuille dédiée. Étaient touchés, symétriquement, les noms d'un seul label — la racine de chaque worktree en tête, mais aussi local.localhost, mailpit.localhost et le domaine du site de démonstration.
Le correctif ne touche donc ni la directive tls, ni le magasin de certificats, ni la CA : il généralise la forme qui marchait déjà. Quatre renommages :
| Avant | Après | Ce que ça change |
|---|---|---|
<worktree>.localhost |
app.<worktree>.localhost |
L'application entre dans le cas à deux labels, comme docs. et mailpit. |
demo.localhost (site de démonstration des fixtures) |
app.demo.localhost |
Trois labels : le joker ne le couvre pas, un bloc explicite du repli le sert |
dépôt principal = worktree local |
dépôt principal = worktree main |
app.main.localhost, docs.main.localhost, mailpit.main.localhost |
bloc mailpit.localhost du repli |
(supprimé) | Redondant avec mailpit.main.localhost, permanent et valide |
Le nom main a été choisi parce que l'arbre de travail principal reste sur la branche main, les worktrees portant les branches de travail : le suffixe dit ce qu'on trouve derrière.
Conséquence immédiate, et c'est tout l'objet du changement : plus aucune URL de développement n'avertit. Plus de -k à passer à curl, plus d'exception de sécurité à accepter par worktree — la seule installation qui reste est celle de la racine, une fois par poste.
Le préfixe n'est pas cosmétique
C'est la longueur du nom qui rend le certificat valide. Un service ajouté plus tard sur un nom d'un seul label sous .localhost fonctionnerait — et avertirait, ramenant exactement le défaut qu'on vient de fermer. Les deux gabarits (infra/proxy/site.caddy.tpl, infra/proxy/fallback.caddy.tpl) le rappellent en tête de fichier, et la liste des noms de worktree réservés s'est étendue à app pour qu'aucun worktree ne vienne produire une adresse ambiguë ou dupliquée.
Ce que le joker sert encore¶
Le bloc *.localhost n'a pas disparu : il reste le seul moyen de servir un domaine de site que personne n'a écrit dans une conf, puisqu'ils sont résolus dynamiquement en base (cf. Multi-tenant : résolution d'un domaine vers un site). Ce qu'il sert a simplement changé de nature : ce ne sont plus que les domaines mappés à la main sur un nom d'un seul label. Ceux-là fonctionnent, et avertissent — le comportement décrit plus haut. Un domaine de site à deux labels ou plus obtient, lui, une feuille valide, et c'est le cas du site de démonstration depuis qu'il s'appelle app.demo.localhost.
Le régime d'émission n'est pas le levier : ce que on_demand a démontré¶
Cette trace est conservée pour une raison précise : l'idée qui suit est naturelle, la documentation de Caddy l'autorise, et sans le contre-résultat mesuré un futur lot la re-dériverait.
L'idée était de supprimer l'émission anticipée du wildcard. tls internal accepte un second régime, tls internal { on_demand }, qui n'émet plus au chargement mais à la poignée de main, pour le nom réellement présenté — ce qui correspond au besoin d'un bloc dont les noms ne sont pas connus à l'avance. La configuration est acceptée par caddy validate. Elle a été livrée au lot 26, puis retirée au lot 27 : mesurée sur un proxy réel, c'est une régression, et plus grave que le défaut qu'elle visait.
openssl s_client -connect ticket-215.localhost:443 …
tlsv1 alert internal error · no peer certificate available
ls /data/caddy/certificates/local/
PRÉSENTS : localhost · docs.<wt>.localhost · mailpit.<wt>.localhost (deux labels)
ABSENTS : local.localhost · ticket-215.localhost · mailpit.localhost (un label)
Aucun nom d'un seul label sous .localhost n'obtenait plus de certificat — pas même local.localhost, qui avait son bloc dédié dans 01-main.caddy, ni mailpit.localhost, qui avait le sien dans le repli. localhost nu subsistait : un wildcard ne couvre pas le domaine qu'il suffixe. Ce que les deux essais établissent :
Bloc *.localhost |
Noms à un label | Noms à deux labels |
|---|---|---|
tls internal (en place) |
Wildcard servi → refus d'OpenSSL, avertissement du navigateur, mais l'accès reste possible | Feuille dédiée, aucun problème |
tls internal { on_demand } (retiré) |
Aucun certificat → poignée de main impossible | Feuille dédiée, aucun problème |
La colonne de droite est la même dans les deux cas. C'est elle qui a fini par donner la solution : puisque le régime d'émission ne déplace que la colonne de gauche — d'un avertissement franchissable à un handshake impossible — le levier n'était pas là. Il était dans le nom.
Ce qui est mesuré, et ce qui n'est qu'une hypothèse
Mesuré : le refus d'OpenSSL (curl rend verify=1), l'avertissement observé dans un navigateur, la liste des feuilles présentes et absentes dans le magasin, l'échec de la poignée de main sur le nom sondé (ticket-215.localhost) sous on_demand, et le fait qu'un nom à deux labels obtient une feuille dédiée là où un nom à un label reçoit le wildcard.
Hypothèse, cohérente avec ces observations mais jamais testée pour elle-même : Caddy ne créerait pas de feuille pour un nom qu'un certificat déjà en magasin couvre, et rattacherait donc les noms à un label à la policy TLS du bloc joker plutôt qu'à celle de leur propre bloc de site. C'est l'explication la plus simple des deux régimes, ce n'est pas un fait établi. Le correctif retenu ne s'appuie pas dessus : il évite le recouvrement au lieu d'en expliquer le traitement, ce qui le rend indépendant de la validité de l'hypothèse.
Un changement du repli atteint bien les postes existants
C'est la condition de livraison de tout ce qui précède, correctif comme retour en arrière : castor proxy:up régénère le fichier de repli à chaque appel — en préservant la désignation du worktree par défaut, qui porte le routage des domaines de site — puis recharge la configuration, sans condition. Il n'écrivait autrefois ce fichier que s'il était absent, et laissait le rechargement à l'utilisateur : une évolution du gabarit n'atteignait alors que les postes n'ayant jamais démarré le proxy, c'est-à-dire aucun de ceux qui subissent le problème qu'elle traite. Rien à réinstaller au passage : castor cert:trust est inchangé, le trust store n'a jamais été en cause.
Le renommage, lui, ne se limite pas au proxy : il touche les alias réseau des conteneurs du dépôt principal et le domaine du site de démonstration, tous deux hors de portée d'un rechargement de conf. La marche à suivre sur un poste déjà installé est dans Migrer un poste existant vers les URLs app..
Résoudre les noms de worktree sans configuration système¶
Le choix d'un suffixe en .localhost n'est pas cosmétique : c'est lui qui évite d'imposer une configuration système, hors dépôt, à refaire à chaque création de worktree et à nettoyer à chaque destruction.
| Client | Comportement | À configurer |
|---|---|---|
| Chromium / Chrome / Edge | Mappent nativement tout nom en .localhost sur la loopback |
Rien |
| Firefox | Idem | Rien |
Hôte Linux avec systemd-resolved |
Synthétise les enregistrements pour tout nom finissant en .localhost |
Rien |
Hôte Linux sans systemd-resolved |
getaddrinfo ne connaît que ce qui est dans /etc/hosts |
Une ligne dans /etc/hosts |
Le cas nominal ne demande donc rien : ni dnsmasq, ni IP de loopback dédiée, ni entrée /etc/hosts par worktree — c'est ce qui a écarté ces trois options.
Reste un cas, et un seul, où une configuration système demeure nécessaire : un hôte sans systemd-resolved, pour les clients en ligne de commande. Le navigateur y fonctionne parfaitement, mais curl https://app.ticket-185.localhost échoue en Could not resolve host. La dissymétrie est déroutante — elle ressemble à une panne du proxy alors qu'elle se joue avant lui — c'est pourquoi castor proxy:status sonde explicitement la résolution et imprime la ligne /etc/hosts à ajouter. Il ne la pose pas lui-même : écrire dans /etc/hosts est une action système, hors mandat de l'outillage du dépôt.
Deux réseaux internes, aucune route par défaut¶
Le proxy doit atteindre les conteneurs de toutes les stacks. Il faut donc un réseau partagé, kirexo-proxy, auquel php, docs et mailer de chaque worktree s'attachent en plus de leur réseau applicatif.
C'est le point où le dispositif pouvait tout casser en silence. Un réseau Docker non-internal fournit une route par défaut via sa passerelle NAT : attacher le conteneur php — celui qui exécute l'agent — à un second réseau non-internal lui rendrait un accès Internet complet, en contournant intégralement le proxy sortant à allowlist. Sans aucun message, sans aucun symptôme applicatif : tout continuerait de fonctionner, mieux même qu'avant.
D'où la ligne la plus importante de infra/proxy/proxy-net.sh : le réseau est créé avec --internal. Deux réseaux internal n'offrent aucune route par défaut ; le confinement est préservé. Le script refuse d'ailleurs de continuer si un réseau kirexo-proxy préexistant n'est pas internal, plutôt que de démarrer sur une hypothèse.
Le conteneur caddy-proxy, lui, est attaché à deux réseaux : kirexo-proxy (internal) et le réseau default de son propre projet Compose, non-internal, qui porte la publication des ports. Il est ainsi la seule machine à voir les deux mondes — exactement comme egress-proxy dans l'autre sens.
Ce que la règle DOCKER-USER garantit, et ce qu'elle ne garantit pas¶
Un réseau partagé met les stacks en présence les unes des autres. Or internal: true ferme l'extérieur, pas le voisinage : sur un bridge, l'attachement est bidirectionnel, et le conteneur php du worktree 185 peut par défaut ouvrir une connexion vers celui du worktree 212.
La formule « répond mais n'initie pas » n'est donc pas un comportement natif de Docker. Elle s'obtient par une règle explicite posée dans la chaîne DOCKER-USER de l'hôte : tout flux NEW entrant sur le bridge partagé dont la source n'est pas le proxy est jeté. Le trafic retour des connexions ouvertes par le proxy est en ESTABLISHED, n'est donc pas matché, et passe. Le proxy atteint toutes les stacks ; aucune stack n'atteint le proxy ni sa voisine.
enable_icc=false n'aurait pas convenu : il coupe tous les flux NEW intra-bridge, donc aussi proxy → application.
Trois limites, qui font partie du contrat plutôt que de le trahir :
- La règle est volatile. Elle disparaît au redémarrage de la machine ou à un flush du démon Docker.
infra/proxy/proxy-net.shla repose à chaque appel, et il est appelé parcastor proxy:upet par le préalable commun aux cibles qui démarrent une stack. - Elle est conditionnée à
sudo. Sanssudodisponible, le script n'échoue pas : il émet un avertissement et sort en0. Faire échouer chaquecastor docker:upd'un poste sans droits d'administration serait un remède pire que le mal. - Le mode dégradé est un mode supporté, et son risque résiduel est borné : un agent peut alors atteindre en HTTP l'application d'un worktree voisin. Il n'atteint ni son système de fichiers (porté par les binds), ni Internet (le réseau reste
internal).
C'est précisément parce que la garantie est hôte-only, volatile et conditionnelle que l'invariant de confinement C10 est classé advisory et jamais blocking : il s'affiche en ⚠ WARN sans jamais bloquer une session. Le raisonnement complet est dans Pourquoi C10 est advisory et non blocking. Le diagnostic qui fait autorité est côté hôte : castor proxy:status affiche la présence de la règle, et la valeur du sysctl net.bridge.bridge-nf-call-iptables sans lequel elle serait inopérante — le trafic intra-bridge ne traverserait pas DOCKER-USER, toujours sans le moindre signal.
Pourquoi la plage dynamique du réseau du proxy est bornée¶
La règle ci-dessus a une propriété qu'on oublie facilement en la lisant : elle ne désigne pas un conteneur, elle désigne une adresse. ! -s 172.31.1.2 -j DROP protège ce qui porte 172.31.1.2 au moment où le paquet passe, et rien d'autre. Le conteneur caddy-proxy demande bien cette adresse en statique dans infra/proxy/compose.proxy.yaml — mais une adresse demandée n'est pas une adresse obtenue.
Or, un réseau Docker créé sans --ip-range alloue les adresses dynamiques à partir du bas du subnet. Sur 172.31.1.0/24, la première disponible est donc .2 : exactement celle qui est réservée. Il suffit qu'un conteneur rejoigne le réseau avant le proxy — un kirexo-shared recréé pendant que le proxy était arrêté, par exemple — pour qu'il la rafle.
À partir de là, deux issues, et c'est la seconde qui compte. Ou bien Docker refuse d'attacher le Caddy et rend Address already in use, message qui ne nomme jamais l'occupant mais qui, au moins, fait du bruit. Ou bien le Caddy démarre sur une autre adresse : les URL répondent, le routage fonctionne, tout paraît normal — et la règle DOCKER-USER protège désormais le conteneur intrus en jetant le trafic du proxy. Le pare-feu reste syntaxiquement valide ; il vise simplement la mauvaise machine. Le cloisonnement n'est pas dégradé, il est inversé, et rien ne le signale.
C'est un défaut de sécurité, pas de disponibilité, et il illustre la ligne directrice du contrat de confinement : vérifier l'effet, jamais la configuration. Une conf Compose qui déclare ipv4_address: 172.31.1.2 ne prouve rien. La mesure se fait sur le réseau réel.
Trois dispositifs en découlent, et il en faut trois :
- La prévention — le réseau est créé avec
--ip-range 172.31.1.128/25(KIREXO_PROXY_IP_RANGE). L'allocation dynamique commence à.128, la moitié basse reste réservée par construction, et l'ordre de démarrage cesse d'avoir de l'importance. C'est le même geste que le plan d'adressage lui-même : rendre l'invariant vrai par la structure plutôt que par la discipline. - Le contrôle —
castor proxy:uprelit l'adresse réellement obtenue après leupet échoue si elle diffère, en nommant l'occupant. La prévention ne suffit pas seule : un--ip-rangene peut pas être ajouté à un réseau existant,docker network createne modifiant jamais un réseau en place. Les postes qui portent unkirexo-proxyd'avant restent donc exposés tant que ce réseau n'a pas été détruit et recréé — et le script se contente de l'avertir sans échouer, parce qu'unexit 1casserait chaquecastor docker:upde ces postes. - La remédiation —
castor proxy:migrate, qui exécute cette recréation. Elle n'existe pas par confort : le diagnostic a d'abord imprimé les cinq commandes à taper, dont une à rejouer dans chaque worktree. Personne ne les a tapées. L'avertissement a survécu deux jours, jusqu'à ce qu'un conteneur de la stack mutualisée rafle.2et bloquecastor wt:upen dur. Un remède qui demande cinq commandes dans N répertoires n'est pas un remède, c'est un rappel — et un diagnostic qui ne s'exécute pas est une dette, au même titre qu'une prévention qu'on n'applique qu'aux nouveaux postes.
Cette dernière est aussi la raison pour laquelle un réseau absent n'est pas traité comme un réseau conforme : c'est l'état exact que laisse une migration interrompue entre la suppression et la recréation. Y répondre « rien à migrer » déclarerait la situation saine au moment précis où plus rien ne tourne.
La marche à suivre côté opérateur — ce que la cible descend, ce qu'elle refuse de toucher, et ce que le diagnostic affiche — est dans castor proxy:migrate.
Un service sur deux réseaux rend deux adresses¶
Docker répond à une résolution de nom par toutes les adresses partagées entre le demandeur et la cible. Un service attaché à deux réseaux communs rend donc deux enregistrements A, et le client en choisit un.
C'est inoffensif jusqu'à ce qu'une des deux routes soit fermée. Avec la règle DOCKER-USER ci-dessus, l'adresse du réseau du proxy est précisément celle qui sera jetée : une connexion sur deux part dans le vide, en timeout. Le symptôme est un des pires qui soient — des e-mails « parfois » perdus, une sonde de documentation qui échoue une fois sur trois, et aucun message pour dire pourquoi.
D'où une règle d'alias, permanente : tout service joignable à la fois par le proxy et par l'application déclare deux alias distincts, chacun sur un seul réseau, et aucun consommateur ne vise le nom de service nu.
| Service | Alias applicatif (réseau de la stack) | Alias proxy (réseau kirexo-proxy) |
|---|---|---|
php |
(aucun — un seul consommateur, et il se parle à lui-même) | php-<worktree> |
docs |
docs-int |
docs-<worktree> |
mailer |
mailer-int |
mailpit-shared |
C'est ce qui explique deux valeurs qui, prises isolément, ressemblent à une coquetterie : MAILER_DSN=smtp://mailer-int:1025 dans .env, et l'URL http://docs-int:8000/ utilisée par la sonde « doc en ligne » du hook Stop comme par le message d'aide de castor docs:build. Les alias sont déclarés en forme mapping dans compose.override.yaml : la forme liste (networks: [a, b]) ne permet pas de déclarer d'alias, et la perdre ferait tomber tous les worktrees en 502 d'un coup.
Deux noms nus restent corrects et ne doivent pas être « corrigés » : MERCURE_URL, qui vise php depuis php lui-même (le noyau route par lo, le paquet ne traverse aucun bridge), et le conteneur jetable de castor monitor, lancé sur un seul réseau.
Pourquoi le proxy parle en clair au FrankenPHP¶
Le proxy ne parle pas HTTPS à l'application : il vise php-<worktree>:8080, en HTTP clair. Trois contraintes se croisent, et l'adresse sans nom d'hôte :8080 ajoutée à SERVER_NAME est la seule qui les satisfasse toutes les trois.
- L'en-tête
Hostdoit arriver intact. C'est lui qui porte le multi-tenant (Host→Site) et les URLs générées. Or, depuis Caddy 2.11,reverse_proxyvers un upstreamhttps://réécritHostavec l'adresse de l'upstream : Symfony recevraitHost: php-ticket-185et le rejetterait en400. Contournable, au prix de trois réglages fragiles, pour un chiffrement sans valeur sur un bridgeinternal. - Pas de boucle de redirection. Le port
443de FrankenPHP porte la redirection automatique HTTP→HTTPS pourlocalhostet*.localhost: y proxifierapp.ticket-185.localhostrenverrait un308vers… le proxy. Une adresse Caddy sans nom d'hôte n'est pas éligible à l'HTTPS automatique, donc aucune redirection n'y est installée. - Les tests E2E ne bougent pas. Ils visent
https://localhostdans le conteneur ;localhost, *.localhostrestent donc déclarés dansSERVER_NAME, à côté de:8080.
Symfony continue de générer des URLs en https:// : Caddy pose X-Forwarded-Proto: https, et la plage du réseau du proxy est déjà couverte par TRUSTED_PROXIES.
Le dépôt principal est un worktree nommé main¶
Le dépôt principal n'est pas un worktree : il n'aura donc jamais de castor wt:up, et donc jamais de fichier de site écrit par cette cible. Comme les ports publiés ont disparu, il serait devenu injoignable — durablement, et non le temps d'une transition.
Il est donc traité comme un worktree de nom figé, main, servi par un fichier dédié (01-main.caddy) que castor proxy:up écrit systématiquement. Le nom vient de la branche : l'arbre de travail principal reste sur main, les worktrees portant les branches de travail. Un développeur qui n'utilise pas les worktrees lance castor docker:up comme avant et trouve son application sur https://app.main.localhost, sa documentation sur https://docs.main.localhost, sa boîte mail sur https://mailpit.main.localhost — et https://localhost y redirige en 308.
Le nom du worktree principal et les alias Compose bougent ensemble
Les alias réseau du dépôt principal sont rendus par php-${WT:-main} et docs-${WT:-main} (compose.override.yaml, compose.full.yaml) : ils valent php-main et docs-main quand aucun .env.worktree ne définit WT. C'est exactement ce que la conf du proxy vise, l'un pour l'application et l'autre pour la documentation. Changer KIREXO_PROXY_MAIN_WT sans changer les alias — ou l'inverse — fait router le proxy vers un alias inexistant : 502 avec un TLS parfaitement valide devant, sur tout le dépôt principal si c'est php- qui a divergé, sur la seule docs.main.localhost si c'est docs-. La même valeur vit aussi dans la sonde de confinement C10 (infra/confinement/check.lib.sh, infra/confinement/check.sh), qui interroge les alias des worktrees pairs, et dans le repli du namespace de session des hooks (.claude/hooks/lib/session-dir.sh). Elle vit enfin sous une autre forme — le nom d'hôte applicatif complet, app.<nom>.localhost — dans les deux écritures de KIREXO_RESERVED_DOMAINS (.env et le repli :- de compose.override.yaml), et cette forme-là n'a pas du tout le même mode de panne : le proxy route parfaitement, le conteneur répond, et c'est la résolution Host → Site qui ne reconnaît plus l'adresse comme applicative — 404 sur toute l'application, /login compris, pendant que l'infrastructure se déclare saine. Neuf copies en tout, réparties dans sept fichiers qu'aucun lien de code n'unit. Le renommage local → main en a d'ailleurs oublié plusieurs, à deux reprises, sans qu'aucun signal ne le dise — c'est exactement le mode de panne que cette dispersion produit. Des cas bats extraient désormais ces sources de leurs fichiers et les comparent entre elles plutôt que de recopier la valeur (tests/Bash/confinement/peer_aliases.bats) ; l'inventaire fichier par fichier est en référence, Les neuf copies du nom du dépôt principal.
Le nom main est particulier à deux titres, et cette dissymétrie est voulue : il est accepté comme worktree par défaut (c'est le défaut posé par proxy:up) mais refusé comme nom de worktree utilisateur par proxy_write_site (infra/proxy/proxy.lib.sh). Un worktree homonyme écraserait le routage du dépôt principal et dupliquerait l'alias php-main sur le réseau du proxy — deux conteneurs répondant au même nom, en round-robin.
Cinq autres noms sont refusés, et un seul l'est pour une collision : demo, qui produirait app.demo.localhost, l'adresse déjà déclarée en dur dans le repli pour le site de démonstration — donc un duplicate site address qui ferait échouer le rechargement pour tous les worktrees. Les quatre autres le sont pour une ambiguïté de lecture ou de routage : app (préfixe de service de l'application — docs.app.localhost se lirait aussi bien « la doc du worktree app » que « le worktree docs.app »), mailpit (même famille : depuis le retrait du bloc mailpit.localhost du repli, un worktree mailpit ne dupliquerait plus aucune adresse, mais mailpit.mailpit.localhost resterait illisible), localhost et www.
Deux derniers noms, shared et proxy, sont refusés pour une raison d'une autre nature — et c'est ce qui rend la liste utile au-delà du routage. Le projet Compose d'un worktree vaut kirexo-<worktree> : un castor wt:up shared viserait donc kirexo-shared, c'est-à-dire la stack mutualisée, et son up --remove-orphans en retirerait egress-proxy comme un conteneur devenu orphelin. La sortie réseau de tous les worktrees tomberait d'un coup, pour un nom de ticket malheureux. La liste réservée est donc une barrière commune à deux espaces de noms distincts, l'hôte HTTP et le projet Compose.
Que ce second espace de noms cloisonne réellement suppose une chose qui n'allait pas de soi : que le nom du projet soit calculé à partir du worktree, et non lu quelque part. Il était lu — dans le COMPOSE_PROJECT_NAME de .env.worktree, publié dans l'environnement du process. Un fichier absent, et Compose retombait sur la valeur ambiante : la commande ne cassait pas, elle s'adressait à une autre stack, ou à aucune. Le cloisonnement n'était pas franchi, il était simplement inopérant — le même mode de panne que le proxy démarré sur la mauvaise adresse, plus haut sur cette page. Les cibles wt:* passent donc désormais un -p kirexo-<worktree> explicite, dérivé du seul nom du worktree. La contrepartie est qu'une valeur éditée à la main dans le fichier n'est plus honorée : elle est signalée, parce qu'une correction muette aurait remplacé une panne silencieuse par une réparation silencieuse. Le détail de ce contrôle est en référence — Le projet Compose visé par les cibles de worktree.
Ce routage a un corollaire applicatif qui n'a rien d'infrastructurel : app.main.localhost doit figurer dans KIREXO_RESERVED_DOMAINS. Sans lui, HostResolutionSubscriber (src/Plugin/Web/src/EventSubscriber/HostResolutionSubscriber.php) prend le dépôt principal pour un domaine de site public, ne trouve aucun Site correspondant et rend 404 sur toute l'application, /login compris. Le mode de panne est particulièrement retors : le proxy, lui, répond parfaitement — un 502 aurait accusé l'infrastructure, un 404 accuse l'application. La comparaison se fait par égalité exacte (SiteResolver::isAppDomain(), src/Plugin/Web/src/Service/SiteResolver.php), jamais par suffixe : un renommage d'URL applicative qui oublie cette liste tombe donc en 404 généralisé, pas en dégradé.
Les domaines de site publics et le worktree par défaut¶
app.demo.localhost n'est pas une URL d'infrastructure : c'est un domaine de site, celui du site de démonstration des fixtures (SiteFixtures::DEMO_HOST, src/DataFixtures/SiteFixtures.php), résolu dynamiquement en base par le sous-système multi-tenant (cf. Multi-tenant : résolution d'un domaine vers un site). Il ne peut donc pas être attribué à un worktree en particulier au moment d'écrire une conf.
Deux propriétés structurelles règlent le problème sans arbitrage supplémentaire :
- Caddy choisit le bloc de site dont l'adresse est la plus spécifique :
app.ticket-185.localhostest servi par son propre bloc, jamais par le joker qui le précède. Mais « aucun bloc dédié » ne veut pas dire « repli » — un joker ne remplace qu'un seul label. Un domaine de site ennotes.localhosttombe bien dans le*.localhost, avec le certificat wildcard et l'avertissement décrits plus haut ; un nom à deux labels ou plus sans bloc à lui n'est servi par rien du tout,infra/proxy/Caddyfilen'important quesites/*.caddyet n'offrant aucun catch-all. - Un domaine de site ne collisionne jamais avec un nom d'infrastructure
<service>.<worktree>.localhost, sauf à porter les mêmes labels — d'où le refus du nom de worktreedemo, qui produirait exactement l'adresse du site de démonstration.
« Rien ne répond » : deux pannes qui ne se diagnostiquent pas au même étage
Vues du navigateur, elles se ressemblent — et l'une des deux envoie chercher au mauvais endroit.
- Un bloc existe, l'upstream est absent — worktree déclaré dont les conteneurs ne tournent pas, ou alias réseau qui a divergé du nom visé. La poignée de main aboutit, le certificat est valide, et le proxy rend un
502. La requête est bien passée :docker compose psetcastor wt:upsont les gestes utiles. - Aucun bloc ne matche le nom — worktree détruit (
castor wt:destroyretire son fichier de site, cf.castor/worktree.php), ou domaine de site à deux labels que personne n'a déclaré. Le joker ne l'atteint pas, aucun certificat n'est émis pour lui, et la poignée de main n'a pas lieu : le navigateur rendERR_SSL_PROTOCOL_ERROR. Il n'y a aucune requête HTTP — donc aucun log applicatif, aucune trace Sentry, et rien à chercher côté conteneur. Le geste est d'écrire le bloc manquant :castor wt:uppour un worktree, un bloc explicite dans le repli pour un domaine de site, sur le modèle de celui d'app.demo.localhost.
Les domaines de site qu'il sert, le repli les route donc vers un worktree, désigné par un marqueur dans infra/proxy/fallback.caddy.tpl — le worktree par défaut. Il vaut main dès le premier castor proxy:up, puis suit les créations et destructions de worktrees. Une seule base de données pouvant revendiquer app.demo.localhost à la fois, c'est un arbitrage assumé et affiché : castor proxy:status dit lequel.
Le site de démonstration, lui, ne passe plus par le joker : comptant trois labels, il est hors de portée de *.localhost et le repli lui consacre un bloc explicite, avec le même upstream que le joker. C'est ce bloc qui lui vaut une feuille de certificat dédiée, donc une visite sans avertissement.
D'où une asymétrie qu'il faut lire comme une paire, et non comme deux réglages indépendants : app.main.localhost doit être dans KIREXO_RESERVED_DOMAINS (c'est l'application), app.demo.localhost ne doit jamais y être (c'est un site). Y mettre les deux ferait disparaître le site de démonstration derrière le routage applicatif — une panne exactement aussi silencieuse que la précédente, et symétrique.
Ce que cette page ne couvre pas¶
- Les cibles
proxy:up,proxy:reload,proxy:down,proxy:migrate,proxy:statusetcert:trust, leurs options et leur sortie : Commandes Castor — Proxy hôte. - Les variables du proxy, les alias, et le sort des anciennes variables de port : Variables d'environnement.
- L'installation de la CA dans le trust store et le retrait de l'ancienne racine : Installer la CA du proxy de développement.
- Le contrat de confinement, ses invariants et ses sévérités : Modèle de menace et contrat de confinement et
.claude/skills/_shared/confinement.md. - La sortie réseau du conteneur vers Internet, qui passe par un tout autre proxy : Pourquoi la sortie réseau passe par un proxy à allowlist.
- L'instanciation multiple de la stack et le fichier
.env.worktree: Variables de worktree.