Diagnostiquer un blocage réseau sortant¶
Vous êtes développeur·se sur Kirexo, une commande lancée depuis un conteneur (composer, npm, curl, Claude Code, mkdocs) échoue sur un accès réseau, et vous voulez savoir ce qui bloque. Cette recette part du symptôme et remonte jusqu'à la cause.
Prérequis¶
- Vous savez quelle commande échoue et quel message exact elle affiche.
- Pour les étapes de réparation : un terminal côté hôte à la racine du dépôt (les cibles d'écriture sont hôte-only).
Le signal le plus précoce : l'avertissement affiché à l'ouverture d'un worktree
castor wt:shell et castor wt:claude sondent la sortie réseau avant de vous rendre la main, et affichent le bloc Pas de sortie réseau depuis ce worktree. quand elle est morte — avec le compteur de redémarrages d'egress-proxy s'il est non nul, et le remède à jouer côté hôte. L'avertissement n'empêche jamais l'ouverture : vous pouvez l'ignorer, ou le suivre. S'il est apparu, sautez directement à l'étape 3 : la cause est déjà nommée. Format exact et limites : La sonde de sortie réseau à l'ouverture.
Le modèle mental en une phrase
Le conteneur n'a aucune route vers l'extérieur. Sa seule sortie est le proxy egress-proxy, qui n'ouvre un tunnel CONNECT que vers les domaines de son allowlist. Tout blocage tient donc à l'une de ces trois questions : le client parle-t-il au proxy ? le proxy est-il joignable ? le domaine est-il dans l'allowlist ? Le fonctionnement d'ensemble est expliqué dans Pourquoi la sortie réseau passe par un proxy à allowlist.
1. Lire l'état de la sortie réseau¶
Depuis le conteneur — la cible est en lecture seule, elle ne modifie rien :
Lancée depuis un terminal hôte, ses trois sondes ne mesurent pas le proxy
Rien ne l'empêche de tourner côté hôte, et rien ne vous le signale à l'écran. Les sondes s'exécutent pourtant là où tourne Castor : depuis l'hôte, elles empruntent la route normale de l'hôte, donc packagist.org passe, example.com passe aussi — et ces verdicts ne disent rien de la politique appliquée par egress-proxy, y compris quand il est mort. Seul l'affichage des whitelists reste exact, puisqu'il lit des fichiers. Pour un diagnostic de sortie réseau, entrez d'abord : castor wt:shell, puis castor firewall:status. Cf. castor firewall:status.
Elle affiche les whitelists depuis lesquelles l'allowlist du proxy est rendue — avec le dossier réellement lu, sur la ligne Lu dans … —, les variables HTTPS_PROXY / NO_PROXY effectives, puis trois sondes. Leur combinaison suffit à orienter le diagnostic :
packagist.org via proxy |
example.com via proxy |
packagist.org sans proxy |
Interprétation |
|---|---|---|---|
OK |
OK |
OK |
Nominal : la sortie autorisée passe, la sortie non autorisée est refusée, aucune route directe ne subsiste. Le blocage vient d'un domaine précis → Ouvrir un domaine. |
KO |
OK |
OK |
Le proxy répond mais refuse un domaine qui devrait passer : allowlist périmée côté proxy → étape 4. |
KO |
KO |
OK |
Le proxy n'est pas joignable du tout → étape 3. |
| — | — | KO affiché en rouge |
Une route directe existe : un réseau non-internal est attaché au conteneur. Anomalie de confinement → castor confinement:check. |
La cible sort toujours en code 0, même quand une sonde est rouge : c'est un outil de lecture. Le gate, c'est castor confinement:check.
Lancée depuis le conteneur d'un worktree, la liste n'est pas celle du proxy
Le dépôt principal — d'où l'allowlist est rendue — n'est pas monté dans la cellule d'un worktree : la cible y lit /app/infra/firewall, c'est-à-dire les fichiers du worktree, que plus rien n'alimente. Elle le dit explicitement (⚠️ Worktree : cette whitelist n'est PAS celle que le proxy applique). Dans la cellule du dépôt principal, il n'y a pas d'écart et aucun avertissement. Dans les deux cas, seules les sondes mesurent la sortie réelle — cf. Une seule whitelist, celle du dépôt principal.
2. Traduire le message d'erreur¶
| Message | Cause | Suite |
|---|---|---|
curl: (56) CONNECT tunnel failed, response 403 |
Le proxy refuse le domaine : il n'est pas dans l'allowlist. | Ouvrir un domaine, puis étape 4 si le domaine y est déjà. |
CONNECT tunnel failed, response 403 qui se répète après l'ouverture du domaine |
Un téléchargement refusé a laissé un artefact de 0 octet, retéléchargé en boucle. | Étape 11. |
curl: (7) Failed to connect to egress-proxy port 3128 |
Le proxy est arrêté, ou le conteneur n'est pas attaché au réseau kirexo-egress. |
Étape 3. |
curl: (5) Could not resolve proxy: egress-proxy — ou exit 6, avec http_code 000 |
Le nom du proxy ne résout plus : son conteneur a disparu, ou il est en cours de redémarrage permanent. | Étape 3, puis 9 ou 12 si le conteneur est en Restarting, selon le message répété. |
🔒 Confinement ROUGE — le travail est suspendu. à l'ouverture d'une session Claude Code, avec C3 dans les invariants en échec |
Le gate SessionStart a constaté qu'il ne reste plus aucune sortie réseau. |
Étape 3. |
API Error: Unable to connect to API dans une session Claude Code déjà ouverte, sans aucun autre signal |
Le proxy est mort pendant la session : le gate ne repasse qu'au démarrage d'une session. | Étape 3. Relancer la session par castor wt:claude fait désormais apparaître la cause en clair, avant que Claude ne démarre. |
Pas de sortie réseau depuis ce worktree. au lancement de castor wt:claude ou castor wt:shell |
La sonde de sortie réseau de la cible a échoué depuis le conteneur : il ne reste aucune route. Le lancement se poursuit quand même. | Étape 3 — le bloc affiche déjà le remède, et le compteur de redémarrages du proxy s'il est non nul. |
Could not resolve host: <domaine externe> |
Le client n'utilise pas le proxy : il tente une résolution locale, qui échoue par conception. | Étape 5. |
| Timeout muet, sans message | Typique d'un runtime Node qui ignore les variables de proxy. | Étape 5. |
network kirexo-egress declared as external, but could not be found |
Le projet Compose mutualisé kirexo-shared n'a jamais été démarré sur ce poste. |
Étape 6. |
network kirexo-proxy declared as external, but could not be found |
Le réseau du proxy hôte n'existe pas encore sur ce poste. | Étape 6. |
could not translate host name "database" |
La stack est attachée à un réseau devenu orphelin — sans rapport avec le proxy. | Étape 7. |
Deux faux symptômes à ne pas poursuivre
getent hosts packagist.orgéchoue depuis le conteneur. C'est attendu : le conteneur ne résout pas les noms externes, c'est le proxy qui résout. Ne construisez aucun diagnostic là-dessus.curl --noproxy '*' https://packagist.orgéchoue. C'est la preuve que le confinement fonctionne — l'absence de route est la garantie recherchée, pas une panne.
3. Vérifier que le proxy tourne¶
C'est le premier réflexe quand plus rien ne sort — ni composer, ni npm, ni Claude Code. Le proxy est la sortie unique de tout l'environnement de développement : disparu, il ne reste aucune route vers l'extérieur, et le contrôle de confinement le nomme :
Un C3 en ✗ KO portant la mention PROXY INJOIGNABLE ne veut dire qu'une chose : le proxy ne répond plus. La ligne affiche le remède, et ce KO arme le gate SessionStart — une session Claude Code s'ouvre alors sans travailler, tant que la sortie n'est pas revenue. Détail du volet : castor confinement:check — C3.
Cas bénin à écarter d'abord : l'hôte vient de démarrer
Au boot, Docker relance les conteneurs restart: unless-stopped dans un ordre arbitraire : php peut être prêt avant egress-proxy, dont le healthcheck a un start_period de 10 s (compose.shared.yaml). Pendant cette fenêtre, la sonde rend le même échec (exit 6 ou exit 7) qu'un proxy définitivement perdu. Le remède est d'attendre une dizaine de secondes et de relancer castor confinement:check — pas d'agir.
Second cas bénin : un castor docker:up vient de recréer les singletons
Le proxy sortant et le Caddy hôte sont recréés quand leur parentage change — notamment au premier castor docker:up joué après une mise à jour du dépôt qui déplace leur ancrage. Pendant le up --wait, la sortie réseau et les services mutualisés sont coupés pour tous les worktrees : un téléchargement en cours échoue et doit être relancé.
Si la coupure se répète à chaque cible, un ping-pong est en cours : un worktree tourne encore une version antérieure de castor.php et réancre les singletons à l'inverse à chaque commande. Mettez tous les worktrees à jour — il n'y a rien d'autre à jouer. Cf. Préalable commun aux cibles qui démarrent une stack.
Passé ce cas, deux causes produisent le même exit 6 ou exit 7, et la sonde ne sait pas les distinguer : le conteneur a disparu, ou il redémarre en boucle. C'est côté hôte que la réponse se lit.
Le proxy vit dans un autre projet Compose (kirexo-shared), partagé par tous les worktrees. castor docker:down ne l'arrête donc pas, et il n'apparaît pas dans un docker compose ps du worktree.
# HÔTE
docker compose -p kirexo-shared -f compose.shared.yaml ps
docker compose -p kirexo-shared -f compose.shared.yaml logs --tail=50 egress-proxy
Les journaux Squid sortent sur les flux standard, une ligne par requête. Cherchez le verdict en fin de champ :
TCP_TUNNEL/200— le tunnel a été ouvert, le domaine est autorisé ;TCP_DENIED/403— refusé, suivi du domaine demandé. C'est la confirmation la plus directe qu'un domaine manque à l'allowlist.
Cas 1 — le conteneur est absent ou arrêté. Il ne figure pas dans le ps ci-dessus, ou il y figure en Exited. Remontez le projet mutualisé :
Depuis un terminal hôte, obligatoirement
Le conteneur constate la disparition du proxy, il ne peut pas la réparer : l'invariant C2 lui interdit tout socket Docker, donc toute commande sur le démon. Aucune cible Castor lancée de l'intérieur n'y changera quoi que ce soit. Cf. Modèle de menace et confinement.
Symétriquement, aucune cible Castor ne supprime egress-proxy : castor docker:down s'en abstient explicitement (il est mutualisé), et castor image:refresh se contente de le remonter en étape 0/4. Un conteneur disparu vient donc toujours d'un geste extérieur au dépôt — docker container prune, l'interface Docker Desktop, une suppression manuelle.
Une seule cible le recrée, et elle l'annonce : castor wt:destroy, quand le proxy était monté depuis le worktree détruit (cf. Le re-parentage des projets singletons). Le conteneur revient aussitôt ; seuls les tunnels en cours sont coupés.
Cas 2 — docker ps affiche Restarting
Ne poursuivez pas ce chemin : castor docker:up ne vous en sortira pas, il fait un start du conteneur existant et non un recreate — et il peut échouer sur container kirexo-shared-egress-proxy-1 is unhealthy. C'est la dernière ligne des journaux qui désigne l'étape à suivre :
| Message répété | Où aller |
|---|---|
FATAL: Squid is already running |
Étape 9 — le cliquet du fichier pid. |
FATAL: Unable to open configuration file |
Étape 12 — le conteneur monte un répertoire qui n'existe plus. |
4. Comparer l'allowlist du dépôt et celle que le proxy applique¶
Le fichier réellement lu par Squid est généré, pas écrit à la main — et c'est celui du dépôt principal, seul répertoire depuis lequel l'allowlist est rendue :
Trois vérifications, dans cet ordre :
- Le domaine y figure-t-il ? Chaque ligne commence par un point (
.symfony.com) : cette forme couvre le domaine et ses sous-domaines. Une ligne sans point ne couvrirait que le domaine exact — c'est le principal piège du mécanisme, expliqué dans Le point de tête. - Le fichier est-il à jour ? Il n'est régénéré que par
castor firewall:reload(ou par le démarrage de la stack). Une édition de whitelist sans rechargement n'a aucun effet. - Le proxy a-t-il relu le fichier ? Rechargez explicitement :
Un rechargement qui annonce « Allowlist régénérée » sans rien changer
Ce cas s'est produit en conditions réelles. Cause : la configuration du proxy était bind-montée par fichier. Un bind de fichier attache un inode ; toute écriture par éditeur ou sed -i en crée un nouveau côté hôte, et le conteneur reste sur l'ancien — squid -k reconfigure recharge alors sagement la politique d'avant, en affichant un succès.
Les montages portent désormais sur des dossiers (infra/egress/, infra/egress/generated/). Si vous ajoutez un montage lié au proxy, montez le dossier, jamais le fichier. En cas de doute sur ce que voit le conteneur :
5. Vérifier que le client parle bien au proxy¶
Un client qui n'honore pas les variables de proxy tente une résolution locale et échoue sur Could not resolve host, ou reste muet jusqu'au timeout.
Vous devez y trouver HTTP_PROXY, HTTPS_PROXY, leurs équivalents en minuscules, NO_PROXY / no_proxy et NODE_USE_ENV_PROXY. Points de vigilance :
- Les minuscules comptent.
curln'honore quehttp_proxyen minuscules ; Symfony HttpClient ignore volontairementHTTP_PROXYen majuscules hors SAPI CLI (parade httpoxy) mais lithttps_proxy. Les deux graphies sont posées pour cette raison. - Node. Le
fetchnatif et undici n'honorent les variables de proxy que siNODE_USE_ENV_PROXY=1est posée. Sans elle, un script Node du projet sort « en direct » et se prend un timeout muet. - Un service oublié. Seuls les services rattachés au proxy reçoivent ces variables. Si un nouveau service a besoin de sortir, il doit recevoir l'ancre d'environnement et être attaché au réseau
egressdanscompose.override.yaml. - Les tests E2E ne passent pas par le proxy, volontairement.
PANTHER_CHROME_ARGUMENTS(dans.env.test) contient--no-proxy-server: Chromium visehttps://localhostethttps://app.demo.localhost(SiteFixtures::DEMO_HOST), qui n'ont rien à faire dans un tunnel. Si vous voyez un échec E2E avec un403de proxy, c'est ce flag qui a sauté.
Le détail de chaque variable est en référence.
6. Le préalable manquant : « network kirexo-egress declared as external »¶
Le réseau kirexo-egress est déclaré external côté worktree : il doit exister avant tout docker compose up ou run. C'est le projet kirexo-shared qui le crée.
Le réseau kirexo-proxy — celui du proxy hôte — est dans le même cas, et produit le même message avec son propre nom. Il est créé, lui, par infra/proxy/proxy-net.sh.
Les cibles castor docker:up, castor docs:build, castor wt:up et castor image:refresh exécutent ce préalable pour vous — elles passent toutes par le même helper shared_stack_up() de castor.php. Un docker compose up lancé à la main, non : il ne traverse aucune cible Castor. Dans ce cas, jouez ces lignes côté hôte avant le up :
# HÔTE, à la racine du dépôt — équivalent manuel du préalable des cibles Castor
castor claude:space # espace Claude + jeton GitLab : sans lui, Docker crée
# des dossiers root-owned dans $HOME à la place des binds
bash infra/proxy/proxy-net.sh # réseau kirexo-proxy (internal) + règle de cloisonnement
[ -e infra/firewall/whitelist.local.txt ] || cp infra/firewall/whitelist.local.txt.dist infra/firewall/whitelist.local.txt
bash infra/egress/render-allowlist.sh
docker compose -p kirexo-shared -f compose.shared.yaml up -d --wait
Le conteneur du proxy, lui, n'est pas démarré par ce préalable : il l'est par castor proxy:up, à jouer une fois sur le poste (cf. Commandes Castor — Proxy hôte).
7. Après un changement de réseau : recréer toute la stack¶
Symptôme : castor test:e2e échoue sur could not translate host name "database", alors que docker compose ps montre tous les services démarrés.
Cause : modifier les propriétés du réseau default force Docker à le recréer. Les conteneurs d'infrastructure déjà démarrés restent attachés à l'ancien réseau, devenu orphelin : ils tournent, mais database, redis, rabbitmq… deviennent invisibles depuis php.
Remède — recréer toute la stack, pas seulement php :
# HÔTE, dans le worktree concerné
castor wt:up <ticket> # ou : castor docker:up dans le dépôt principal
Un simple docker compose restart php ne suffit pas : les conteneurs d'infrastructure ne sont pas recréés.
Même cause, même remède après un castor proxy:migrate : le réseau kirexo-proxy ayant été supprimé puis recréé, tout conteneur qui n'a pas été recréé depuis référence un identifiant de réseau disparu — y compris dans les worktrees qui étaient seulement arrêtés.
8. Diagnostic global¶
# Depuis le conteneur — amorçage, sondes réseau, supervision, transports, résolution intra-stack
castor doctor
# Depuis l'hôte — binaires hôte, état des services, proxy sortant, migrations
castor doctor
# Depuis l'un ou l'autre — vérifie les invariants de confinement par leur effet
castor confinement:check
castor doctor s'adapte au côté d'où il est lancé : il n'y a plus de cible de diagnostic séparée pour l'intérieur du conteneur.
castor confinement:check est le seul des trois à faire autorité sur l'isolation. Un statut ⚠ WARN « conteneur périmé » ou « image périmée » signifie que le dépôt porte déjà le correctif mais que votre conteneur (ou votre image) n'a pas encore été recréé : chaque ligne affiche son remède. Cf. Modèle de menace et confinement.
9. Le proxy redémarre en boucle : FATAL: Squid is already running¶
Comment reconnaître le cas. Depuis un conteneur applicatif, curl sort en exit 5 (« couldn't resolve proxy ») ou en exit 6, avec un http_code de 000 ; castor confinement:check fait passer C3 (« Sortie réseau fermée par défaut ») en ✗ KO, avec la mention PROXY INJOIGNABLE — c'est le même verdict que pour un conteneur supprimé, les deux causes étant indistinguables depuis l'intérieur. Côté hôte, docker ps montre kirexo-shared-egress-proxy-1 en Restarting, et ses journaux répètent FATAL: Squid is already running : c'est ce qui tranche entre les deux.
Ce qui bloque. Squid est le PID 1 de son conteneur. Après une mort brutale, son fichier pid survit avec la valeur 1 et le Squid suivant — PID 1 lui aussi — se prend pour un Squid déjà démarré. Rien ne casse ce cliquet tout seul : ni restart: unless-stopped, ni autoheal, ni castor docker:up. Le détail du mécanisme est dans Deux pannes révélatrices.
Comme la sortie réseau est mutualisée, la panne coupe tous les worktrees à la fois, et castor docker:up échoue sur container kirexo-shared-egress-proxy-1 is unhealthy.
Le geste qui débloque — il faut jeter la couche writable du conteneur, donc le supprimer, pas le redémarrer :
# HÔTE, à la racine du dépôt
docker compose -p kirexo-shared -f compose.shared.yaml rm -sf egress-proxy
docker compose -p kirexo-shared -f compose.shared.yaml up -d --wait egress-proxy
C'est le rm -sf qui compte : il détruit le conteneur et le fichier pid avec lui. Un --force-recreate seul n'a pas suffi dans un cas observé.
Pourquoi une commande docker compose brute, ici et nulle part ailleurs
La règle du projet est « Castor est le task runner unique » : tout passe par une cible. Ces deux lignes en sont la seule exception de cette page, et pour une raison précise — aucune cible ne fait ce geste, et aucune ne pourrait le faire sans changer de périmètre.
castor docker:up amène le proxy à l'état « démarré » (up -d --wait) mais ne le détruit jamais, ce qui est exactement ce qu'il faut ici. castor docker:down, lui, épargne délibérément le projet kirexo-shared : il est partagé par tous les worktrees, et le descendre couperait la sortie réseau des autres (castor.php). Le geste de recréation vise donc un conteneur qui n'appartient pas au projet Compose du worktree — d'où les -p kirexo-shared -f compose.shared.yaml explicites, sans lesquels Compose ne le trouverait pas.
Corollaire : la commande coupe brièvement la sortie réseau de tous les worktrees. C'est acceptable ici parce qu'elle est déjà coupée.
Contrôlez ensuite le retour à la normale depuis le conteneur avec castor firewall:status : la sonde packagist.org via proxy doit repasser OK. Un castor wt:shell qui s'ouvre sans avertissement de sortie réseau donne le même verdict, en un geste de moins.
Le correctif est en place — si le cas se reproduit, votre conteneur est périmé
Le service egress-proxy monte désormais /tmp en tmpfs (compose.shared.yaml) : le fichier pid est recréé vide à chaque démarrage, le cliquet ne peut plus s'armer. Vérifié par l'effet — deux docker kill suivis de docker start d'affilée, le proxy revient healthy à chaque fois et son RestartCount reste à 0.
Rencontrer encore FATAL: Squid is already running signifie donc que le conteneur en cours tourne sur une définition antérieure au correctif. Les deux commandes ci-dessus le recréent sur la définition à jour et closent le sujet.
10. Un service redémarre en boucle depuis son passage par le proxy¶
Comment reconnaître le cas. Un service bascule unhealthy puis redémarre, encore et encore, alors que ses propres journaux ne montrent rien d'anormal et qu'il répond correctement quand on l'interroge à la main. Le service docs en a fait les frais : deux redémarrages en 90 s, tracés au niveau du daemon par Container /kirexo-docs-1 found to be unhealthy - Restarting container now — c'est le conteneur autoheal qui applique la sanction que le healthcheck a demandée. Le compteur se lit directement :
Signe complémentaire, côté proxy : des TCP_DENIED/403 qui ne correspondent à aucune sortie légitime attendue.
Ce qui bloque. Le service a reçu l'ancre d'environnement <<: *proxy-env et son healthcheck utilise wget. Or, sur une image Alpine, ce wget est celui de BusyBox : il honore http_proxy mais ignore no_proxy. Le healthcheck, qui vise pourtant http://127.0.0.1:8000, part donc vers egress-proxy — lequel refuse tout ce qui n'est pas un CONNECT et rend 403. Le service est sain ; c'est son healthcheck qui ment.
Le correctif — vider les variables de proxy pour la seule durée du healthcheck (compose.override.yaml) :
test: ["CMD", "env", "http_proxy=", "https_proxy=", "wget", "--spider", "-q", "http://127.0.0.1:8000"]
Le -Y off de BusyBox (« proxy off ») ferait le même effet, mais il ne survit pas à un changement de base : en GNU wget, -Y est l'alias de --proxy et attend un booléen. Un http_proxy vide est ignoré par les deux implémentations — la forme retenue résiste donc à un futur bump de squidfunk/mkdocs-material hors d'Alpine.
La règle à retenir : tout service à qui l'on ajoute <<: *proxy-env et dont le healthcheck utilise wget doit neutraliser les variables de proxy dans la commande de test. curl honore no_proxy : il n'a pas besoin de ce traitement. Le healthcheck de mailer (compose.shared.yaml) a exactement la même forme sans neutralisation et reste sain — parce que ce service ne reçoit pas les variables de proxy ; le jour où il les recevra, il faudra le corriger aussi.
Ce que ce recyclage explique
Les fenêtres d'indisponibilité de la documentation sur https://docs.<worktree>.localhost venaient de ce redémarrage permanent — pas de castor docs:build, qui construit le site dans ./site sans toucher au service docs. Le service n'expose aucun port sur l'hôte : il n'est joignable que par le proxy hôte (depuis un navigateur) ou par son alias applicatif docs-int:8000 (depuis le conteneur php).
11. Un téléchargement refusé laisse un artefact vide¶
Comment reconnaître le cas. Une commande qui télécharge un fichier échoue sur un 403 au CONNECT, vous ouvrez le domaine dans l'allowlist… et l'erreur revient à l'identique, en nommant le même domaine, alors que castor firewall:status confirme que le domaine est bien autorisé.
Observé sur le binaire Tailwind, téléchargé par symfonycasts/tailwind-bundle au premier bin/console tailwind:build — donc sur tout worktree neuf, var/tailwind/ étant gitignoré :
! [NOTE] Downloading TailwindCSS binary from https://github.com/tailwindlabs/tailwindcss/releases/download/v4.1.11/tailwindcss-linux-x64-musl
In ErrorChunk.php line 73:
CONNECT tunnel failed, response 403 for "https://release-assets.githubusercontent.com/…"
Le domaine cité n'est pas celui de l'URL affichée : GitHub redirige les assets de release vers release-assets.githubusercontent.com, et c'est ce hôte-là qui doit être autorisé. Il figure dans infra/firewall/baseline-domains.txt — un 403 sur ce domaine signifie donc que l'allowlist appliquée par le proxy est plus ancienne que celle du dépôt : castor firewall:reload depuis le dépôt principal (cf. étape 4).
Ce qui bloque. La tentative refusée laisse un fichier de 0 octet à l'emplacement cible. Le bundle ne le considère pas comme un binaire valide : il retélécharge — et rien dans le message ne dit qu'un résidu traîne. L'erreur se répète donc à l'identique, y compris une fois le domaine ouvert, tant que le fichier vide n'a pas été retiré.
Le geste qui débloque — après avoir ouvert le domaine, supprimer l'artefact vide avant de relancer :
La règle à retenir, valable au-delà de ce cas : après un 403 sur un téléchargement, vérifier l'emplacement cible avant de conclure. Un artefact de 0 octet transforme une panne réparée en panne qui se répète, et le second message est indiscernable du premier.
12. Le proxy redémarre en boucle sur Unable to open configuration file¶
Comment reconnaître le cas. Depuis un conteneur, les symptômes sont ceux de l'étape 9 — curl en exit 5 ou 6, http_code à 000, C3 en ✗ KO avec PROXY INJOIGNABLE, et côté Claude Code une erreur de connexion à l'API qui ne dit rien d'utile. Ce qui tranche est dans les journaux du proxy, côté hôte :
# HÔTE
docker ps --filter name=egress-proxy --format '{{.Names}} {{.Status}}'
docker logs --tail 5 kirexo-shared-egress-proxy-1
Le compteur de redémarrages confirme l'ampleur — restart: unless-stopped relance sans fin :
Ce qui bloque. Le conteneur monte ./infra/egress depuis le répertoire où le projet kirexo-shared a été créé, en chemin absolu figé. Si ce répertoire était un worktree depuis supprimé, Docker recrée le chemin manquant en dossier vide appartenant à root, et Squid ne trouve plus sa configuration.
Les cibles Castor ne créent plus kirexo-shared que depuis le dépôt principal, qu'aucune destruction de worktree n'emporte : ce cas ne concerne donc plus que les conteneurs créés avant cet ancrage, ou créés par un docker compose up lancé à la main depuis un worktree. Vérifiez le parentage — la source affichée désigne alors un répertoire inexistant ou vide :
# HÔTE
docker inspect -f '{{range .Mounts}}{{.Source}}{{"\n"}}{{end}}' kirexo-shared-egress-proxy-1
docker inspect -f '{{index .Config.Labels "com.docker.compose.project.working_dir"}}' kirexo-shared-egress-proxy-1
Le raisonnement est dans Un singleton est parenté sur le répertoire qui l'a créé.
Le geste qui débloque — recréer le service depuis le dépôt principal, seul répertoire dont on sait qu'il survivra :
# HÔTE, à la racine du dépôt principal
bash infra/egress/render-allowlist.sh
docker compose -p kirexo-shared -f compose.shared.yaml up -d --force-recreate --wait egress-proxy
Le --force-recreate est le point décisif : un up -d seul ne change rien, la définition du service n'ayant pas bougé — c'est le conteneur, et lui seul, qui porte le mauvais chemin. Le rendu de l'allowlist vient d'abord : infra/egress/generated/allowlist.conf est un fichier généré, gitignoré, et son absence fait crash-looper Squid exactement de la même façon.
Contrôlez ensuite depuis le conteneur avec castor firewall:status : la sonde packagist.org via proxy doit repasser OK.
Le Caddy hôte porte le même défaut, en sommeil
kirexo-proxy monte ./Caddyfile, un bind de fichier, donc d'inode : après la disparition de son répertoire fondateur, le conteneur continue de tourner healthy sur un inode fantôme. La panne n'attend qu'un docker restart ou un reboot pour tomber sur le seul point d'entrée web de tout l'environnement de dev. Le contrôle et le remède sont les mêmes :
Jamais de down -v pour « repartir propre »
Le volume caddy_proxy_data du projet kirexo-proxy porte la CA racine locale, émise pour dix ans. La détruire obligerait à rejouer castor cert:trust sur tous les postes, et ferait avertir les navigateurs sur toutes les URLs *.localhost entre-temps. Le remède est une recréation de service, jamais une descente de projet avec ses volumes.
Depuis castor wt:destroy, ce geste est fait pour vous
La destruction d'un worktree détecte les conteneurs singletons qui le référencent et les re-parente sur le dépôt principal avant de retirer le répertoire — l'ordre compte, une fois le worktree supprimé les dossiers root-owned semés par Docker exigent un sudo pour être retirés. La commande sort en 1 si la recréation n'a pas abouti, avec la ligne à rejouer. Cf. Le re-parentage des projets singletons.
Ce cas de figure reste possible quand un répertoire de worktree est supprimé à la main, sans passer par la cible.
Voir aussi¶
- Ouvrir un domaine dans l'allowlist du proxy sortant — la recette d'ajout.
- Pourquoi la sortie réseau passe par un proxy à allowlist — ce que garantit
internal: true, et ce qu'il ne garantit pas. - Commandes Castor — Sortie réseau — les cibles
firewall:*en détail. - Worktrees et environnement de développement — réseaux, montages
:ro, cibles hôte-only.