Aller au contenu

Variables d'environnement du dépôt (développement et déploiement du mainteneur)

Cette page s'adresse aux développeur·ses et au mainteneur qui déploie depuis le dépôt (compose.yaml + compose.prod.yaml).

Référence des variables déclarées dans .env à la racine du dépôt. .env ne contient que des valeurs par défaut non secrètes et est versionné.

Gestion des secrets

  • Les credentials réels (mots de passe, clés API, tokens, DSN avec mot de passe) vivent dans .env.local, non versionné (présent dans .gitignore).
  • En production, les secrets sont injectés via les variables d'environnement du compose.prod.yaml ou un gestionnaire externe. Ils ne transitent jamais par Git.
  • En cas de fuite : changer immédiatement la valeur dans tous les environnements avant de chercher la cause.

Symfony charge les variables dans l'ordre suivant : .env → .env.local → variables d'environnement du process. La dernière valeur lue gagne.

Vous installez Kirexo chez vous ?

Cette page ne vous concerne pas : vos réglages sont décrits dans Paramètres de l'instance.

À surcharger obligatoirement en production

Les valeurs présentes dans .env sont des valeurs factices destinées au seul environnement de développement local. Elles ne doivent jamais être utilisées en production. Avant tout déploiement, vérifier que chacune des variables ci-dessous est définie via compose.prod.yaml ou un gestionnaire de secrets externe :

Variable Risque si non surchargée
APP_SECRET Signature CSRF et cookies prévisibles → forge de session possible.
POSTGRES_PASSWORD Mot de passe !ChangeMe! connu publiquement (versionné) → accès BDD trivial.
DATABASE_URL Contient POSTGRES_PASSWORD — recomposer ou réutiliser le DSN avec le nouveau mot de passe.
RABBITMQ_USER / RABBITMQ_PASSWORD Couple guest/guest par défaut → prise de contrôle du bus de messages.
MESSENGER_TRANSPORT_DSN Contient les credentials RabbitMQ — à recomposer en cohérence.
CADDY_MERCURE_JWT_SECRET Secret connu → forge de JWT Mercure (publication arbitraire d'événements SSE).
TYPESENSE_API_KEY Clé xyz-dev-key connue → lecture/écriture arbitraire dans l'index de recherche.
KIREXO_RESERVED_DOMAINS Obligatoire (${…:?…}). Absente ou vide ⇒ docker compose refuse de démarrer. Laissée à la valeur du .env (localhost,127.0.0.1,…) ⇒ le domaine réel n'est pas réservé, la résolution Host → Site le traite comme un domaine de site inconnu : 404 sur toute l'application, /login compris.
DEFAULT_URI Obligatoire (${…:?…}). Laissée à https://localhost ⇒ le lien de réinitialisation du mot de passe, rendu par le worker, pointe vers https://localhost. Son hôte doit figurer dans KIREXO_RESERVED_DOMAINS.
MAILER_DSN Obligatoire (${…:?…}). Laissée à smtp://mailer-int:1025 (Mailpit de dev) ⇒ hôte inexistant, aucun e-mail ne part.
MAILER_FROM_ADDRESS Obligatoire (${…:?…}). Laissée à noreply@kirexo.local ⇒ domaine non routable, SPF/DKIM impossibles, messages classés en spam.
MERCURE_PUBLIC_URL Obligatoire (${…:?…}). Laissée à https://localhost/.well-known/mercure ⇒ l'EventSource du navigateur ne se connecte pas : autosave de l'éditeur et temps réel cassés.
SERVER_NAME localhost par défaut → certificats Caddy invalides en prod. À fixer au domaine réel.
SENTRY_DSN Vide → aucune télémétrie d'erreurs en prod. À renseigner.
GRAYLOG_HOST Vide → aucun log centralisé en prod, et une tentative d'envoi UDP perdue par log ≥ warning. À renseigner.
CLAUDE_API_KEY_CIPHER_KEY Absente ou vide ⇒ docker compose refuse de démarrer (déclaration ${…:?…} dans compose.prod.yaml). Changée ⇒ clé API Claude stockée illisible, à ressaisir. Cf. Chiffrement de la clé API Claude.

Règle absolue

Aucune valeur secrète ne transite par Git. Si l'une des valeurs ci-dessus est jamais commitée par erreur (même brièvement), la considérer comme compromise et la régénérer dans tous les environnements avant de chercher la cause de la fuite.

Variables d'exécution obligatoires (:?)

Cinq variables sont déclarées obligatoires dans l'ancre x-kirexo-app-environment de compose.prod.yaml, fusionnée dans les services php et worker : les deux reçoivent exactement les mêmes valeurs. Le worker en a besoin autant que le serveur web : c'est lui qui rend les e-mails (liens absolus via DEFAULT_URI, envoi via MAILER_*).

Variable Forme attendue Exemple
KIREXO_RESERVED_DOMAINS Domaine(s) de l'application, CSV, sans schéma ni port, comparés par égalité exacte. Jamais un domaine de site. kirexo.example.org
DEFAULT_URI URI publique de l'application, sans chemin. Hôte présent dans KIREXO_RESERVED_DOMAINS. https://kirexo.example.org
MAILER_DSN DSN Symfony Mailer du SMTP sortant. Secret : les identifiants, URL-encodés, s'insèrent avant l'hôte. smtp://smtp.example.org:587
MAILER_FROM_ADDRESS Adresse d'expéditeur, sur un domaine couvert par SPF/DKIM. noreply@example.org
MERCURE_PUBLIC_URL URL publique du hub Mercure, vue par le navigateur. https://kirexo.example.org/.well-known/mercure

Comportement de la forme ${VAR:?message} :

  • Absente ou vide : l'interpolation échoue et toute commande docker compose -f compose.yaml -f compose.prod.yaml … s'arrête sur le message (config, pull, up, mais aussi down, logs, ps, exec). Le message commence par <VARIABLE> manquante ou vide : et renvoie vers cette page.
  • Définie : la valeur est transmise telle quelle. Aucune validation de forme n'est faite par Compose.
  • Source de la valeur : l'interpolation lit l'environnement du shell et le fichier .env du répertoire du projet Compose (celui de compose.yaml quand la commande est lancée depuis la racine du clone). Une variable du shell l'emporte sur .env. Sur un serveur qui contient un clone du dépôt, le .env versionné fournit les cinq variables avec leurs valeurs de développement : :? ne se déclenche pas, et l'instance démarre avec les pannes décrites dans le tableau ci-dessus.

MAIL_FROM n'est pas injecté en production

MAIL_FROM (en-tête From global, config/packages/mailer.yaml) est dérivé de MAILER_FROM_ADDRESS par le .env embarqué dans l'image : MAIL_FROM="Kirexo <${MAILER_FROM_ADDRESS}>". Symfony Dotenv résout ${MAILER_FROM_ADDRESS} depuis l'environnement réel du conteneur. Injecter MAIL_FROM dans compose.prod.yaml (par exemple sous la forme ${MAIL_FROM:-}) le figerait, éventuellement à vide, et tout envoi échouerait. La variable exposée à l'exploitant est MAILER_FROM_ADDRESS.

Procédure d'export sur le serveur : Déployer Kirexo en production.

Garde-fou des secrets d'exemple

En APP_ENV=prod, l'entrypoint de l'image (frankenphp/docker-entrypoint.sh, copié en /usr/local/bin/docker-entrypoint) refuse de lancer l'application si un secret est absent, vide ou égal à une valeur d'exemple. Le contrôle a lieu avant l'attente de la base : aucune connexion n'est tentée, aucune migration n'est jouée.

Portée : commandes frankenphp, php et bin/console, donc le serveur (php) et le worker Messenger (worker, dont la commande commence par php). Toute autre commande (composer, sh…) et tout autre APP_ENV (dev, test, non défini) ne sont pas contrôlés. docker compose exec ne passe pas par l'entrypoint et n'est jamais bloqué.

Libellé affiché Variable du conteneur Variable à renseigner côté hôte Génération
APP_SECRET APP_SECRET APP_SECRET openssl rand -hex 32
POSTGRES_PASSWORD (dans DATABASE_URL) mot de passe contenu dans DATABASE_URL POSTGRES_PASSWORD openssl rand -hex 32
MERCURE_PUBLISHER_JWT_KEY (CADDY_MERCURE_JWT_SECRET) MERCURE_PUBLISHER_JWT_KEY CADDY_MERCURE_JWT_SECRET openssl rand -hex 32
MERCURE_SUBSCRIBER_JWT_KEY (CADDY_MERCURE_JWT_SECRET) MERCURE_SUBSCRIBER_JWT_KEY CADDY_MERCURE_JWT_SECRET openssl rand -hex 32
CLAUDE_API_KEY_CIPHER_KEY CLAUDE_API_KEY_CIPHER_KEY CLAUDE_API_KEY_CIPHER_KEY openssl rand -base64 32

Le conteneur ne reçoit jamais POSTGRES_PASSWORD ni CADDY_MERCURE_JWT_SECRET : le premier arrive dans DATABASE_URL, le second est dérivé en MERCURE_PUBLISHER_JWT_KEY et MERCURE_SUBSCRIBER_JWT_KEY (compose.prod.yaml). Le mot de passe de DATABASE_URL est extrait sans décodage ; les formes URL-encodées refusées figurent telles quelles dans la liste.

RABBITMQ_PASSWORD (openssl rand -hex 32) n'est pas contrôlé par l'entrypoint, seulement par le diagnostic app:install:check, qui refuse aussi guest.

Liste des valeurs d'exemple

infra/install/example-secrets.txt est la source unique des valeurs refusées, lue par l'entrypoint (chemin relatif au WORKDIR, /app dans l'image) et par App\Service\Install\Check\SecretsCheck.

  • Une valeur par ligne, comparaison exacte et sensible à la casse ; les lignes commençant par # sont des commentaires.
  • Contenu actuel : !ChangeMe!, %21ChangeMe%21, !ChangeThisMercureHubJWTSecretKey!, la clé nulle de .env.test (AAAA…A=, 43 A suivis de =) et guest.
  • La valeur vide n'y figure pas : elle est refusée par un test séparé.
  • Tout placeholder de secret ajouté à .env ou compose.yaml doit y être ajouté.
  • Fichier illisible ⇒ refus de démarrer (garde-fou des secrets inopérant) : l'absence de liste n'est jamais interprétée comme « rien à refuser ».

Absent = valeur d'exemple

L'image de production n'a pas de dump-env : une variable absente de l'environnement du conteneur retombe sur le .env embarqué, qui porte justement les valeurs d'exemple. Le garde-fou traite donc « absente » comme « valeur d'exemple ».

Sur la pile compose.yaml + compose.prod.yaml, une variable non exportée côté hôte produit ce cas de deux façons : interpolée depuis le .env d'un clone du dépôt (APP_SECRET, POSTGRES_PASSWORD via le défaut !ChangeMe!), ou interpolée à vide (CADDY_MERCURE_JWT_SECRET, déclarée sans défaut).

Qui refuse quoi

Situation Refusée par
Secret non renseigné, là où le fichier Compose l'exige par ${VAR:?…} Docker Compose, avant tout démarrage (cf. Variables d'exécution obligatoires)
Secret vide ou absent qui a passé Compose (variable sans :?) l'entrypoint
Placeholder de développement recopié depuis .env ou compose.yaml (!ChangeMe!…) l'entrypoint
Mot de passe RabbitMQ par défaut (guest) le seul diagnostic app:install:check

Pourquoi -hex et pas -base64 dans une URL

POSTGRES_PASSWORD et RABBITMQ_PASSWORD finissent dans une URL (DATABASE_URL, MESSENGER_TRANSPORT_DSN). Le base64 y introduit /, + et =, qui en cassent l'analyse sans être encodés. openssl rand -hex 32 ne produit que [0-9a-f]. APP_SECRET et CADDY_MERCURE_JWT_SECRET suivent la même commande par uniformité. Seule CLAUDE_API_KEY_CIPHER_KEY est en openssl rand -base64 32 : la variable est décodée en 32 octets bruts (base64: dans #[Autowire], cf. Chiffrement de la clé API Claude).

Messages et état

Une ligne sur stderr par secret fautif, puis le bloc d'arrêt commun. Aucune valeur de secret n'est jamais écrite ; la valeur testée passe au grep par l'entrée standard, jamais en argument, et n'apparaît donc pas dans ps.

[kirexo]   - APP_SECRET : absente, vide ou valeur d'exemple. Générer : openssl rand -hex 32
[kirexo] ERREUR : secrets d'exemple ou absents en production : APP_SECRET.
[kirexo] Le serveur n'est PAS démarré : le conteneur reste en vie, état de santé rouge, sans redémarrage en boucle.
[kirexo] Renseigner ces variables dans le fichier .env de l'installation, puis recréer les conteneurs : docker compose up -d

Plusieurs secrets fautifs donnent plusieurs lignes -, et la ligne ERREUR les liste séparés par des virgules. Liste des valeurs introuvable :

[kirexo] ERREUR : liste des valeurs d'exemple introuvable (infra/install/example-secrets.txt) : garde-fou des secrets inopérant.
[kirexo] Le serveur n'est PAS démarré : le conteneur reste en vie, état de santé rouge, sans redémarrage en boucle.
[kirexo] Image incomplète : réinstaller une image publiée par la pipeline d'un tag.

Le conteneur se comporte ensuite comme dans l'état d'attente des migrations : vivant, unhealthy, sans redémarrage en boucle, sortie en 143 sur SIGTERM. Un docker restart relit le même environnement et retombe dans le même état : il faut recréer le conteneur. Procédure : Le conteneur reste unhealthy : secret d'exemple refusé.

Framework Symfony

Variable Défaut Rôle
APP_ENV dev Environnement applicatif (dev, test, prod).
APP_SECRET !ChangeMe! Secret utilisé pour la signature CSRF, les cookies, etc. À surcharger en prod.
TRUSTED_PROXIES 127.0.0.0/8,10.0.0.0/8,172.16.0.0/12,192.168.0.0/16 Liste CIDR des proxies de confiance. Définie inline dans compose.yaml pour Docker networking — ne pas redéfinir sauf en prod derrière un proxy personnalisé.
TRUSTED_HOSTS (vide) hors dev et CI — aucun filtre de Host Expression régulière des Host autorisés, lue par framework.trusted_hosts (config/packages/framework.yaml, %env(default::TRUSTED_HOSTS)%). Déclarée ${TRUSTED_HOSTS:-} dans compose.yaml et, à l'identique, dans l'ancre x-kirexo-app-environment de compose.prod.yaml : elle ne dérive plus de SERVER_NAME. Vide, elle se résout à null et Symfony ne pose aucun filtre ; un Host mal formé reste rejeté en 400. En dev et dans le job E2E de la CI, elle est surchargée par une regex littérale — cf. Les trois déclarations de SERVER_NAME. Si vous la définissez en production, la regex doit couvrir le domaine applicatif, l'hôte interne php (endpoint ask de l'on-demand TLS) et chaque domaine de site mappé en base : un Host non couvert est rejeté en 400 avant toute résolution Host → Site. Ce qui protège en son absence : Pourquoi TRUSTED_HOSTS n'est pas le filtre des Host en production.
DEFAULT_URI https://localhost URI de base des URL générées hors requête HTTP (commandes Symfony Console, worker Messenger), lue par framework.router.default_uri: '%env(DEFAULT_URI)%' (config/packages/routing.yaml). C'est elle qui fait le lien de réinitialisation du mot de passe : l'e-mail est rendu par le worker (url() dans templates/reset_password/email.html.twig). Résolue à l'exécution : un changement s'applique au redémarrage du process, sans rebuild d'image. Obligatoire en production (cf. Variables d'exécution obligatoires) ; son hôte doit figurer dans KIREXO_RESERVED_DOMAINS, sinon le lien aboutit sur un 404.

FrankenPHP / Caddy

Variable Défaut Rôle
SERVER_NAME localhost (compose.yaml y ajoute , php:80) Adresses du vhost unique déclaré par frankenphp/Caddyfile ({$SERVER_NAME:localhost} { … }) : les noms que le Caddy embarqué sert, et ceux pour lesquels il émet un certificat. Liste séparée par des virgules, lue au démarrage du conteneur — un changement suppose de recréer le service php, pas de le redémarrer. La valeur diffère selon le contexte : cf. Les trois déclarations de SERVER_NAME. Servir un nom ne suffit pas à le rendre joignable : là où TRUSTED_HOSTS est défini (dev, CI), Symfony rejette un nom qu'il ne couvre pas — les deux s'y déclarent ensemble.
CADDY_MERCURE_JWT_SECRET !ChangeThisMercureHubJWTSecretKey! Secret utilisé pour signer et vérifier les JWT Mercure (SSE). En dev, la valeur par défaut est suffisante — À surcharger en prod par une valeur aléatoire forte. Dérive les variables MERCURE_PUBLISHER_JWT_KEY et MERCURE_SUBSCRIBER_JWT_KEY exposées au conteneur.
KIREXO_ONDEMAND_TLS_ENABLED 0 Manette d'activation de l'on-demand TLS Caddy (émission d'un certificat à la volée pour un domaine mappé à un Site ou réservé à l'application par KIREXO_RESERVED_DOMAINS). 0 = désactivé (défaut : dev, worktrees, déploiement derrière Traefik). 1 = mode Caddy-standalone. Lue aussi côté Symfony par WebPluginTlsAskController (l'endpoint ask reste inerte, 403, tant que le flag vaut 0). Cf. Servir les domaines de site en HTTPS.
CADDY_ONDEMAND_TLS_GLOBAL (vide) Bloc de directive Caddy injecté dans le bloc global du frankenphp/Caddyfile. Vide = inerte (aucune régression). En mode Caddy-standalone, à renseigner avec on_demand_tls { ask http://php/.well-known/kirexo/on-demand-tls }.
CADDY_ONDEMAND_TLS_SITE (vide) Bloc de directive Caddy injecté dans le vhost du frankenphp/Caddyfile. Vide = inerte. En mode Caddy-standalone, à renseigner avec tls { on_demand } pour activer l'émission on-demand sur ce vhost.

Les trois déclarations de SERVER_NAME

Trois fichiers déclarent cette variable, et aucun lien de code ne les unit. Chacun fait foi dans son contexte :

Contexte Où Valeur
Dev — toutes les piles Compose (dépôt principal, worktree, profil full) compose.override.yaml, service php — valeur littérale, jamais interpolée localhost, *.localhost, *.demo.localhost, php:80, :8080
CI — tests E2E .gitlab-ci.yml, template .php_e2e_job localhost, *.localhost, *.demo.localhost — ni php:80 ni :8080 : la CI lance frankenphp run sans Compose et sans proxy hôte
Prod environnement du serveur, cf. À surcharger obligatoirement en production un seul nom d'hôte, ex. kirexo.app

En dev, la liste est écrite en dur : compose.override.yaml ne l'interpole pas. Exporter SERVER_NAME dans le shell, ou la poser dans .env ou .env.local, n'a donc aucun effet sur la stack de développement — c'est le fichier qu'il faut éditer, puis recréer le service php. Le repli ${SERVER_NAME:-localhost} de compose.yaml n'est atteint que là où l'override n'est pas chargé, c'est-à-dire en production.

En production, la même valeur est consommée deux fois, sous deux formes : compose.yaml la donne au conteneur suffixée de , php:80 (le vhost interne en clair dont dépend MERCURE_URL), tandis que compose.prod.yaml l'interpole brute dans deux labels Traefik Host(...). D'où la contrainte : un seul nom d'hôte, sans virgule ni joker — une liste produirait une règle Traefik qui ne matche rien.

TRUSTED_HOSTS ne suit que dans les deux premiers cas. En dev comme dans le job E2E de la CI, il est déclaré juste à côté, avec la même portée (^(.+\.)?localhost$|^127\.0\.0\.1$). En production, il n'est pas dérivé de SERVER_NAME : compose.yaml et compose.prod.yaml le laissent vide (${TRUSTED_HOSTS:-}), donc sans filtre. Une regex limitée à SERVER_NAME rejetterait en 400 les domaines de site, mappés en base et inconnus de la configuration ; elle ne vaudrait rien non plus dès que SERVER_NAME porte une liste (^a, b$ n'est pas une alternance).

*.demo.localhost : un joker Caddy ne couvre qu'un label

*.localhost matche demo.localhost, mais pas app.demo.localhost — le domaine du site de démonstration (SiteFixtures::DEMO_HOST, src/DataFixtures/SiteFixtures.php), qui compte deux labels sous .localhost depuis son renommage. Sans l'entrée *.demo.localhost, Caddy n'émet aucun certificat pour ce nom et les tests E2E Panther du site public échouent en ERR_SSL_PROTOCOL_ERROR — mesuré, en local comme en CI. Le TLS tombant avant la première requête HTTP, il n'y a ni log applicatif ni trace Sentry : rien qu'un navigateur qui refuse d'ouvrir la page.

Le nombre de labels est ce qui rend le certificat valide, pas une convention d'écriture : Pourquoi tout nom servi a au moins deux labels.

Corollaire opposable : toute déclaration de SERVER_NAME servant un domaine de site doit couvrir SiteFixtures::DEMO_HOST. Les piles Compose du dépôt et le .php_e2e_job sont comparés à la constante par tests/Unit/Infra/DemoHostConsistencyTest.php — une copie ajoutée ailleurs (nouveau job CI, nouveau fichier Compose) n'est gardée par rien tant qu'elle n'y est pas déclarée.

:8080 — l'adresse sans nom d'hôte, pour le proxy hôte

En développement, le proxy Caddy hôte ne parle pas HTTPS à FrankenPHP : il vise php-<worktree>:8080, en HTTP clair. Une adresse Caddy sans nom d'hôte matche n'importe quel Host et n'est pas éligible à l'HTTPS automatique — aucune redirection 308 n'y est donc installée, et le proxy ne boucle pas sur lui-même.

Le motif du HTTP clair est distinct : depuis Caddy 2.11, reverse_proxy vers un upstream https:// réécrit l'en-tête Host avec l'adresse de l'upstream. Symfony recevrait Host: php-ticket-185, ce qui casserait le multi-tenant et les URLs générées, et serait rejeté par TRUSTED_HOSTS. Sur un bridge internal, le chiffrement n'apporte rien en contrepartie.

localhost, *.localhost sont conservés dans la liste : les tests E2E visent https://localhost depuis l'intérieur du conteneur. Le rendu du site de démonstration, lui, ne s'appuie pas sur eux — app.demo.localhost n'est pas couvert par le joker *.localhost et relève de l'entrée *.demo.localhost. Raisonnement complet : Pourquoi le proxy parle en clair au FrankenPHP.

Multi-tenant (résolution de domaine)

Variable Défaut Rôle
KIREXO_RESERVED_DOMAINS localhost,127.0.0.1,app.main.localhost,local.localhost — valeur portée par .env, bloc ###> kirexo/multi-tenant ###, qui en est la source de vérité Liste (séparée par des virgules) des domaines réservés à l'application : ceux qui conservent le routage app_* normal et ne sont jamais servis comme site public d'un utilisateur. Lue à l'exécution par la résolution Host → Site. En prod, obligatoire (cf. Variables d'exécution obligatoires) : y placer le ou les domaines de l'application, dont l'hôte de DEFAULT_URI. Ne pas y lister de domaine de site utilisateur (ceux-là sont résolus dynamiquement en base). En dev multi-worktree, la valeur est dérivée de l'identifiant du worktree : cf. Variables de worktree.

Pourquoi app.main.localhost figure dans le défaut

En dev, le dépôt principal est servi par le proxy hôte sur https://app.main.localhost (et https://localhost y redirige en 308). Un domaine absent de cette liste est traité comme un domaine de site public : HostResolutionSubscriber (src/Plugin/Web/src/EventSubscriber/HostResolutionSubscriber.php) ne trouve aucun Site correspondant et rend 404 sur toute l'application, /login compris. Le proxy, lui, répondrait parfaitement — d'où un diagnostic qui accuse l'application plutôt que le routage.

La comparaison est une égalité exacte après normalisation (minuscules, port retiré) dans SiteResolver::isAppDomain() (src/Plugin/Web/src/Service/SiteResolver.php), jamais une correspondance de suffixe : une entrée ne couvre aucun de ses sous-domaines, et réciproquement. Chaque nom applicatif servi doit donc y figurer en toutes lettres.

local.localhost est une entrée pour les signets, pas pour une fenêtre de migration

La quatrième entrée du défaut, local.localhost, est l'ancienne adresse du dépôt principal — celle qui était réellement servie avant le renommage des URLs de développement. Elle n'a rien à voir avec app.main.localhost. Ce nom n'a plus de bloc de site : il retombe sous le joker *.localhost du repli, qui l'envoie au worktree par défaut. Quand ce défaut est le dépôt principal, sa présence dans la liste fait répondre l'application au lieu de rendre 404 — c'est tout ce qu'elle achète, et un signet resté sur l'ancienne URL est le seul cas où elle sert.

Il n'existe pas de fenêtre « conteneur déjà migré, proxy pas encore » qu'elle couvrirait : KIREXO_RESERVED_DOMAINS et l'alias réseau php-${WT:-main} viennent de la même création de conteneur — un changement d'environnement force la recréation, et l'alias bascule dans la même opération, l'un ne peut donc pas passer sans l'autre. Dans la fenêtre réelle, c'est l'ancien 01-main.caddy qui route local.localhost vers php-local, alias que plus aucun conteneur ne porte : 502, et la liste réservée n'y joue aucun rôle.

Y écrire main.localhost à la place ne couvrirait rien : ce nom n'a jamais été servi. Le raisonnement complet est en commentaire dans .env, au-dessus de la variable. L'ordre des gestes à jouer sur un poste existant est en Migrer un poste existant vers les URLs app. ; une fois les signets à jour, cette entrée peut disparaître.

La valeur qui fait foi est celle de .env, pas le repli de compose.override.yaml

compose.override.yaml répète la même liste sous la forme ${KIREXO_RESERVED_DOMAINS:-…}, mais cette branche de repli n'est jamais évaluée dans le dépôt principal : Compose charge .env automatiquement pour l'interpolation, la variable y est donc déjà définie. Une modification écrite dans le seul défaut :- n'aurait aucun effet observable.

Une valeur explicite — celle de .env, ou celle du .env.worktree d'un worktree — remplace la liste intégralement : elle n'est jamais fusionnée avec le défaut.

Un domaine de site ne s'y met jamais

app.demo.localhost — et plus généralement tout domaine mappé à un Site — ne doit jamais figurer dans cette liste. L'y ajouter ferait disparaître le site derrière le routage applicatif : la panne est symétrique du 404 décrit plus haut, et tout aussi silencieuse. L'asymétrie est voulue : app.main.localhost est l'application, app.demo.localhost est un site.

Résolution dynamique des domaines de site

Les domaines des sites publics ne figurent pas dans cette variable : ils sont inconnus à l'avance et résolus à l'exécution à partir de la base. Le raisonnement complet (aiguillage prioritaire, double isolation, état passif du domaine) est décrit dans Multi-tenant : résolution d'un domaine vers un site, et le routage correspondant côté proxy dans Les domaines de site publics et le worktree par défaut.

Mercure (sync temps réel)

Le hub Mercure est embarqué dans FrankenPHP (module Caddy natif mercure, déclaré dans frankenphp/Caddyfile) : aucun service Docker dédié. Il diffuse les événements SSE consommés par le navigateur (config/packages/mercure.yaml, hub default).

Variable Défaut Rôle
MERCURE_URL http://php/.well-known/mercure URL interne (app → hub). Lue par le bundle Mercure côté Symfony pour publier les updates sur le hub embarqué (url: dans config/packages/mercure.yaml). Vise le vhost HTTP interne en clair (php:80, déclaré dans SERVER_NAME du frankenphp/Caddyfile) : passer par https://localhost ferait échouer le client HTTP du conteneur sur le certificat auto-signé de Caddy (« SSL certificate problem ») et l'autosave tomberait en 500.
MERCURE_PUBLIC_URL https://localhost/.well-known/mercure URL publique exposée au navigateur. Sert d'endpoint EventSource au JavaScript pour s'abonner aux updates (public_url: dans config/packages/mercure.yaml). Obligatoire en production (cf. Variables d'exécution obligatoires).

Pourquoi deux variables (interne vs public)

L'application publie sur le hub par un chemin réseau (MERCURE_URL), tandis que le navigateur s'abonne par un autre (MERCURE_PUBLIC_URL). Les deux divergent dès le développement : l'interne emprunte le réseau Docker en clair (http://php/.well-known/mercure, vhost HTTP php:80 sans TLS ni redirection) alors que la publique est l'URL externe en https (https://localhost/.well-known/mercure en dev, le domaine en prod, ex. https://kirexo.app/.well-known/mercure). Une seule URL pour les deux usages casserait soit la publication serveur (échec TLS sur le certificat auto-signé), soit l'abonnement navigateur.

Le secret JWT n'est pas dans .env

MERCURE_URL et MERCURE_PUBLIC_URL sont des valeurs non secrètes (versionnées dans .env). Le secret de signature des JWT Mercure n'y figure pas : il vit dans CADDY_MERCURE_JWT_SECRET (injecté par compose.yaml). Cette unique valeur est dérivée en MERCURE_PUBLISHER_JWT_KEY et MERCURE_SUBSCRIBER_JWT_KEY, réutilisées à la fois :

  • par la directive mercure { … } du frankenphp/Caddyfile (le hub, via {env.MERCURE_PUBLISHER_JWT_KEY} / {env.MERCURE_SUBSCRIBER_JWT_KEY}) ;
  • par le bundle Symfony (config/packages/mercure.yaml, secret: '%env(MERCURE_PUBLISHER_JWT_KEY)%').

Hub et publisher signent ainsi avec la même clé. N'introduisez pas de variable MERCURE_JWT_SECRET parallèle : la vérification JWT échouerait. À surcharger en prod par une valeur aléatoire forte (via CADDY_MERCURE_JWT_SECRET).

Doctrine / PostgreSQL

Variable Défaut Rôle
POSTGRES_DB app Nom de la base.
POSTGRES_USER app Utilisateur PostgreSQL.
POSTGRES_PASSWORD !ChangeMe! Mot de passe PostgreSQL. À surcharger en prod.
POSTGRES_VERSION 18 Version majeure de PostgreSQL : tag de l'image du service database (postgres:${POSTGRES_VERSION:-18}-alpine) et serverVersion du DSN. Fixée dans .env, que Compose lit pour l'interpolation. La changer exige un nouveau volume de données (PostgreSQL refuse les données d'une autre majeure).
DATABASE_URL postgresql://app:!ChangeMe!@database:5432/app?serverVersion=18&charset=utf8 DSN Doctrine complet. Recomposé à partir des variables ci-dessus.
RUN_MIGRATIONS 0 dans compose.yaml, 1 dans compose.prod.yaml — absente de .env à dessein Joue ou non les migrations Doctrine au démarrage du serveur applicatif. Détail ci-dessous.

RUN_MIGRATIONS

Manette lue par l'entrypoint shell du conteneur php (frankenphp/docker-entrypoint.sh, copié dans l'image en /usr/local/bin/docker-entrypoint). Symfony ne la lit jamais.

Propriété Valeur
Défaut hors production 0, porté par compose.yaml : RUN_MIGRATIONS: ${RUN_MIGRATIONS:-0}.
Défaut en production 1, porté par compose.prod.yaml : RUN_MIGRATIONS: ${RUN_MIGRATIONS:-1}. Compose fusionne les blocs environment du service php ; la valeur de compose.prod.yaml l'emporte.
Valeurs acceptées 0 (migrations non jouées) et 1 (migrations jouées). Non définie ou vide équivaut à 0.
Valeur invalide Toute autre valeur (true, yes, 2, 1 avec une espace…) est refusée : pas de migration, serveur non démarré (voir État d'attente).
Portée La seule commande frankenphp run, c'est-à-dire le CMD de l'image (frankenphp run --config /etc/caddy/Caddyfile). php …, bin/console … (worker Messenger, commandes ponctuelles via docker compose run/exec), frankenphp php-cli … et toute autre commande ne migrent jamais, même avec 1. Le service worker de compose.prod.yaml pose en plus RUN_MIGRATIONS: "0" dans son propre environnement.
Commande jouée php bin/console doctrine:migrations:migrate --no-interaction --allow-no-migration --all-or-nothing, sortie non masquée (visible dans docker compose logs php).
Moment Après l'attente de la base (dbal:run-sql "SELECT 1", 60 essais), avant le lancement de FrankenPHP. Le healthcheck (curl -f http://localhost:2019/metrics) ne peut donc passer au vert qu'une fois les migrations appliquées.
Schéma déjà à jour No-op : Doctrine rend 0, le serveur démarre normalement.

Sans effet sur la stack de développement

En développement, compose.override.yaml remplace la commande du service php par /app/infra/supervisor/supervisor.sh start all. L'entrypoint ne voit pas frankenphp run et ne migre jamais, quelle que soit la valeur de RUN_MIGRATIONS. Les migrations s'y appliquent à la main : castor doctrine:migrate.

Messages de l'entrypoint

Préfixe stable [kirexo].

Situation Flux Message
RUN_MIGRATIONS vaut 0, vide ou non définie stdout [kirexo] RUN_MIGRATIONS=0 : migrations non jouées au démarrage.
RUN_MIGRATIONS=1, avant la migration stdout [kirexo] RUN_MIGRATIONS=1 : application des migrations Doctrine...
Migration réussie stdout [kirexo] Migrations Doctrine à jour.
Migration en échec stderr [kirexo] ERREUR : échec des migrations Doctrine (code <N>). — <N> est le code de sortie de doctrine:migrations:migrate.
Valeur invalide stderr [kirexo] ERREUR : valeur invalide RUN_MIGRATIONS=<valeur> (attendu : 0 ou 1).

Les deux messages d'erreur sont suivis des trois mêmes lignes, sur stderr, où <conteneur> est l'identifiant court du conteneur ($HOSTNAME) :

[kirexo] Le serveur n'est PAS démarré : le conteneur reste en vie, état de santé rouge, sans redémarrage en boucle.
[kirexo] Corriger la cause (sortie ci-dessus), puis rejouer : docker exec -it <conteneur> bin/console doctrine:migrations:migrate
[kirexo] et redémarrer ce conteneur : docker restart <conteneur>

Ces lignes de reprise sont génériques

Elles sont identiques pour les deux causes. Sur une valeur invalide, rejouer migrate puis docker restart ne corrige rien : le redémarrage relit la même valeur et retombe dans le même état. Il faut d'abord corriger RUN_MIGRATIONS dans l'environnement de l'hôte, puis recréer le conteneur (docker compose … up -d), un restart ne relisant pas l'environnement. Procédure : Le conteneur php reste unhealthy après une mise à jour.

État d'attente : conteneur en vie, unhealthy

Sur un échec de migration ou une valeur invalide, l'entrypoint ne sort pas :

  • FrankenPHP n'est pas lancé ; l'endpoint admin Caddy :2019 ne répond jamais et le healthcheck échoue.
  • Le processus reste vivant : la politique restart: always de compose.prod.yaml ne relance rien, il n'y a pas de boucle de redémarrage.
  • SIGTERM et SIGINT (docker stop, docker compose down) sont honorés immédiatement ; le processus sort en code 143.
  • docker exec reste possible dans le conteneur, ce qui permet de lancer la migration à la main une fois la cause corrigée.

Le service php affiche starting pendant le délai de grâce du healthcheck, puis unhealthy. compose.prod.yaml porte ce délai à 5 minutes pour laisser le temps à une migration longue ; les autres paramètres restent ceux de compose.yaml :

Paramètre du healthcheck compose.yaml Pile compose.yaml + compose.prod.yaml
test curl -f http://localhost:2019/metrics inchangé
start_period 60s 300s
interval / timeout / retries 10s / 5s / 5 inchangés

Un premier succès de la sonde pendant ce délai rend le service sain aussitôt : un démarrage sans migration n'attend pas plus longtemps.

Base injoignable : comportement distinct

Si la base ne répond pas après les 60 essais de l'attente initiale, l'entrypoint sort en code 1, avant toute migration. Sous restart: always, le conteneur est alors relancé : ce cas couvre une panne transitoire de la base, pas une migration cassée.

Ne pas définir RUN_MIGRATIONS dans .env

Docker Compose lit .env pour l'interpolation des fichiers Compose. Une ligne active RUN_MIGRATIONS=… y rendrait la variable définie : le défaut ${RUN_MIGRATIONS:-1} de compose.prod.yaml ne serait jamais évalué, et une production déployée depuis le dépôt cloné ne migrerait plus (avec 0) ou refuserait de démarrer (avec une valeur invalide). .env ne porte donc qu'une ligne commentée #RUN_MIGRATIONS=, dans le bloc ###> kirexo/migrations ###. Pour surcharger, exporter la variable dans l'environnement de l'hôte.

Les raisons de ce fonctionnement sont développées dans Pourquoi les migrations sont jouées au démarrage du seul service applicatif.

Messenger / RabbitMQ

Variable Défaut Rôle
RABBITMQ_USER guest Utilisateur RabbitMQ.
RABBITMQ_PASSWORD guest Mot de passe RabbitMQ. À surcharger en prod.
MESSENGER_TRANSPORT_DSN amqp://guest:guest@rabbitmq:5672/%2f/messages DSN du transport Messenger principal (bus de commandes async).
MESSENGER_TRANSPORT_PLUGIN_WEB_DSN amqp://guest:guest@rabbitmq:5672/%2f/plugin_web DSN du transport Messenger dédié au plugin web (isolation d'échec par plugin). Défaultée par le bundle KirexoPluginWebBundle (prependExtension), qui déclare aussi le transport lui-même et le route sur sync:// en environnement de test — décision prise sur kernel.environment, pas dans un bloc when@test du cœur. À surcharger en prod avec les credentials RabbitMQ réels. Surface de configuration côté bundle : Configuration du plugin web.

Variables déclarées par les plugins

MESSENGER_TRANSPORT_PLUGIN_WEB_DSN est déclarée par le plugin web, pas par le cœur. Sa source de vérité est le manifeste ENV_VARS du bundle, transcrit dans Configuration du plugin web ; la ligne ci-dessus la reprend sous l'angle exploitation / déploiement.

Worker Messenger

Deux variables règlent le worker qui consomme les transports. Symfony n'en lit aucune.

Variable Défaut Lue par Rôle
KIREXO_WORKER_TRANSPORTS scheduler_default plugin_web async Dev : supervisor_command messenger (infra/supervisor/supervisor.lib.sh), dans l'environnement du conteneur php. Prod : interpolation Compose de la command du service worker (compose.prod.yaml). Transports consommés par messenger:consume, séparés par des espaces. Chaque mot devient un argument. scheduler_default est placé en tête : messenger:consume sert ses transports par ordre de priorité. Ne jamais y mettre failed : le worker rejouerait en boucle les messages en échec. Une liste sans scheduler_default désactive les tâches périodiques, dont la purge de la corbeille.
KIREXO_WORKER_REPLICAS 1 Prod uniquement : interpolation Compose de scale sur le service worker (compose.prod.yaml). Nombre d'instances du worker. Au-delà de 1, les files RabbitMQ sont partagées entre les instances, et une seule instance déclenche les tâches périodiques grâce au verrou du schedule default (cf. LOCK_DSN). docker compose up -d --scale worker=N la surcharge ponctuellement.

Les défauts de développement et de production sont identiques. Un test de cohérence, sous tests/Unit/Infra/, compare le défaut de compose.prod.yaml à celui de supervisor.lib.sh.

Ligne de commande complète du worker, commune aux deux environnements :

php bin/console messenger:consume ${KIREXO_WORKER_TRANSPORTS:-scheduler_default plugin_web async} --time-limit=3600 --memory-limit=192M -vv

Dans compose.prod.yaml, la command est écrite sous forme de chaîne, pas de liste : Compose interpole la variable, puis découpe la chaîne en arguments. Sous forme de liste, "${KIREXO_WORKER_TRANSPORTS}" passerait scheduler_default plugin_web async comme un seul nom de transport.

Aucun fichier Compose de développement ne transmet KIREXO_WORKER_TRANSPORTS

En développement, la variable est lue dans l'environnement du conteneur php, et ni compose.override.yaml ni .env.worktree ne la déclarent. L'exporter dans le shell de l'hôte n'a donc aucun effet : le défaut s'applique. Un changement du défaut dans supervisor.lib.sh n'est pris en compte qu'au redémarrage du conteneur php (docker compose restart php, côté hôte) : la boucle de supervision a lu la lib à son démarrage, et castor supervisor:worker-restart ne suffit pas.

Ne pas les définir dans .env

Les deux variables sont volontairement absentes de .env, pour la même raison que RUN_MIGRATIONS. Docker Compose lit .env pour l'interpolation : une ligne active y rendrait la variable définie, et le défaut :- de compose.prod.yaml ne serait jamais évalué. Une production déployée depuis le dépôt cloné hériterait alors de la valeur de développement. Pour surcharger en production, exporter la variable dans l'environnement de l'hôte.

Exploitation (logs, mise à l'échelle, arrêt) : Déployer Kirexo en production — le worker Messenger. Raisons de ce découpage : Pourquoi un worker Messenger dédié et un verrou sur le planificateur.

Redis

Variable Défaut Rôle
REDIS_URL redis://redis:6379 URL de connexion Redis. Utilisée par : le pool de cache applicatif (config/packages/cache.yaml), le handler de session HTTP (config/packages/framework.yaml) et — par défaut en dev — le store de verrouillage Symfony Lock (cf. LOCK_DSN).

Typesense

Variable Défaut Rôle
TYPESENSE_HOST typesense Hôte du moteur de recherche Typesense.
TYPESENSE_PORT 8108 Port Typesense.
TYPESENSE_API_KEY xyz-dev-key Clé API Typesense. À surcharger en prod.

Gotenberg

Variable Défaut Rôle
GOTENBERG_URL http://gotenberg:3000 URL du service Gotenberg (génération PDF).

Mailer

Variable Défaut Rôle
MAILER_DSN smtp://mailer-int:1025 DSN du mailer Symfony. En dev, pointe sur Mailpit via son alias applicatif mailer-int (aucun mail ne sort de la machine). En test, .env.test force null://null ; en prod, obligatoire, injectée par compose.prod.yaml (cf. Variables d'exécution obligatoires).
MAILER_FROM_ADDRESS noreply@kirexo.local Adresse d'expéditeur des emails transactionnels (ex. email de réinitialisation de mot de passe, cf. Réinitialiser son mot de passe). MAIL_FROM en est dérivé. En prod, obligatoire : une adresse réelle du domaine émetteur, cohérente avec les enregistrements SPF/DKIM pour éviter le classement en spam. MAIL_FROM n'est pas injecté, cf. Variables d'exécution obligatoires.

mailer-int et non le nom de service nu mailer

En dev, le conteneur Mailpit est attaché à deux réseaux : celui de la stack et celui du proxy hôte. Docker répond à une résolution de nom par toutes les adresses partagées entre demandeur et cible — le nom nu mailer rendrait donc deux enregistrements A, et un envoi SMTP sur deux partirait vers le réseau du proxy, où la règle de cloisonnement le jette. Symptôme : des e-mails perdus par intermittence, sans trace.

mailer-int est l'alias déclaré sur le seul réseau applicatif (compose.override.yaml, service mailer, forme mapping). La règle vaut pour tout service multi-réseaux : Un service sur deux réseaux rend deux adresses. Réception et diagnostic : Recevoir les e-mails en développement.

Symfony Lock

Variable Défaut Rôle
LOCK_DSN redis://redis:6379 DSN du store de verrouillage distribué. Redis est utilisé par défaut pour que les verrous soient partagés entre le serveur web FrankenPHP et les workers Messenger — flock (lock fichier système) ne fonctionnerait qu'au sein d'un seul processus / filesystem. En prod multi-instance, le même DSN convient ; pour une dépendance moindre on peut basculer sur postgresql+advisory://…. Porte aussi le verrou kirexo_scheduler_default du schedule default : toutes les instances du worker doivent viser le même store, sinon chacune déclencherait les tâches périodiques (cf. app:articles:purge-trashed). En dev, suffixé par REDIS_DB_INDEX (compose.override.yaml) : un verrou par worktree.

Observabilité

Variable Défaut Rôle
SENTRY_DSN (vide) DSN Sentry. Vide en dev, injecté en prod.
GRAYLOG_HOST (vide) Hôte Graylog pour les logs GELF/UDP. Vide en dev — aucun service Graylog local n'est démarré. En prod, pointer vers votre instance Graylog.
GRAYLOG_PORT 12201 Port Graylog (GELF UDP).

Graylog — prod uniquement

L'envoi vers Graylog n'est déclaré que sous when@prod (voir config/packages/monolog.yaml). En dev, les logs partent uniquement dans les fichiers Monolog / la console Symfony.

En prod, deux handlers portent l'envoi :

Handler Type Rôle
graylog whatfailuregroup, members: [graylog_gelf], channels: ["!event"] Attaché au logger. Absorbe toute exception levée par son membre.
graylog_gelf gelf, nested: true, level: warning Envoie en GELF/UDP vers GRAYLOG_HOST:GRAYLOG_PORT. Attaché au seul groupe graylog, jamais directement au logger.

GRAYLOG_HOST vide : les handlers restent déclarés, il n'y a pas d'activation conditionnelle. Le transport vise alors localhost:GRAYLOG_PORT et l'envoi échoue.

Échec d'envoi (GRAYLOG_HOST vide, Graylog injoignable, socket refusé) : l'exception du transport est absorbée par whatfailuregroup. Le log est perdu pour Graylog ; la requête ou la commande en cours continue. Un log perdu ne fait jamais tomber une requête.

Coût : chaque log de niveau warning ou plus déclenche une tentative d'envoi UDP, y compris quand GRAYLOG_HOST est vide.

Indépendamment de Graylog, le handler main (fingers_crossed, déclenché à error) vide son tampon vers nested, qui écrit sur php://stderr.

Le handler requiert le package PHP graylog2/gelf-php :

castor composer "require graylog2/gelf-php:^2.0"

Chiffrement de la clé API Claude

La clé API Claude (utilisée pour l'analyse IA des articles côté admin) est stockée chiffrée en base. Le chiffrement est assuré par le service App\Service\Security\ClaudeApiKeyCipher (src/Service/Security/ClaudeApiKeyCipher.php), qui s'appuie sur une clé symétrique : CLAUDE_API_KEY_CIPHER_KEY.

Variable Origine Rôle
CLAUDE_API_KEY_CIPHER_KEY Dev : vault config/secrets/dev/ · Test : .env.test (valeur fixe) · Prod : variable d'environnement du serveur, injectée obligatoirement par compose.prod.yaml Clé de chiffrement symétrique (libsodium sodium_crypto_secretbox) de la clé API Claude. Format : base64 de 32 octets aléatoires (SODIUM_CRYPTO_SECRETBOX_KEYBYTES). Injectée dans le cipher via #[Autowire(env: 'base64:CLAUDE_API_KEY_CIPHER_KEY')], qui décode le base64 en 32 octets bruts au boot.

Secret — jamais committé en clair, jamais dans .env

Cette variable est un secret. Elle n'est pas définie dans .env.

  • Ne PAS la définir dans .env, pour deux raisons. En dev, une valeur (même vide) dans .env masquerait le vault à l'exécution (l'environnement du process et .env ont priorité sur le secret déchiffré). En prod, Compose lit .env pour l'interpolation de compose.prod.yaml : une valeur versionnée y satisferait silencieusement la déclaration obligatoire. Elle est donc absente de .env à dessein.
  • Dev : le secret est déclaré dans config/secrets/dev/ et committé sous forme chiffrée (illisible sans la clé privée du dossier).
  • Prod : aucun coffre Symfony Secrets, par choix — cohérent avec l'absence volontaire de dump-env prod dans le Dockerfile. La clé est injectée comme APP_SECRET, par une variable d'environnement du serveur que compose.prod.yaml déclare obligatoire :

    CLAUDE_API_KEY_CIPHER_KEY: "${CLAUDE_API_KEY_CIPHER_KEY:?CLAUDE_API_KEY_CIPHER_KEY manquante ou vide : …}"
    

    Génération : openssl rand -base64 32 ou php -r 'echo base64_encode(random_bytes(32));'. Sans la variable (absente ou vide), toute commande docker compose -f compose.yaml -f compose.prod.yaml … échoue avec le message CLAUDE_API_KEY_CIPHER_KEY manquante ou vide : …, au lieu d'un 500 sur /admin/reglages.

  • Rotation : changer la valeur rend illisible la clé API Claude déjà stockée en base ; elle est à ressaisir dans /admin/reglages.

  • Aucune valeur en clair n'est versionnée, conformément à la règle absolue sur les secrets (cf. l'avertissement « Gestion des secrets » en tête de page).

Valeur de test fixe en .env.test

.env.test définit une valeur fixe et non secrète (CLAUDE_API_KEY_CIPHER_KEY=AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA=, soit 32 octets nuls en base64) pour que le cipher s'instancie pendant la suite de tests. Cette valeur n'a aucune portée hors environnement de test : elle ne protège aucune clé réelle et n'est jamais utilisée en dev ou prod.

ANTHROPIC_API_KEY n'est PAS la clé API réelle

.env déclare une variable ANTHROPIC_API_KEY (vide par défaut). C'est un placeholder attendu par le schéma de configuration du bundle symfony/ai (config/packages/ai.yaml) au démarrage du conteneur — il n'est pas utilisé pour l'analyse en pratique. La vraie clé API Claude n'est jamais lue depuis l'environnement : elle est saisie via l'admin (Réglages), chiffrée (cf. CLAUDE_API_KEY_CIPHER_KEY ci-dessus) et déchiffrée à la volée au moment de l'appel à Claude. Ne définissez donc aucun secret dans ANTHROPIC_API_KEY : laissez-la vide. La saisie de la vraie clé est décrite dans Configurer la clé API Claude pour l'analyse IA.

Variable Défaut Rôle
ANTHROPIC_API_KEY (vide) Placeholder de configuration du bundle symfony/ai. Non utilisé pour l'analyse — laisser vide, ne jamais y mettre de secret. La clé API réelle est saisie chiffrée via l'admin (voir ci-dessous).

La procédure de fourniture de la clé de chiffrement (vault en dev, variable d'environnement en prod) puis de saisie de la clé API est décrite dans Configurer la clé API Claude pour l'analyse IA. Le déclenchement et la lecture du rapport d'analyse sont décrits dans Analyser un article avec l'IA (Claude).

Image de production et préfixe de registry

Ces deux variables pilotent quelle image Docker la production tire du registry. Elles ne vivent pas dans .env : en production, on les exporte dans le shell (ou un gestionnaire de secrets/config) avant docker compose pull && up.

Les services php et worker de compose.prod.yaml ne buildent pas l'image sur le serveur : ils PULL une image immuable publiée par la CI (index assemblé par le job docker:manifest-prod : linux/amd64 + linux/arm64, ou linux/amd64 seul pour une release dont la note de release contient une section « Architecture » — un hôte arm64 vérifie cette note avant d'épingler la version ; cf. Pipeline GitLab CI). Les deux partagent la même référence d'image (ancre x-kirexo-prod-image), donc toujours la même version :

${IMAGES_PREFIX:-registry.gitlab.com/shaurifr/kirexo/}kirexo-prod:${KIREXO_VERSION:-latest}
Variable Défaut dans compose.yaml Défaut dans compose.prod.yaml Rôle
IMAGES_PREFIX (vide) registry.gitlab.com/shaurifr/kirexo/ Préfixe du nom de l'image Docker. En dev (compose.yaml), il préfixe kirexo-app (vide par défaut → image locale non poussée). En prod (compose.prod.yaml), il pointe le registry du projet devant kirexo-prod.
KIREXO_VERSION — latest Tag de l'image kirexo-prod à déployer. Épingle une release précise : le tag Git de version sémantique MAJEUR.MINEUR.CORRECTIF (ex. 0.0.1, sans préfixe v), que la CI pousse aussi comme tag d'image.

IMAGES_PREFIX doit finir par / si vous le définissez manuellement

Le préfixe est concaténé directement au nom de l'image (${IMAGES_PREFIX}kirexo-prod). S'il ne se termine pas par une barre oblique, le préfixe se colle au nom : registry.gitlab.com/shaurifr/kirexokirexo-prod. Le défaut prod (registry.gitlab.com/shaurifr/kirexo/) inclut déjà le / final — ne le redéfinissez que si vous poussez vers un autre registry, en conservant le / terminal.

Toujours exporter KIREXO_VERSION en production

Le défaut latest est un tag mutable : il est réécrit à chaque release. Si le serveur de prod ne définit pas KIREXO_VERSION, un docker compose pull ramène la dernière image publiée — vous perdez la possibilité de rejouer une version précise ou de revenir en arrière de façon déterministe.

Le déploiement DOIT donc exporter KIREXO_VERSION=<version> (un tag Git de version sémantique, ex. KIREXO_VERSION=0.0.1) avant docker compose pull && up, pour épingler exactement l'image testée par la CI et garder un rollback propre. La procédure complète est décrite dans Déployer Kirexo en production.

Variables Docker Compose (dev uniquement)

Le fichier compose.override.yaml exposait des variables pour surcharger les ports publiés côté hôte. Ces variables n'ont plus de consommateur : la stack de développement ne publie plus aucun port, tout passe par le proxy Caddy hôte. Elles sont conservées dans .env / .env.local.dist — elles n'y font aucun mal — mais les définir n'a plus aucun effet.

Modèle .env.local.dist

Un modèle versionné .env.local.dist à la racine du dépôt regroupe les variables surchargeables (ports Compose, USER_ID/GROUP_ID du build, Xdebug, observabilité). Pour démarrer : cp .env.local.dist .env.local puis décommentez uniquement les lignes que vous voulez surcharger. La liste exhaustive et le rôle de chaque variable restent documentés ci-dessous.

Attention : .env.local n'agit que sur les variables lues par Symfony. Celles qui sont interprétées par Docker Compose (ports, USER_ID/GROUP_ID, TZ, Xdebug, worktree) y sont listées à titre de référence et n'y ont aucun effet : elles se surchargent dans .env ou dans l'environnement du shell — TZ exceptée, qui ne se pose que dans le shell (cf. Fuseau horaire). Le modèle porte ce rappel sur ses blocs build Docker, xdebug et worktrees.

Variable Ancien défaut État
HTTP_PORT 80 Sans consommateur. L'application est servie par le proxy hôte sur https://app.main.localhost (ou https://app.<worktree>.localhost).
HTTPS_PORT 443 Sans consommateur. Idem.
HTTP3_PORT 443 Sans consommateur. Le proxy publie 443/udp pour HTTP/3.
POSTGRES_PORT 5432 Sans consommateur. Client BDD : docker compose exec database ….
RABBITMQ_PORT 5672 Sans consommateur.
RABBITMQ_MANAGEMENT_PORT 15672 Sans consommateur. UI RabbitMQ : docker compose exec ou tunnel ponctuel côté hôte.
TYPESENSE_PORT 8108 Sans consommateur en tant que port publié. À ne pas confondre avec le TYPESENSE_PORT injecté dans l'environnement du conteneur php par compose.yaml, figé à 8108 — c'est le port interne du service, cf. Typesense.
GOTENBERG_PORT 3000 Sans consommateur.
MKDOCS_PORT 8000 Sans consommateur. La documentation est servie sur https://docs.main.localhost (ou https://docs.<worktree>.localhost).
MAILPIT_SMTP_PORT 1025 Sans consommateur. Le SMTP est joignable depuis les conteneurs sur mailer-int:1025.
MAILPIT_UI_PORT 8025 Sans consommateur. L'UI est servie sur https://mailpit.main.localhost (ou https://mailpit.<worktree>.localhost — la même boîte, mutualisée).

Plus aucun port publié — et un ports: réintroduit n'est pas le remède

Les sept blocs ports: de compose.override.yaml (php, database, rabbitmq, typesense, gotenberg, mailer, docs) ont été retirés : onze publications en moins. Le seul publisher de tout l'environnement de développement est le conteneur caddy-proxy, sur 127.0.0.1:80 et 127.0.0.1:443.

C'est ce qui permet à N stacks de coexister : elles ne se disputent plus la loopback, elles se distinguent par leur nom d'hôte. Réintroduire un bloc ports: pour « retrouver » un accès direct rouvrirait la collision et la surface exposée. Pour atteindre un service de backing depuis l'hôte, passer par docker compose exec (ou un tunnel ponctuel), jamais par une publication.

Ces variables ne font pas partie du contrat .env.worktree et n'ont pas à y être ajoutées.

IMAGES_PREFIX n'est plus dev-only

IMAGES_PREFIX est lue par compose.yaml et par compose.prod.yaml. Comme son rôle et son défaut diffèrent entre les deux, elle est documentée dans sa propre section : Image de production et préfixe de registry.

Mode et port Xdebug

Xdebug est désactivé par défaut en dev par xdebug.mode = off (frankenphp/conf.d/20-app.dev.ini), que compose.override.yaml reproduit sur l'environnement du conteneur avec XDEBUG_MODE: ${XDEBUG_MODE:-off}. Pour activer ponctuellement la couverture, castor test:coverage injecte XDEBUG_MODE=coverage le temps du run (cf. castor.php) ; cette injection par docker compose exec -e a précédence sur l'environnement du conteneur. Les outils tiers comme PHPStorm peuvent forcer un mode différent à la volée via le flag CLI -dxdebug.mode=..., qui surcharge la directive INI le temps du processus.

Le port d'écoute de l'IDE n'est plus 9003 en dur : il vit dans XDEBUG_CLIENT_PORT (défaut 9003, qui est aussi la valeur par défaut d'Xdebug lui-même — l'INI ne fixe pas xdebug.client_port). Ce défaut est réservé au dépôt principal ; les worktrees allouent 9004 et au-delà. Détail : Variables de worktree.

Proxy Caddy hôte (dev uniquement)

Ces variables pilotent le proxy Caddy hôte — le seul point d'entrée de l'environnement de développement. Elles sont lues côté hôte par infra/proxy/proxy-net.sh (réseau et cloisonnement) et infra/proxy/proxy.lib.sh (génération des confs de site), plus, pour deux d'entre elles, par castor proxy:status.

Elles ne vivent ni dans .env, ni dans .env.local, ni dans .env.worktree : leur valeur par défaut est codée dans les scripts, et une surcharge se fait par une variable d'environnement réelle exportée dans le shell. En pratique, seuls les tests bats les surchargent, pour écrire dans un répertoire temporaire plutôt que dans $HOME.

Variable Défaut Rôle
KIREXO_PROXY_SITES_DIR ${HOME}/.kirexo/proxy/sites Dossier des confs de site générées, monté :ro dans le proxy. Hors du dépôt, délibérément : un worktree ne doit pas pouvoir modifier le routage d'un autre, et le proxy est un singleton partagé par tous les checkouts.
KIREXO_PROXY_TPL_DIR Dossier de proxy.lib.sh, soit infra/proxy/ Dossier des gabarits site.caddy.tpl et fallback.caddy.tpl.
KIREXO_PROXY_RESERVED_WT app demo mailpit localhost www shared proxy (séparés par des espaces) Noms de worktree refusés, pour trois raisons distinctes selon le nom. Collision d'adresse de site — demo seul : il produirait app.demo.localhost, déjà déclarée en dur dans le repli, et Caddy refuserait de recharger sa configuration (duplicate site address) pour tous les worktrees, pas seulement pour le fautif. Ambiguïté de lecture — app et mailpit (préfixes de service : docs.app.localhost se lit aussi bien « la doc du worktree app » que « le worktree docs.app » ; depuis le retrait du bloc mailpit.localhost du repli, un worktree mailpit ne produit plus aucun doublon, seulement des noms ambigus), localhost et www. Collision de nom de projet Compose — shared et proxy, le projet d'un worktree valant kirexo-<wt> : wt:up shared viserait kirexo-shared, la stack mutualisée, et son up --remove-orphans retirerait egress-proxy — coupant la sortie réseau de tous les worktrees. Motif à jour, nom par nom, en commentaire de infra/proxy/proxy.lib.sh.
KIREXO_PROXY_MAIN_WT main Nom figé du « worktree » que constitue le dépôt principal — celui de la branche que porte l'arbre de travail principal. Ce nom est recopié neuf fois, dans sept fichiers qu'aucun lien de code n'unit (inventaire) : elles doivent bouger ensemble, sans quoi le proxy route vers un alias inexistant (502), l'application cesse d'être reconnue sur son propre nom d'hôte (404 sur tout, /login compris) ou la sonde C10 cesse de tester le dépôt principal en silence. Ce nom n'est pas dans la liste réservée ci-dessus : il est valide comme worktree par défaut (proxy_set_default main), mais refusé comme nom de worktree utilisateur par wt_normalize_name et proxy_write_site.
KIREXO_PROXY_NET kirexo-proxy Nom du réseau Docker partagé entre le proxy et les stacks. Déclaré external: true dans compose.override.yaml : il doit exister avant tout docker compose up|run, ce que garantit le préalable commun.
KIREXO_PROXY_SUBNET 172.31.1.0/24 Plage du réseau partagé. Elle suit le plan d'adressage du contrat de confinement et ne doit recouvrir aucune autre plage, sinon docker network create refuse (pool overlaps).
KIREXO_PROXY_IP 172.31.1.2 IP fixe du conteneur caddy-proxy sur ce réseau. La règle de cloisonnement s'y adosse : « tout flux NEW sur ce bridge dont la source n'est pas cette IP est jeté ». Lue aussi par castor proxy:status.
KIREXO_PROXY_IP_RANGE 172.31.1.128/25 Plage d'allocation dynamique du réseau, passée à docker network create --ip-range. Elle exclut par construction la moitié basse du subnet — passerelle .1 et Caddy .2 — quel que soit l'ordre de démarrage des conteneurs. Sans elle, Docker alloue à partir du bas du subnet et le premier conteneur qui rejoint le réseau avant le proxy rafle 172.31.1.2 : voir Pourquoi la plage dynamique du réseau du proxy est bornée. Un réseau créé avant cette borne se recrée par castor proxy:migrate — docker network create ne modifie pas un réseau en place.
KIREXO_PROXY_GATEWAY 172.31.1.1 Passerelle du réseau, passée à docker network create --gateway. Explicite : sans elle, Docker la place au bas de KIREXO_PROXY_IP_RANGE, soit .128 — elle sortirait de la moitié basse que le plan d'adressage réserve, et mangerait la première adresse dynamique. Aucun code ne dépend de cette valeur. Elle n'est appliquée qu'à la création du réseau : --check-ipam ne juge que la plage, un réseau borné mais à passerelle .128 reste donc considéré conforme.
KIREXO_PROXY_BRIDGE br-kirexo-proxy Nom de l'interface bridge, figé pour que la règle iptables soit déterministe — un nom auto-généré changerait à chaque recréation du réseau. 15 caractères maximum (IFNAMSIZ). Lue aussi par castor proxy:status.

Le réseau doit rester internal

infra/proxy/proxy-net.sh crée kirexo-proxy avec --internal et refuse de continuer si un réseau homonyme existe sans l'être. Un réseau non-internal fournit une route par défaut : attacher le conteneur php à un second réseau de ce type lui rendrait un accès Internet complet, en contournant le proxy sortant à allowlist, et sans le moindre signal. Cf. Deux réseaux internes, aucune route par défaut.

Les neuf copies du nom du dépôt principal

Le nom du « worktree » que constitue le dépôt principal est écrit neuf fois, dans sept fichiers qu'aucun lien de code n'unit. Aucune copie n'importe la valeur d'une autre : chacune porte son propre littéral, en dur ou en repli :-. Sept le portent nu, deux l'enchâssent dans le nom d'hôte applicatif complet (app.<nom>.localhost) — c'est la même valeur sous une autre forme, et elle doit suivre les autres.

# Fichier Forme Divergence ⇒
1 infra/confinement/check.lib.sh défaut du 3ᵉ argument de confinement_peer_aliases — la référence sonde C10 muette
2 infra/confinement/check.sh le ${WT:-…} passé en self_wt à cette fonction le dépôt principal se sonde lui-même
3 infra/proxy/proxy.lib.sh KIREXO_PROXY_MAIN_WT 502
4 compose.override.yaml alias réseau php-${WT:-…} du service php 502
5 compose.override.yaml alias réseau docs-${WT:-…} du service docs — une copie à part entière 502 sur la seule documentation
6 compose.full.yaml le même alias php-${WT:-…}, pour le profil full 502 en profil full
7 .claude/hooks/lib/session-dir.sh repli candidate='…' du namespace de session état de session dédoublé
8 .env app.<main>.localhost dans KIREXO_RESERVED_DOMAINS 404
9 compose.override.yaml le même nom d'hôte, dans le repli ${KIREXO_RESERVED_DOMAINS:-…} 404, en dormance

502 et 404 ne se diagnostiquent pas pareil. Les copies 3 à 6 gouvernent des noms d'upstream : le proxy finit par router vers un alias que personne ne porte, et la panne se lit du côté de l'infrastructure. Les copies 8 et 9 sont des noms d'hôte applicatifs : Caddy route parfaitement, le conteneur répond, et c'est SiteResolver::isAppDomain() (src/Plugin/Web/src/Service/SiteResolver.php) qui ne reconnaît plus l'adresse comme applicative — la résolution Host → Site la traite alors en domaine de site public, n'en trouve aucun, et rend 404 sur toute l'application, /login compris. C'est le mode de panne le plus grave de l'inventaire, et le seul qui n'accuse pas le routage.

La copie 9 est dormante tant que .env définit la variable : Compose charge ce fichier pour l'interpolation, la branche de repli n'est donc jamais évaluée dans le dépôt principal (cf. l'avertissement de Multi-tenant (résolution de domaine)). Elle n'en est pas moins une copie : elle est la valeur servie dès que la variable n'est pas définie, et rien ne signale qu'elle a divergé d'ici là.

L'alias docs- compte pour lui-même parce qu'il a son propre consommateur et son propre mode de panne : c'est lui que vise le reverse_proxy docs-main:8000 écrit dans 01-main.caddy par proxy_write_main (infra/proxy/proxy.lib.sh, gabarit infra/proxy/site.caddy.tpl). Une divergence sur cette ligne-là laisse l'application du dépôt principal parfaitement servie et rend 502 sur docs.main.localhost — la documentation devient injoignable, seule.

Aucune divergence ne casse bruyamment : le proxy route vers un alias que personne ne porte (502 derrière un TLS parfaitement valide), la sonde C10 interroge un alias disparu et rend ok sans avoir rien mesuré, ou l'application rend 404 pendant que toute l'infrastructure se déclare saine. Le renommage local → main en a oublié plusieurs, à deux reprises, sans qu'aucun test ne rougisse.

Les cas « COHÉRENCE » de tests/Bash/confinement/peer_aliases.bats comparent ces sources entre elles, en extrayant chaque valeur de son fichier plutôt qu'en la recopiant. Corollaire opposable : toute nouvelle copie de ce nom ajoute son cas dans ce fichier. Le pourquoi de cette dispersion est discuté dans Le dépôt principal est un worktree nommé main.

Les occurrences en message ou en commentaire ne sont pas dans l'inventaire

Le même nom apparaît aussi dans des textes que personne n'exécute : commentaires de .env, de .env.local.dist et des gabarits du proxy, message de revalidation du hook Stop (.claude/hooks/lib/checklist-container.sh). Une divergence y produit une consigne qui envoie vers une URL morte, jamais une panne — ils sont hors inventaire et hors du corollaire ci-dessus.

Alias réseau : deux noms par service multi-réseaux

Un service attaché à la fois au réseau de la stack et à celui du proxy rend deux adresses sous son nom nu — Docker répond par toutes les adresses partagées entre demandeur et cible. Une connexion sur deux partirait alors vers le réseau du proxy, où elle est jetée : panne intermittente, sans message.

D'où la règle, portée par compose.override.yaml : deux alias distincts, chacun déclaré sur un seul réseau, et aucun consommateur ne vise le nom de service nu.

Service Alias applicatif Alias sur kirexo-proxy Consommateurs de l'alias applicatif
php (aucun — voir ci-dessous) php-${WT:-main} MERCURE_URL vise le nom nu php, mais depuis php lui-même : la résolution rend ses propres adresses et le noyau route le paquet par lo, sans jamais traverser le bridge du proxy. Aucun autre consommateur ne vise ce nom.
docs docs-int docs-${WT:-main} Sonde « doc en ligne » du hook Stop, message d'aide de castor docs:build.
mailer mailer-int mailpit-shared MAILER_DSN.

Forme mapping obligatoire

Les alias exigent la forme networks: {proxy: {aliases: [...]}}. La forme liste (networks: [default, proxy]) ne permet pas d'en déclarer : les récrire ainsi ferait tomber tous les worktrees en 502 d'un coup, sans que rien ne l'annonce.

Variables de worktree (dev uniquement)

Cinq singletons de la stack de développement étaient câblés en dur dans compose.override.yaml : le nom du réseau Docker (kirexo), le tag de l'image locale (kirexo-dev-local:latest), le port Xdebug (9003), l'index Redis (0) et les domaines réservés. Tant qu'ils sont fixes, une deuxième instance de la stack entre en collision avec la première.

Ils dérivent désormais d'un seul identifiant de worktree, WT, porté par un fichier .env.worktree à la racine du worktree. Une stack par worktree git peut ainsi coexister avec les autres.

Invariant : fichier absent = comportement historique

.env.worktree absent ⇒ la stack se comporte exactement comme avant. Chaque variable porte un défaut égal à sa valeur historique : projet Compose = basename du dossier, réseau kirexo, image kirexo-dev-local:latest, Xdebug 9003, index Redis 0, vhost RabbitMQ %2f. C'est le mode du dépôt principal — rien à créer, rien à configurer.

L'invariant vaut pour le dépôt principal, qui n'a jamais eu ce fichier. Dans un worktree, son absence n'est pas un mode de fonctionnement mais un état cassé : les cibles wt:* le disent au lieu de se replier sur les défauts, cf. Le projet Compose visé par les cibles de worktree.

Les 16 clés du contrat

Ordre du fichier rendu. Source de vérité : wt_managed_keys() et wt_render_env() dans infra/worktree/env.lib.sh. Les exemples valent pour WT=ticket-185.

Variable Exemple (WT=ticket-185) Défaut sans .env.worktree Rôle
WT ticket-185 (clé absente) Identifiant du worktree, dont tout le reste dérive. Motif imposé : [a-z0-9][a-z0-9_-]{0,30} — c'est ce qu'accepte un nom de projet Docker Compose. Une valeur malformée fait échouer Castor au chargement, avec un message explicite (worktree_env() dans castor.php).
COMPOSE_PROJECT_NAME kirexo-ticket-185 basename du dossier projet Préfixe natif Compose des conteneurs, volumes et réseaux. Précédence : -p > cette variable > name: du fichier compose > basename du dossier. Les cibles castor wt:* passent toujours un -p kirexo-<worktree>, calculé sans le fichier : la valeur écrite ici n'est donc plus celle qu'elles honorent, seulement celle qu'elles contrôlent — une divergence est signalée, jamais suivie. Cf. Le projet Compose visé par les cibles de worktree.
COMPOSE_PROFILES light (vide) Profils Compose actifs. Écrite par castor wt:up --profile=light\|full, puis réutilisée quand l'option est omise — sans cette mémoire, un second wt:up ferait retomber une stack full en light. C'est cette variable, et non un empilement de fichiers Compose, qui discrimine les deux profils : elle active les services portant profiles: ["full"] dans compose.override.yaml — redis, rabbitmq, typesense, gotenberg — éteints en light, où les instances mutualisées de kirexo-shared prennent le relais. Détail : Profils de ressources et mutualisation.
KIREXO_NETWORK kirexo-ticket-185 kirexo Nom du réseau default de la stack (networks.default.name dans compose.override.yaml, ${KIREXO_NETWORK:-kirexo}). Lu aussi côté Castor par kirexo_network(). Aucune plage IP imposée : cf. Aucune subnet n'est allouée.
KIREXO_IMAGE_TAG ticket-185 latest Tag du layer overlay buildé localement (image: kirexo-dev-local:${KIREXO_IMAGE_TAG:-latest}). Un castor wt:up <ticket> ne re-pointe donc jamais l'image qu'un autre worktree utilise — la cible reconstruit kirexo-dev-local:<worktree> quand elle est absente ou plus ancienne que le Dockerfile, sous ce tag-là et aucun autre. Le contenu buildé étant identique, Docker dédup les layers.
KIREXO_GIT_COMMON_DIR /home/<user>/dev/kirexo/.git (clé absente) Common dir git du dépôt principal, chemin absolu côté hôte — le fichier .git d'un worktree y pointe en absolu. Consommée par compose.worktree.yaml, que Compose n'auto-découvre jamais et qu'une cible doit empiler explicitement : le common dir est monté dans le conteneur au même chemin absolu, en écriture pour php et en lecture seule pour docs. C'est ce qui fait fonctionner git dans le conteneur d'un worktree — et l'entrée correspondante de confinement_allowed_mounts() est ce qui garde C1 au vert.
KIREXO_SHARED_CLAUDE_DIR /home/<user>/dev/kirexo/var/claude (clé absente) var/claude du dépôt principal, chemin absolu côté hôte — l'espace de travail des skills (cadrage d'étape, specs de lots, scripts de ship, rapports). Dérivée du common dir par wt_shared_claude_dir() (infra/worktree/env.lib.sh) : une seule source de vérité pour « où est le dépôt principal ». Consommée par compose.worktree.yaml, qui monte ce dossier dans le conteneur au même chemin absolu, en écriture ; castor wt:up fait ensuite du var/claude du worktree un lien vers ce chemin. Le même chemin des deux côtés est nécessaire, pas cosmétique : ce dossier est lu depuis l'hôte (scripts de ship, DoD, pare-feu) autant que depuis le conteneur (skills, sous-agents). Une valeur vide fait échouer le démarrage (:? dans compose.worktree.yaml) plutôt que de poser un bind bancal. L'entrée correspondante de confinement_allowed_mounts() garde C1 au vert.
KIREXO_RESERVED_DOMAINS localhost,127.0.0.1,app.ticket-185.localhost,ticket-185.localhost celui du dépôt principal, cf. Multi-tenant (résolution de domaine) Domaines réservés à l'application, jamais servis comme site public multi-tenant. Le domaine du worktree doit y figurer. La forme sans préfixe app. est l'ancienne URL du worktree, réellement servie avant le renommage : elle est là pour les signets, jamais pour couvrir une fenêtre de migration. Ce raisonnement-là serait à l'envers — castor wt:up écrit la conf proxy et .env.worktree avant le up qui recrée le conteneur (castor/worktree.php), l'ancien nom n'est donc présent que dans la liste déjà régénérée. Ce qu'elle achète est autre chose : ce nom n'ayant plus de bloc de site, il retombe sous le joker *.localhost du repli, qui l'envoie au worktree par défaut ; l'y lister fait répondre l'application au lieu d'un 404, mais seulement quand ce défaut est le worktree propriétaire du nom. La comparaison est une égalité exacte, jamais un préfixe. Le raisonnement est en commentaire au-dessus de la clé, dans infra/worktree/env.lib.sh. Rôle complet et implications multi-tenant : Multi-tenant (résolution de domaine).
MAIL_FROM [ticket-185] Kirexo <noreply@kirexo.local> Kirexo <noreply@kirexo.local> Expéditeur global des mails, appliqué par framework.mailer.headers.From (config/packages/mailer.yaml). Mailpit étant mutualisé entre worktrees, le préfixe rend la boîte partagée lisible. À ne pas confondre avec MAILER_FROM_ADDRESS, dont la valeur par défaut de MAIL_FROM dérive et qui n'est pas dans ce contrat.
REDIS_DB_INDEX 1 0 Index de base logique Redis, pour isoler cache, sessions et verrous entre worktrees. Alloué dans 1..15 — l'index 0 est réservé au dépôt principal. Consommée par REDIS_URL et LOCK_DSN (compose.override.yaml).
RABBITMQ_VHOST ticket-185 %2f Vhost RabbitMQ de la stack, qui cloisonne ses queues sur le broker mutualisé. Consommée par les deux MESSENGER_TRANSPORT_*_DSN (compose.override.yaml). Le vhost lui-même est créé et autorisé par castor wt:up, avant le démarrage de la stack : sans cela, le worker Messenger partirait en ACCESS_REFUSED au premier message.
TYPESENSE_COLLECTION_PREFIX ticket-185_ (vide) Préfixe des noms de collections Typesense, qui cloisonne l'index sur l'instance mutualisée. Consommée par compose.override.yaml.
XDEBUG_CLIENT_PORT 9004 9003 Port d'écoute de la fenêtre PhpStorm de ce worktree. C'est la valeur allouée, reportée dans XDEBUG_CONFIG — le conteneur, lui, ne lit que XDEBUG_CONFIG. Alloué dans 9004..9066 : 9003 est réservé au dépôt principal.
XDEBUG_CONFIG client_host=host.docker.internal client_port=9004 idekey=ticket-185 (vide) Valeur qui fait foi côté conteneur. compose.override.yaml n'est qu'un passe-plat (XDEBUG_CONFIG: ${XDEBUG_CONFIG:-}) ; vide = comportement historique (les valeurs de l'INI et les défauts d'Xdebug s'appliquent).
PHP_IDE_CONFIG serverName=ticket-185 (vide) Passe-plat également (PHP_IDE_CONFIG: ${PHP_IDE_CONFIG:-}). Rattache une session CLI au Server PhpStorm qui porte le path mapping.
WT_GATEWAY_IP relevée à l'exécution, ex. 172.18.0.1 (vide) Gateway du réseau de la stack, lue sur Docker après création du réseau — jamais calculée. Rendue présente et vide à la génération, puis renseignée par castor wt:up juste après le démarrage. Quand la valeur change, wt:up recrée le seul service php : extra_hosts est figé à la création du conteneur. Consommée par extra_hosts dans compose.override.yaml (host.docker.internal:${WT_GATEWAY_IP:-host-gateway}), qui rend l'IDE joignable depuis un réseau internal: true — cf. Brancher PhpStorm sur un worktree.

Chaque clé du contrat a un lecteur

MAIL_FROM, REDIS_DB_INDEX, RABBITMQ_VHOST et TYPESENSE_COLLECTION_PREFIX ont été écrites au contrat avant d'être lues : leurs consommateurs sont arrivés avec la mutualisation des services de backing, et WT_GATEWAY_IP avec extra_hosts. Les poser dès l'origine a évité de réconcilier deux fois le fichier chez chaque développeur. Aucune clé du contrat n'est écrite sans effet observable.

Un lot qui a besoin d'une nouvelle variable par worktree ajoute une ligne à wt_managed_keys() ; il ne crée pas un second véhicule.

Où vit le fichier

  • Emplacement : .env.worktree, à la racine du worktree (un par worktree).
  • Gitignoré — l'entrée /.env.worktree est dans .gitignore. Il ne doit jamais être committé : il porte des valeurs propres à un poste et à un worktree.
  • Généré et réconcilié par castor wt:up <ticket>, à chaque exécution. Les fonctions qui produisent le fichier vivent dans infra/worktree/env.lib.sh et sont utilisables côté hôte uniquement.
  • Modèle versionné : .env.worktree.dist à la racine du dépôt. C'est une référence de lecture, pas un fichier à copier : la source de vérité est wt_render_env(), pas le modèle.

Ne pas l'éditer à la main

wt:up réconcilie le fichier clé par clé à chaque exécution : toute valeur du contrat que vous y modifiez sera réécrite. Deux garanties compensent cette réécriture :

  • les clés hors contrat que vous ajoutez sont préservées (aucune réécriture globale du fichier) ;
  • une ligne commentée n'est pas confondue avec la clé : # MAIL_FROM=… reste un commentaire, la décommenter est votre décision.

XDEBUG_CLIENT_PORT et REDIS_DB_INDEX déjà présents sont réutilisés au lieu d'être réalloués : sans cela, le port d'écoute changerait à chaque wt:up et la configuration PhpStorm du développeur casserait.

XDEBUG_MODE est la clé libre

Le fichier généré se termine par cette ligne, commentée :

# XDEBUG_MODE='develop,debug'

Elle est à vous, jamais réécrite par la réconciliation. Trois points à connaître :

  • .env.worktree est le seul endroit où la décommenter a un effet en mode worktree — compose.override.yaml lit ${XDEBUG_MODE:-off} depuis l'environnement d'interpolation de Compose, qui ne contient ni .env.local, ni la cascade Symfony.
  • xdebug.mode ne se règle que par cette variable. Passer le mode dans XDEBUG_CONFIG (XDEBUG_CONFIG=mode=develop,debug) est silencieusement ignoré par Xdebug — aucune erreur, aucun log, le step-debugger reste simplement inerte.
  • Après changement, il faut recréer le conteneur (docker compose up -d php) et non le redémarrer : l'environnement d'un conteneur est figé à sa création.

Qui lit .env.worktree

Trois lecteurs, et un quatrième qui ne le lit jamais.

Lecteur Comment
Docker Compose docker compose --env-file .env --env-file .env.worktree …
Castor worktree_env() (castor.php) parse le fichier avec Symfony Dotenv et publie les valeurs dans l'environnement du process, pour que la quinzaine d'appels à docker compose disséminés dans les cibles visent tous le même projet. Les valeurs déjà présentes dans le shell gagnent, comme chez Compose. Le parsing est celui de Dotenv, jamais un parseur maison : trois lecteurs d'un même fichier ne doivent pas en donner trois lectures différentes. Le nom du projet ne repose plus sur cette publication dans les cibles wt:*, qui le passent en -p ; le reste des clés, si.
Scripts hôte wt_load_env (infra/worktree/env.lib.sh) source le fichier (set -a). No-op silencieux si le fichier est absent : c'est le mode mono-worktree, pas une erreur. C'est ce qui impose le quotage par apostrophes simples de toutes les valeurs rendues — un fichier sourcé exécuterait sinon ce que contient MAIL_FROM.
Symfony — jamais Le fichier n'appartient pas à la cascade Dotenv (.env, .env.local, .env.$APP_ENV, .env.$APP_ENV.local). Les valeurs atteignent l'application par le bloc environment: de Compose, pas autrement.

L'ordre des --env-file compte, et .env doit être répété

Passer un --env-file désactive le chargement automatique de .env. L'omettre de la ligne ne « garde » donc pas les valeurs de .env : il les perd, en silence, et le build repart sur les replis internes (USER_ID, ports, KIREXO_RESERVED_DOMAINS…). D'où la forme complète, .env en premier, .env.worktree ensuite — le second gagne sur les clés communes, et une variable réellement présente dans le shell gagne sur les deux.

Ce détail ne concerne que les lanceurs hors Castor (IDE, script maison) : Castor, lui, n'utilise pas --env-file du tout — il publie les valeurs dans l'environnement du process avant d'invoquer docker compose, qui les voit alors comme de vraies variables d'environnement.

Ces variables ne fonctionnent ni dans .env.local, ni dans .env

  • .env.local : Docker Compose ne le lit jamais — la cascade .env.local est une mécanique Symfony Dotenv, pas une mécanique Compose. L'échec est muet : la variable est simplement ignorée, aucun message, et le diagnostic se fait des heures plus tard sur une stack qui vise le mauvais réseau. .env.local.dist porte un bloc ###> worktrees (NE PAS définir ici) ### qui rappelle la liste des quinze clés concernées.
  • .env : il est versionné. Une valeur propre à un worktree y salirait le git status de tout le monde et finirait committée.

Le seul véhicule est .env.worktree, ou une variable d'environnement réelle exportée dans le shell pour une surcharge ponctuelle.

Aucune subnet n'est allouée

Il n'existe ni clé WT_SUBNET, ni fonction d'allocation de plage IP, et il n'en est pas prévu. Docker est l'IPAM : c'est lui qui choisit la plage du réseau, garantit qu'elle ne recouvre pas celle d'un autre réseau, et refuse le up en cas de conflit. Réimplémenter cette allocation, ce serait dupliquer la logique avec un fichier d'état à verrouiller, à nettoyer, et qui se désynchronise au premier git worktree remove manuel.

WT_GATEWAY_IP est donc relevée sur le réseau réel une fois celui-ci créé, jamais calculée :

docker network inspect kirexo-ticket-185 --format '{{(index .IPAM.Config 0).Gateway}}'

La lecture est tolérante par construction (wt_gateway_ip, infra/worktree/env.lib.sh) : Docker absent, réseau inexistant ou IPAM.Config vide donnent une chaîne vide et un code de retour 0, jamais une erreur. Un repli déduit la gateway du Subnet (172.19.0.0/16 → 172.19.0.1, convention Docker pour un bridge) quand le champ Gateway est vide. Et une valeur relevée vide n'écrase jamais une gateway déjà écrite : mieux vaut une valeur ancienne mais plausible qu'un trou.

Fonction hôte uniquement

wt_gateway_ip a besoin du socket Docker, absent du conteneur par construction (invariant de confinement C2). Comme toutes les fonctions de cette lib qui touchent à Docker ou à git, elle s'exécute côté hôte.

Variables hôte du cycle de vie des worktrees

Ces trois variables ne figurent pas dans le contrat .env.worktree : elles sont lues côté hôte, dans le shell qui lance les cibles castor wt:*. Il n'y a pas de fichier où les poser — on les exporte pour la session, ou dans son profil shell.

Variable Défaut Rôle
KIREXO_WORKTREES_DIR <parent du dépôt principal>/kirexo-worktrees Racine sous laquelle vivent les worktrees (<racine>/ticket-185). Lue par wt_worktrees_dir (infra/worktree/wt.lib.sh). Un chemin situé sous le dépôt principal est refusé par wt:up : le worktree entrerait dans le bind .:/app du dépôt principal et ferait tomber les invariants de confinement C1 et C8.
KIREXO_CLAUDE_BYPASS 1 (implicite) Mise à 0, elle fait renoncer au mode bypassPermissions pour les sessions Claude de ce poste, dans ses deux moitiés : castor wt:claude ne pose plus le flag --permission-mode bypassPermissions sur la ligne de commande, et wt:up n'écrit plus le consentement skipDangerousModePermissionPrompt dans .claude/settings.local.json. La session démarre donc en mode confirmation. C'est une demande — ne pas la confondre avec KIREXO_CLAUDE_BYPASS_ACTIVE, qui est un constat. Alternative persistante, partagée par tous les worktrees : créer le fichier ~/.kirexo/no-claude-bypass. Dans les deux cas, wt:up l'annonce par une ligne de rapport ! settings.local.json (opt-out actif — non généré), ou ! settings.local.json (opt-out actif — existant, laissé tel quel) quand le fichier est déjà là. Un seul opt-out pour les deux moitiés (wt_claude_bypass_enabled(), castor/worktree.php) : dédoublés, ils laisseraient exister une session ouverte en bypass sans consentement — donc un dialogue d'avertissement à chaque ouverture — ou l'inverse, un consentement posé pour un mode qu'on n'accorde plus.
KIREXO_WT_NO_AUTO_UP (non définie) À 1, elle empêche wt:shell (alias wt:bash) et wt:claude de lancer castor wt:up d'elles-mêmes quand la stack du worktree du répertoire courant ne répond pas. wt:shell retombe alors immédiatement sur son conteneur jetable et wt:claude sort en 1 — leurs messages disent que rien n'a été tenté. Ces deux cibles ne créent aucun worktree : elles visent celui du répertoire courant, qui existe donc forcément. Toute autre valeur, variable absente comprise, laisse l'auto-démarrage actif (wt_auto_up_enabled(), castor/worktree.php). Détail : Le démarrage automatique de la stack.

KIREXO_WT_NO_AUTO_UP est une variable, et non une option de commande

wt:claude transmet ses tokens bruts à claude — #[AsRawTokens] rend la ligne de commande entière — : une option Castor --no-auto-up entrerait en collision avec les options de Claude Code. La variable se pose devant l'appel — KIREXO_WT_NO_AUTO_UP=1 castor wt:shell — ou s'exporte pour la durée d'une session de réparation.

Le marqueur no-claude-bypass vit hors du dépôt

Le seul emplacement lu est ~/.kirexo/no-claude-bypass (cf. castor/worktree.php). C'est délibéré : chaque worktree étant un checkout distinct, un marqueur versionné ou posé par worktree ne tiendrait pas — il faudrait le reposer à chaque création, et une branche antérieure le perdrait. Le fichier hors dépôt suit la même logique que ~/.kirexo/secrets/gitlab-token et ~/.kirexo/proxy/sites.

wt:up génère .claude/settings.local.json s'il est absent et aligne celui qui existe déjà (wt_align_settings_local(), castor/worktree.php). L'alignement porte sur deux clés, et sur elles seules :

  • permissions.defaultMode retirée — mais uniquement si elle vaut bypassPermissions : cette valeur décrit un mode que la session n'a pas (Claude Code ignore un mode venu d'un fichier du dépôt, cf. Qui a le droit d'accorder le mode bypassPermissions). Un plan ou un acceptEdits posé à la main est un choix du développeur, que Claude Code honore toujours depuis ce fichier : il survit.
  • skipDangerousModePermissionPrompt posée à true — le consentement au dialogue d'avertissement du mode bypass, que la garde de ce dialogue accepte, elle, depuis les réglages locaux.

Tout le reste du JSON est préservé — serveurs MCP, hooks, modèle, autorisations locales : le fichier est gitignoré et porte les réglages personnels du développeur. L'écriture est atomique, et un échec d'écriture est signalé (!) plutôt que rapporté comme une réconciliation. Lignes de rapport possibles : tableau de réconciliation de wt:up.

Le gabarit versionné est .claude/settings.local.json.tpl, dont le seul placeholder est {{WT}} (rendu dans env.KIREXO_WT, informatif — la source de vérité côté conteneur reste WT, injectée par compose.worktree.yaml). Il ne porte aucun mode de permission : celui-ci vient de la ligne de commande de castor wt:claude.

La sentinelle interne du relais de wt:destroy

Variable Défaut Rôle
KIREXO_WT_DESTROY_REEXEC (non définie) Interne — ne jamais la poser à la main. Posée à 1 par castor wt:destroy sur le sous-processus qu'il relance depuis le dépôt principal quand on l'appelle depuis le worktree visé. Sa présence désarme ce relais, et interdit donc la récursion (castor/worktree.php).

Elle ne figure pas dans le tableau ci-dessus parce qu'elle ne se pose pas depuis l'extérieur : elle n'a aucun usage de diagnostic ni de réglage.

L'exporter dans son shell désactive le relais en silence

Toute valeur non vide fait croire à la cible qu'elle est le sous-processus relancé. Exportée dans un shell, elle la fait retomber sur le chemin qui supprime son propre vendor/ : coches vertes, puis Failed to open stream et code de sortie non nul sur une destruction pourtant réussie. Aucun message n'annonce ce basculement. Le raisonnement complet est dans Ne jamais supprimer le vendor/ dont on dépend.

Où vit l'état d'allocation

Nulle part ailleurs que dans les .env.worktree eux-mêmes. Il n'y a pas de fichier d'état central : la source de vérité des allocations est l'ensemble des worktrees réellement déclarés, énumérés par git worktree list --porcelain puis lus un par un (wt_used_values). Détruire un worktree libère donc mécaniquement son port Xdebug et son index Redis, sans étape de nettoyage.

Le seul artefact hors dépôt est le verrou d'allocation ~/.kirexo/wt-alloc.lock, qui ne porte aucune donnée : il sérialise deux wt:up concurrents, qui liraient sinon le même état et attribueraient le même port. Le supprimer est sans conséquence.

Ressource Valeur réservée au dépôt principal Plage allouée aux worktrees
Port d'écoute Xdebug 9003 9004 … 9066
Index de base Redis 0 1 … 15

L'allocation prend la première valeur libre de la plage, trous compris : sur 9004 et 9006 déjà pris, le worktree suivant obtient 9005. Les valeurs du dépôt principal sont exclues des plages à dessein — une fenêtre PhpStorm déjà ouverte sur 9003 ne doit jamais se faire voler son port par un worktree créé après elle. À saturation, l'allocation échoue avec un message sur stderr plutôt que de réattribuer une valeur déjà prise.

Fuseau horaire (TZ)

Variable Défaut Rôle
TZ Europe/Paris en dev, UTC en prod Fuseau horaire IANA (ex. Europe/Paris). Production : déclarée TZ: "${TZ:-UTC}" dans l'ancre x-kirexo-app-environment de compose.prod.yaml, donc reçue par php et worker ; elle règle à la fois le conteneur et PHP (date.timezone). Dev : déclarée TZ: ${TZ:-Europe/Paris} dans compose.override.yaml ; elle ne règle que le shell du conteneur, PHP restant en UTC. Absente de .env, à dessein.

Comment PHP la lit, selon l'image :

Image Fichiers .ini en jeu date.timezone effectif
kirexo-prod (production) frankenphp/conf.d/10-app.ini seul : date.timezone = ${TZ:-UTC} Valeur de TZ, UTC si elle n'est pas définie.
kirexo-dev (dev et CI) 10-app.ini, puis frankenphp/conf.d/20-app.dev.ini : date.timezone = UTC UTC, quel que soit TZ. 20-app.dev.ini est lu après 10-app.ini (ordre alphabétique du scan) et l'emporte.

La syntaxe de repli ${VAR:-défaut} dans un .ini est supportée par PHP depuis la 8.3 ; l'image est en PHP 8.5. PHP interpole la variable au démarrage du process : un changement de TZ suppose de recréer les conteneurs (docker compose … up -d), un restart ne relisant pas l'environnement.

Valeur de TZ vue par PHP (image prod) Résultat
Non définie UTC.
Fuseau IANA valide Ce fuseau.
Vide UTC, avec un avertissement PHP. Compose ne produit pas ce cas : ${TZ:-UTC} remplace une valeur vide par UTC.
Invalide (ex. Foo/Bar) UTC, avec un avertissement au démarrage, visible dans docker compose … logs php et logs worker. Aucun contrôle ne bloque le démarrage.

Choisir TZ à l'installation, ne plus y toucher

Les colonnes de date sont en Types::DATETIME_IMMUTABLE, soit timestamp without time zone en PostgreSQL : les dates sont écrites dans le fuseau de PHP, sans indication de fuseau. Changer TZ sur une instance qui a déjà des données décale tout l'historique, sans message ni migration. Garder UTC sauf besoin réel. Raisons et conséquences : Pourquoi le fuseau PHP est figé en dev et choisi à l'installation en production.

${TZ:-UTC} reprend le TZ du shell qui lance docker compose

Le défaut UTC n'est atteint que si TZ est absente de l'environnement du shell et du .env du projet. Un TZ exporté par le profil du serveur, ou par la session de l'opérateur, est repris tel quel par l'interpolation, sans être annoncé. Pour une valeur stable, exporter TZ explicitement dans l'environnement de déploiement, au même endroit que les variables obligatoires.

Shell du conteneur de production

PHP embarque sa propre base de fuseaux : date.timezone fonctionne quoi qu'il arrive. L'effet de TZ sur la commande date et sur les horodatages des logs Caddy dépend en revanche de la présence de tzdata dans l'image Alpine, que le Dockerfile n'installe pas explicitement. Sans tzdata, le shell reste en UTC. Ce point n'est pas vérifié par un test.

En dev : shell en heure locale, PHP en UTC

TZ n'y affecte que le shell et les outils non-PHP du conteneur (statusline Claude Code, commande date, logs Docker, scripts Bash). Dans une même session, date renvoie Europe/Paris (ex. 20:22 CEST) tandis que php -r 'echo date("H:i e");' renvoie 18:22 UTC. C'est attendu. Le décalage de 2 h est l'heure d'été ; en hiver ce sera 1 h. Tests et fixtures tournent ainsi en UTC en local comme en CI.

Changer le fuseau du shell de dev

TZ=America/New_York docker compose up -d

Seul le shell change : PHP reste en UTC (20-app.dev.ini). Ne pas déclarer TZ dans .env : Compose le lit pour l'interpolation de tous les fichiers, y compris compose.prod.yaml, et une production déployée depuis un clone hériterait de ce fuseau. Ni dans .env.local, que Docker Compose ne lit jamais (cf. Variables de build Docker).

Variables de build Docker (dev uniquement)

Ces variables sont lues par compose.override.yaml comme build.args du build du service php (image kirexo-dev). Elles réalignent l'utilisateur app du conteneur sur l'UID/GID de l'hôte pour que les fichiers créés dans le bind-mount /app (vendor/, var/, composer.lock…) appartiennent au développeur et non à root.

Variable Défaut Rôle
USER_ID 1000 (dans .env) UID de l'utilisateur hôte passé au build.
GROUP_ID 1000 (dans .env) GID correspondant, même raison.

Docker Compose ne lit que .env, jamais .env.local

Contrairement à Symfony (qui applique la cascade .env → .env.local → environnement du process), Docker Compose ne lit qu'un seul fichier dotenv : .env. La cascade .env.local est une mécanique propre à Symfony. Définir USER_ID/GROUP_ID dans .env.local n'a donc aucun effet sur le build de l'image dev — utilisez .env (défaut versionné) ou une vraie variable d'environnement (surcharge ponctuelle).

C'est pourquoi .env (versionné) porte des défauts USER_ID=1000 / GROUP_ID=1000 dans sa section ###> build Docker (dev uniquement) ### : ils garantissent que tout lanceur trouve toujours les variables, quel que soit le point d'entrée (Castor, IDE, docker compose à la main). Sans ce défaut, un lanceur hors Castor interpolait ${USER_ID}/${GROUP_ID} à vide et le build plantait sur groupmod: invalid group ID ''.

Précédence des valeurs UID/GID

Pour le user app du conteneur — et donc la propriété des fichiers du bind-mount /app — l'UID/GID résulte, par ordre de précédence décroissante :

  1. Variable d'environnement réelle présente au moment du docker compose (la plus prioritaire) :
    • Castor l'injecte automatiquement via posix_getuid() / posix_getgid() (fonction host_user_env() de castor.php) → castor docker:up --build, comme castor wt:up <ticket>, donne toujours vos vraies valeurs, sans rien configurer.
    • Tout lanceur hors Castor (un docker compose build joué à la main, ou un IDE qui pilote Compose lui-même) : la variable doit être exportée dans l'environnement de la session qui lance la commande. PhpStorm, branché en interpréteur distant sur une stack démarrée par Castor, n'est pas concerné — cf. Brancher PhpStorm sur un worktree.
  2. Défaut 1000:1000 versionné dans .env (lu par Docker Compose).
  3. Repli :-1000 du bloc args: de compose.override.yaml (filet si .env était absent).

En complément, dans le dockerfile_inline de compose.override.yaml, les références sont écrites $${USER_ID} / $${GROUP_ID} : le $$ échappe l'interpolation Compose pour que ce soit le moteur de build (via les ARG, repli :-1000) qui les résolve. C'est un filet anti-crash supplémentaire si l'environnement du process est vide.

Cas concret : GID hôte ≠ 1000

La plupart des utilisateurs Linux ont UID et GID à 1000 — le défaut suffit, rien à faire. Mais un dev dont le groupe primaire n'est pas standard (ex. GID hôte 1001) doit surcharger via l'environnement, sinon il hérite du défaut 1000 et les fichiers du bind-mount finissent possédés par le mauvais groupe. Vérifiez votre identité avec id :

id -u   # → UID, ex. 1000
id -g   # → GID, ex. 1001

Avec Castor, c'est automatique — y compris pour castor wt:up, qui construit l'image du worktree. Ce n'est que pour un docker compose build lancé à la main qu'il faut exporter USER_ID/GROUP_ID soi-même. Voir aussi Brancher PhpStorm sur un worktree.

Sortie réseau via le proxy

Le réseau de la stack de développement est internal : il n'existe aucune route vers l'extérieur. La seule sortie est le proxy egress-proxy (Squid, CONNECT-only, allowlist par nom), atteint via les variables ci-dessous. Elles sont posées par l'ancre x-proxy-env de compose.override.yaml, appliquée aux services php et docs.

Elles ne vivent ni dans .env (lu par Docker Compose pour tous les fichiers empilés, y compris ceux partagés avec la production) ni dans .env.dev (lu par Symfony Dotenv seulement — ni le shell, ni curl, ni npm, ni Claude Code ne le voient).

Variable Valeur Rôle
HTTP_PROXY / HTTPS_PROXY http://egress-proxy:3128 Proxy sortant, en majuscules.
http_proxy / https_proxy http://egress-proxy:3128 Mêmes valeurs, en minuscules — indispensable : curl n'honore que les minuscules, Chromium/Chromedriver les préfère, et Symfony HttpClient ignore volontairement HTTP_PROXY en majuscules hors SAPI CLI (parade httpoxy) mais lit https_proxy.
NO_PROXY / no_proxy localhost,127.0.0.1,::1,.localhost,php,database,docs,docs-int,egress-proxy,redis,rabbitmq,typesense,gotenberg,mailer,mailer-int Exclusions. Trois familles : la boucle locale (FrankenPHP se parle à lui-même, chromedriver écoute sur 127.0.0.1:9515, les E2E visent https://localhost et https://app.demo.localhost), les services de la stack du worktree, et les services de la stack mutualisée — dont egress-proxy lui-même, sans quoi un appel au proxy repasserait par le proxy. L'entrée .localhost couvre tout nom en .localhost, quel que soit son nombre de labels.
NODE_USE_ENV_PROXY 1 Node ≥ 22.21 / 24.5 : le fetch natif et undici n'honorent les variables de proxy que si elle est posée. Sans elle, un script Node du projet sort « en direct » et se prend un timeout muet.

Le schéma http:// est volontaire

On parle en clair au proxy, sur le réseau interne, pour lui demander un tunnel CONNECT. Le TLS reste de bout en bout entre le client et le domaine visé : Squid ne déchiffre rien, et aucune autorité de certification n'est à installer dans les conteneurs. Cf. Pourquoi la sortie réseau passe par un proxy à allowlist.

Trois corollaires à connaître avant de diagnostiquer :

  • La résolution DNS des noms externes échoue depuis le conteneur, par conception : c'est le proxy qui résout. Un getent hosts packagist.org en échec n'est pas un symptôme.
  • Les tests E2E ne passent pas par le proxy : PANTHER_CHROME_ARGUMENTS (dans .env.test) contient --no-proxy-server. NO_PROXY couvrirait déjà le cas ; le flag supprime toute dépendance au parsing de no_proxy par Chromium.
  • NO_PROXY n'est pas honoré par tous les clients : le wget des images Alpine est celui de BusyBox, qui lit http_proxy mais ignore no_proxy.

Ajouter <<: *proxy-env à un service dont le healthcheck utilise wget

Couper le proxy explicitement devient alors obligatoire dans la commande du healthcheck, sans quoi celui-ci part vers egress-proxy — qui refuse tout ce qui n'est pas un CONNECT (TCP_DENIED/403) — et le service est déclaré unhealthy puis redémarré en boucle par autoheal, le diagnostic accusant un serveur qui n'y est pour rien. Forme en vigueur pour le service docs (compose.override.yaml) :

test: ["CMD", "env", "http_proxy=", "https_proxy=", "wget", "--spider", "-q", "http://127.0.0.1:8000"]

Vider les variables plutôt qu'utiliser le -Y off de BusyBox : -Y existe aussi en GNU wget, où il est l'alias de --proxy et attend un booléen. Rien ne garantit que l'image mkdocs reste sur une base Alpine, et la casse serait de la même nature. Un http_proxy vide, lui, est ignoré par les deux implémentations.

curl honore no_proxy et n'a pas besoin de ce traitement. Le healthcheck de mailer a la même forme sans neutralisation et reste correct : ce service ne reçoit pas les variables de proxy. Diagnostic du cas : Un service redémarre en boucle depuis son passage par le proxy. Raisonnement : no_proxy est une convention, pas un standard.

Variables internes aux scripts du conteneur

Ces variables sont lues à l'intérieur du conteneur php par les scripts shell de infra/. Elles ne sont pas définies dans .env — leur défaut est codé dans infra/lib/common.sh, sourcée par tous les scripts qui en dépendent.

Variable Défaut Rôle
KIREXO_WORKSPACE /app Racine du projet montée dans le conteneur. Lue par infra/healthcheck/php-healthcheck.sh, infra/supervisor/supervisor.lib.sh et infra/image/image-freshness.lib.sh pour construire les chemins absolus (${KIREXO_WORKSPACE}/var/log/supervisor/frankenphp.log, ${KIREXO_WORKSPACE}/var/run/supervisor/, …). Permet de tester les scripts depuis l'hôte sans monter le projet en /app. Elle départage aussi les boucles de supervision : supervisor_loop_pids lit le KIREXO_WORKSPACE de chaque boucle dans /proc/<pid>/environ (/app s'il est absent) et ne retient que celles de l'espace de travail courant. Une boucle d'un autre espace de travail n'est jamais découverte, arrêtée ni comptée. Le verrou du supervisor, supervisor.lock, vit dans ${KIREXO_WORKSPACE}/var/run/supervisor/ : il y en a un par espace de travail.
SUPERVISOR_* — Paramètres du supervisor (SUPERVISOR_LOCK_TIMEOUT, SUPERVISOR_SPAWN_WAIT, SUPERVISOR_MAINTENANCE_POLL, SUPERVISOR_TEST_COMMAND, réservée aux tests) : voir Worktrees — Une seule boucle par programme.
LOG_SOURCE kirexo Étiquette de source utilisée par le logger commun kirexo_log() (infra/lib/common.sh), qui imprime [<ISO8601>] [<LOG_SOURCE>] <message>. Chaque script pose la sienne (php-healthcheck, supervisor:<programme>, …) — c'est ce qui rend un grep '\[php-healthcheck\]' utile sur le journal commun.

Le répertoire de journaux porte le nom de ce qui écrit dedans

Le point de vérité unique est supervisor_log_dir() (infra/supervisor/supervisor.lib.sh) : ${KIREXO_WORKSPACE}/var/log/supervisor. Les chemins du dépôt sont donc var/log/supervisor/frankenphp.log, var/log/supervisor/messenger.log et var/log/supervisor/supervisor.log, en miroir de var/run/supervisor/ qui porte les PID files des mêmes programmes.

Le dossier est recréé au premier démarrage du supervisor : sur un conteneur qui tournait sous l'ancien nom, les journaux déjà écrits ne sont pas déplacés — ils restent lisibles là où ils sont, et rien de neuf ne s'y ajoute.

Variables du service docs (dev uniquement)

Le service docs (mkdocs en live-reload) reçoit les variables de proxy via l'ancre x-proxy-env, plus une variable qui lui est propre, déclarée dans son bloc environment: de compose.override.yaml.

Variable Valeur Rôle
GIT_DISCOVERY_ACROSS_FILESYSTEM 1 Autorise git à franchir une frontière de système de fichiers en remontant vers le dépôt.

Pourquoi le plugin de dates a besoin de cette variable

Le conteneur reçoit deux binds imbriqués : ./docs sur /docs/docs et ./.git sur /docs/.git. Le premier est donc un point de montage distinct du répertoire qui porte le second. En remontant l'arborescence depuis une page, git bute sur cette frontière et s'arrête avant /docs/.git.

Sans la variable, le plugin git-revision-date-localized échoue alors sur chaque page, et strict: true fait sortir castor docs:build en 1. La cible devient inutilisable comme gate local, alors même que la CI — qui build sur un clone sans bind imbriqué — reste verte : un écart entre les deux qui se paye au moment de comprendre pourquoi.

Elle ne relâche rien au-delà de ce conteneur, dont les seuls binds sont le dépôt lui-même.

Espace Claude et jeton GitLab (dev local)

Ces cinq variables concernent le poste de développement. Aucune ne vit dans .env ni dans .env.local : CLAUDE_CONFIG_DIR et GLAB_CONFIG_DIR sont déclarées en dur dans le service php de compose.override.yaml, GITLAB_TOKEN provient d'un fichier hors dépôt, ~/.kirexo/secrets/gitlab-token, injecté par env_file:, et CLAUDE_CODE_DISABLE_MOUSE_CLICKS comme KIREXO_CLAUDE_BYPASS_ACTIVE n'existent que le temps d'une session ouverte par castor wt:claude. CLAUDE_CONFIG_DIR et GITLAB_TOKEN sont aussi exportées côté hôte par ~/.kirexo/env.sh, généré par castor claude:space.

Variable Origine Rôle
CLAUDE_CONFIG_DIR compose.override.yaml, service php (valeur figée /home/app/.claude-kirexo). Côté hôte : ~/.kirexo/env.sh, valeur $HOME/.kirexo/claude. Déplace l'intégralité de l'espace utilisateur de Claude Code (settings, transcrits, mémoire, file-history/, plugins/, .claude.json…) hors de ~/.claude. Un seul dossier pour l'hôte et pour tous les worktrees, afin qu'une conversation démarrée dans l'un soit reprise par claude --resume dans un autre. La valeur côté conteneur a un point unique de vérité : la fonction cs_container_dir() de infra/claude-space/bootstrap.lib.sh.
GITLAB_TOKEN (dev local) Fichier ~/.kirexo/secrets/gitlab-token, hors dépôt, chmod 600, format dotenv. Injecté par env_file: [{path: ${HOME}/.kirexo/secrets/gitlab-token, required: false}] dans le service php de compose.override.yaml. Jeton GitLab dédié à Kirexo, consommé par glab — qui lit cette variable avant le config.yml de GLAB_CONFIG_DIR — et par le credential helper git du conteneur, qui la lit dans l'environnement pour authentifier les git push HTTPS. Le dossier ~/.kirexo/secrets (mode 700) est par ailleurs monté en lecture seule sur /run/secrets dans le conteneur : le jeton y reste lisible en /run/secrets/gitlab-token, comme source relisable à chaud lors d'une rotation. Création, vérification et rotation : Créer et faire tourner le jeton GitLab de Kirexo.
CLAUDE_CODE_DISABLE_MOUSE_CLICKS Posée par castor wt:claude en -e de son docker compose exec (wt_claude(), castor/worktree.php). Ni .env, ni environment:, ni profil shell. Lue par Claude Code seul — ni PHP, ni Symfony, ni les workers du conteneur n'en savent rien. Elle lui fait renoncer au mode souris du terminal (\e[?1000h), qu'il active pour rendre son interface cliquable : sans elle, le terminal transmet les clics à l'agent au lieu de faire sa sélection native, et le texte affiché dans la conversation — commandes hôte, chemins, sorties de sonde — n'est plus sélectionnable qu'aux conditions de l'agent (cf. la note plus bas). Elle ne coupe que clic, glisser et survol : la molette, donc le défilement de l'interface, reste active. La variante CLAUDE_CODE_DISABLE_MOUSE, qui coupe toute la capture, n'est pas celle retenue.
KIREXO_CLAUDE_BYPASS_ACTIVE Posée par castor wt:claude en -e de son docker compose exec, dans la session lancée et elle seule (wt_claude(), castor/worktree.php). Ni .env, ni environment:, ni profil shell. Constat sur la session, pas réglage : 1 si la ligne de commande claude finale ouvre bien en bypassPermissions, 0 sinon. Elle est calculée sur la ligne complète — flag injecté plus tokens de l'utilisateur (ClaudeBypassFlag::declaresBypass(), castor/src/Worktree/ClaudeBypassFlag.php) —, donc un castor wt:claude --dangerously-skip-permissions, qui n'injecte rien, la publie quand même à 1. Unique consommateur : le gate de confinement du hook SessionStart, qui ne s'arme qu'en bypassPermissions et s'en sert de repli quand Claude Code ne lui passe pas de permission_mode. Absente, elle vaut 0 : un claude lancé à la main depuis castor wt:shell n'accorde aucun bypass, le gate n'a donc pas à s'armer.
GLAB_CONFIG_DIR compose.override.yaml, service php (valeur figée /home/app/.config/glab-cli). Non définie côté hôte. Répertoire de configuration de glab dans le conteneur. Sans elle, glab dérive son répertoire de XDG_CONFIG_HOME=/config, posé par l'image FrankenPHP/Caddy sur un volume appartenant à root : l'utilisateur app ne peut pas y écrire le fichier temporaire créé à chaque lancement, et toute commande glab échoue sur failed to read configuration: open /config/glab-cli/… permission denied — avant même la lecture de GITLAB_TOKEN. /home/app appartient à app:app et n'est pas un volume : le répertoire est créé au premier lancement de glab, sans montage.

KIREXO_CLAUDE_BYPASS et KIREXO_CLAUDE_BYPASS_ACTIVE : une demande, un constat

Les deux noms se ressemblent, les deux variables ne font pas le même métier et ne vivent pas du même côté.

KIREXO_CLAUDE_BYPASS KIREXO_CLAUDE_BYPASS_ACTIVE
Nature Demande du développeur Constat sur la session ouverte
Où elle vit Shell hôte, ou ~/.kirexo/no-claude-bypass Environnement de la session claude dans le conteneur
Qui l'écrit Le développeur castor wt:claude
Qui la lit castor wt:up et castor wt:claude Le hook SessionStart
Effet d'un 0 Renonce au bypass : ni flag, ni consentement Aucun effet — décrit seulement ce qui est

Poser KIREXO_CLAUDE_BYPASS_ACTIVE=1 à la main n'accorde donc rien : ça ment au gate de confinement, qui s'armera sur une session qui n'est pas en bypass. Le sens de la lecture est l'inverse de celui de l'écriture — c'est pour ça que les deux noms diffèrent.

Deux variables GITLAB_TOKEN, deux contextes disjoints

Le nom GITLAB_TOKEN désigne deux variables distinctes, qui ne se rencontrent jamais :

  • celle de cette section — dev local, lue depuis ~/.kirexo/secrets/gitlab-token sur le poste du développeur, jamais définie côté GitLab ;
  • celle des variables CI/CD GitLab — définie dans Settings → CI/CD → Variables du projet, consommée par les jobs tag:create, security:composer-audit, tools:version-check, dependencies:renovate et security:container-issue, jamais présente sur un poste de dev.

Ce ne sont pas deux usages d'un même jeton : les scopes diffèrent (api seul en dev, api + write_repository en CI), les porteurs diffèrent (compte bot ou PAT personnel de repli en dev, PAT du mainteneur en CI), et les révoquer n'a pas les mêmes conséquences. Ne réutilisez pas la valeur de l'un pour l'autre.

Ne jamais déclarer GITLAB_TOKEN dans environment:

La spécification Compose donne à environment: la précédence sur env_file:, « même si la valeur est vide ou indéfinie ». Une ligne GITLAB_TOKEN: ${GITLAB_TOKEN:-} ajoutée au service php viderait le jeton silencieusement : glab retomberait sur une authentification absente sans qu'aucun message ne l'indique. L'injection passe exclusivement par env_file:.

env_file est lu à la création du conteneur

Renseigner ou changer le jeton dans ~/.kirexo/secrets/gitlab-token n'a aucun effet sur la variable GITLAB_TOKEN d'un conteneur déjà en cours d'exécution : elle est figée à sa création. Il faut recréer le conteneur — geste décrit dans Propager le jeton aux conteneurs.

Le montage, lui, reflète la nouvelle valeur immédiatement : /run/secrets/gitlab-token est relisable à chaud (set -a; . /run/secrets/gitlab-token; set +a).

C'est le dossier ~/.kirexo/secrets qui est monté, pas le fichier

Un bind de fichier attache un inode, pas un chemin : un éditeur qui écrit un temporaire puis le renomme par-dessus la cible (vim, VS Code, sed -i) crée un nouvel inode côté hôte, et le conteneur reste attaché à l'ancien, orphelin. La relecture à chaud décrite ci-dessus n'était donc pas tenue tant que le montage portait sur le fichier. Un bind de dossier résout les entrées à chaque accès : elle l'est désormais.

Contrepartie : le dossier expose tout son contenu au conteneur. Un fichier déposé à côté du jeton y devient lisible sans créer de point de montage, donc sans que l'invariant de confinement C1 puisse le signaler. ~/.kirexo/secrets ne contient que gitlab-token — règle portée par .claude/skills/_shared/secrets-env.md.

CLAUDE_CODE_DISABLE_MOUSE_CLICKS est posée sur l'exec, et nulle part ailleurs

Ce qu'un programme interactif demande à son terminal ne regarde ni PHP, ni les tests, ni les workers du même conteneur : un environment: Compose l'imposerait à tous, et le changer obligerait à recréer le conteneur. Un profil shell ne conviendrait pas davantage — wt:claude n'exécute aucun shell, elle exec directement claude, et /home/app n'étant pas bind-monté, le fichier ne survivrait pas au prochain rebuild de l'image. Reste le -e de l'exec, dont la portée est exactement la session ouverte (wt_exec_interactive(), castor/worktree.php).

Conséquence à connaître : un claude lancé à la main depuis castor wt:shell ne reçoit pas la variable, et retrouve donc le mode souris.

Récupérer le texte autrement : /copy, /export, « Copy on select »

Trois mécanismes répondent au même besoin que la variable — sortir du terminal ce que l'agent affiche — sans passer par la sélection du terminal. Ils appartiennent à Claude Code : le dépôt ne les déclare pas, ne les configure pas et n'en garantit pas la présence. Ils sont constatés dans la version que l'image de développement épingle — ARG CLAUDE_CODE_VERSION=2.1.282 du Dockerfile, cf. Node et Claude Code — et une version ultérieure peut les renommer, les déplacer ou les retirer.

Mécanisme Ce qu'il couvre
/copy La dernière réponse de l'agent, ou la N-ième précédente via /copy N. Un sélecteur propose d'isoler un bloc de la réponse ; le réglage « Skip the /copy picker » (/config) copie la réponse entière sans le proposer.
/export La conversation entière, vers le presse-papier ou vers un fichier — /export [filename].
« Copy on select » Réglage /config (copyOnSelect), actif par défaut : l'agent copie de lui-même ce qui vient d'être sélectionné. Il suppose donc qu'il capte la souris, c'est-à-dire une session ouverte sans cette variable.

Le conteneur n'embarque ni xclip, ni wl-copy, ni aucun DISPLAY : le presse-papier du poste n'est atteignable que par une séquence OSC 52 remise à l'émulateur de terminal — Claude Code l'annonce d'ailleurs lui-même en rendu plein écran. Un terminal qui n'honore pas OSC 52 ne verra donc rien arriver.

Ces trois mécanismes ne remplacent pas la variable : ils livrent des unités décidées par l'agent — une réponse, un bloc, une conversation — là où la sélection native prend n'importe quel fragment. Dans la même version, l'agent indique par ailleurs qu'une touche maintenue pendant la sélection rend la main au terminal ; la variable évite d'avoir à la connaître et à la tenir.

Git dans le conteneur (dev local)

Ces variables configurent git à l'intérieur du conteneur php, où le git push est le geste nominal. Elles sont déclarées dans le service php de compose.override.yaml — fichier commun au dépôt principal et aux worktrees, ce qui les rend valables des deux côtés sans passer par castor wt:up.

Aucune n'écrit quoi que ce soit dans .git/config : la configuration passe entièrement par le protocole GIT_CONFIG_COUNT / GIT_CONFIG_KEY_<n> / GIT_CONFIG_VALUE_<n> de git, qui n'a d'effet que dans les process du conteneur. Le common dir est partagé avec l'hôte, où le remote SSH doit continuer de servir.

Variable Valeur Rôle
GIT_USER_NAME .env (Carlos Pereira De Amorim), défaut Kirexo Identité portée par les commits créés depuis le conteneur. Doit vivre dans .env : Compose ne lit jamais .env.local. Une variable d'environnement réelle a précédence.
GIT_USER_EMAIL .env (carlos@shauri.fr), défaut dev@kirexo.local Idem, pour l'adresse.
GIT_AUTHOR_NAME / GIT_AUTHOR_EMAIL / GIT_COMMITTER_NAME / GIT_COMMITTER_EMAIL dérivées des deux précédentes Auteur et committer des commits. Sans elles, git commit échoue sur « Please tell me who you are » — avant même d'atteindre le push.
GIT_TERMINAL_PROMPT 0 Interdit tout prompt interactif. Sans tty, git bloquerait ou rendrait un could not read Username sans indiquer la cause réelle.
GIT_CONFIG_COUNT 5 Nombre de paires GIT_CONFIG_KEY_<n> / GIT_CONFIG_VALUE_<n> lues par git.

Les cinq paires, dans l'ordre des index :

Clé git Valeur Rôle
url.https://gitlab.com/.insteadOf git@gitlab.com: Bascule le transport en HTTPS. insteadOf et non pushInsteadOf : le fetch doit passer lui aussi, sinon git pull --ff-only échoue encore sur le transport SSH absent.
credential.helper fonction shell inline Lit GITLAB_TOKEN dans l'environnement et rend username=oauth2 + password=…. Le jeton n'est jamais écrit sur disque. Si la variable est absente, le helper échoue franchement, sur stderr, en renvoyant vers Créer et faire tourner le jeton GitLab de Kirexo — sans cette garde il rendrait un mot de passe vide et l'utilisateur verrait un 401 sans rapport apparent.
core.hooksPath /app/infra/git-hooks Arme le hook pre-push. Chemin absolu : un chemin relatif serait résolu par git depuis le répertoire courant, donc faux dès qu'une commande git part d'un sous-dossier.
user.name ${GIT_USER_NAME} En plus des GIT_AUTHOR_* / GIT_COMMITTER_* : ces dernières laissent git config user.email vide, que plusieurs outils interrogent.
user.email ${GIT_USER_EMAIL} Idem.

Ne jamais interpoler le jeton dans une valeur environment:

La valeur du credential.helper contient $GITLAB_TOKEN littéralement (échappé $$ pour Compose) : la variable est lue au moment du push, dans l'environnement du process. Écrire sa valeur ici la figerait au démarrage du conteneur et la rendrait visible dans docker inspect. Même règle que pour GITLAB_TOKEN lui-même.

Un core.hooksPath inexistant n'est pas une erreur pour git

Git saute les hooks en silence quand le répertoire pointé est absent. C'est le mode de panne à surveiller si le bind change, et c'est aussi ce qui arrive dans un worktree resté sur une branche antérieure à la création de infra/git-hooks/ : le garde-fou pre-push n'y est simplement pas armé, sans le moindre message.

Ce que le hook refuse, et comment pousser malgré lui quand c'est délibéré : Pousser sur GitLab depuis un worktree. Pourquoi ce dispositif existe : Pourquoi l'agent pousse lui-même, et ce qui le retient.

Site vitrine

Variables lues par les cibles Castor site:* (castor/site.php) par getenv(). Elles sont absentes de .env et de .env.test : on les passe dans l'environnement du process qui lance la cible (shell hôte, shell du conteneur php ou job CI).

Variable Défaut Lue par Rôle
SITE_DEPLOY_PROVIDER (absente) — repli sur deploybase (SiteBuilder::DEFAULT_PROVIDER) castor site:build, castor site:deploy Hébergeur du site vitrine : deploybase ou ovh. Choisit les mentions de l'hébergeur insérées dans le marqueur kirexo:hebergeur et le fournisseur qui reçoit le déploiement. Lue seulement quand l'option --provider est vide ; une variable vide équivaut à une variable absente. Toute autre valeur fait échouer la cible en nommant la variable. Les valeurs admises sont les clés de SiteBuilder::HOSTING_PROVIDERS (castor/src/Site/SiteBuilder.php). En CI, c'est une variable de projet non protégée (cf. Variables CI/CD GitLab).
CI_COMMIT_TAG (injectée par GitLab sur tag) castor site:deploy Version attendue quand --expect-version est vide, si elle est semver.
KIREXO_INSIDE_CONTAINER 1 dans le conteneur de dev uniquement castor site:deploy, infra/site/deploy.sh Refuse le déploiement réel (sortie 3) ; seul --dry-run passe.
SITE_DEPLOY_PROVIDER=ovh castor site:build

Variables de infra/site/deploy.sh

Variables facultatives lues par le script de déploiement appelé par castor site:deploy. Aucune n'est à déclarer en temps normal : les défauts sont écrits dans le script.

Variable Défaut Rôle
DEPLOYBASE_API_URL https://api.deploybase.eu Racine de l'API deploybase (préfixe /api/v1 ajouté par le script).
DEPLOYBASE_BRANCH main Champ branch du manifeste : branche de production du projet deploybase.
OVH_FTP_REMOTE_DIR www Racine web de l'hébergement OVH, cible de mirror --delete. Refusée si vide, /, ., .. ou contenant ...
SITE_PUBLIC_URL https://www.kirexo.app/ Page relue après publication pour vérifier la version servie.
SITE_DEPLOY_POLL_TIMEOUT 120 (secondes) Délai maximal d'attente d'un statut terminal du déploiement deploybase.
SITE_DEPLOY_VERIFY_ATTEMPTS 10 Nombre de lectures de SITE_PUBLIC_URL avant échec.
SITE_DEPLOY_VERIFY_DELAY 6 (secondes) Intervalle entre deux lectures.

Les secrets (DEPLOYBASE_*, OVH_FTP_*) ne sont définis qu'en CI : cf. Variables CI/CD GitLab.

Variables CI/CD GitLab

Ces variables sont définies dans Settings → CI/CD → Variables du projet GitLab et lues par les pipelines décrites dans la Référence Pipeline GitLab CI. Elles ne vivent jamais dans .env ni dans .env.local.

GITLAB_TOKEN côté CI ≠ GITLAB_TOKEN côté poste de dev

La variable CI/CD décrite ci-dessous est sans rapport avec la variable homonyme du poste de développement, décrite dans Espace Claude et jeton GitLab (dev local). Deux jetons, deux porteurs, deux scopes, deux contextes.

Variable Source Rôle
GITLAB_TOKEN À créer manuellement — Personal Access Token (PAT) Token unique du projet, consommé par cinq usages qui ont tous besoin soit de pousser une branche/un tag, soit d'appeler une route de l'API REST que CI_JOB_TOKEN ne couvre pas sur GitLab Free : (1) tag:create (cf. .gitlab/ci/tag.yml) pour appeler POST /projects/:id/repository/tags ; (2) security:composer-audit (cf. .gitlab/ci/security.yml) pour pousser une branche security/composer-* et ouvrir la MR de patch (ou ouvrir une issue de fallback via castor ci:open-issue) ; (3) tools:version-check (cf. .gitlab/ci/dependencies.yml) pour ouvrir une issue via castor ci:open-issue quand un outil épinglé dans le Dockerfile est en retard ; (4) dependencies:renovate (cf. .gitlab/ci/dependencies.yml), où Renovate le lit via le mapping RENOVATE_TOKEN: $GITLAB_TOKEN pour créer branches et merge requests de montée de version ; (5) security:container-issue et security:container-issue:builders (cf. .gitlab/ci/security.yml) pour appeler POST /projects/:id/issues quand au moins une CVE Critical/High est remontée — CI_JOB_TOKEN n'est pas supporté pour cette route sur GitLab Free (la whitelist du job token couvre Registry/Packages/Releases mais pas l'API issues : retour HTTP 401 testé empiriquement, et le réglage « Allow projects to access this project via CI/CD job tokens » n'y change rien — il n'étend que l'accès inter-projets, pas la whitelist des endpoints). Scopes nécessaires : api (création d'issue/MR par les jobs 2, 3, 4 et 5 via le PAT) + write_repository (création de tag par le job 1 et de branches par les jobs 2 et 4). À configurer en masked uniquement (non protected) dans Settings → CI/CD → Variables — la variable doit être disponible aussi sur les feature branches et les MRs, pas seulement sur les refs protégées (les jobs security:container-issue (+ :builders) tournent sur la pipeline de MR / branche courante pour pouvoir ouvrir l'issue d'alerte CVE, et Protect variable la masquerait à ce moment-là). Non utilisé par release:create ni par les jobs Docker — ceux-ci passent par CI_JOB_TOKEN / CI_REGISTRY_PASSWORD (cf. ci-dessous).
GITHUB_COM_TOKEN À créer manuellement — PAT GitHub read-only (un jeton sans aucun scope suffit : il ne sert qu'à relever le quota) Jeton github.com, sans rapport avec GITLAB_TOKEN. Deux consommateurs, avec deux exigences différentes. (1) dependencies:renovate (cf. .gitlab/ci/dependencies.yml) — requis : un préflight contrôle la présence puis la validité du jeton et fait échouer le job s'il est vide. composer update (régénération de composer.lock) et la récupération des release notes interrogent l'API github.com ; sans jeton, le quota anonyme de 60 requêtes/h est dépassé sur un projet Symfony et la MR de montée de version part avec un composer.lock désynchronisé. Renovate lit la variable nue (env.GITHUB_COM_TOKEN) — aucune variable RENOVATE_GITHUB_COM_TOKEN n'est déclarée. (2) Le before_script de .php_quality_job (cf. .gitlab-ci.yml), hérité par tous les jobs qui lancent composer install — optionnel : si le jeton est exposé et accepté par api.github.com, Composer s'authentifie avant d'installer (5000 requêtes/h par jeton au lieu de 60/h par IP de runner) ; s'il est absent, refusé ou injoignable, les jobs installent en anonyme exactement comme avant (fail-open, cf. Authentification Composer auprès de GitHub). Sans cette variable, la CI fonctionne donc ; avec elle, l'installation des dépendances est moins exposée au quota partagé. À configurer en masked et non protected, comme GITLAB_TOKEN — les jobs PHP tournent sur des refs non protégées (MRs, feature branches).
CI_REGISTRY_USER Injecté par GitLab Identifiant d'authentification au registry du projet. Utilisé par les jobs docker:build-* pour docker login.
CI_REGISTRY_PASSWORD Injecté par GitLab Mot de passe d'authentification au registry du projet, valide le temps du job.
CI_REGISTRY_IMAGE Injecté par GitLab Préfixe complet du registry du projet (ex. registry.gitlab.com/shaurifr/kirexo). Sert à construire les noms d'images kirexo-base, kirexo-dev, kirexo-prod.
CI_JOB_TOKEN Injecté par GitLab Token automatique du job courant, scopé sur le job (révoqué à sa fin). Utilisé par release:create pour authentifier release-cli. Pas utilisé par security:container-issue (+ :builders) : la whitelist de CI_JOB_TOKEN sur GitLab Free ne couvre pas POST /projects/:id/issues (testé HTTP 401 empiriquement), ces deux jobs passent par GITLAB_TOKEN (cf. ligne au-dessus).
CREATE_TAG Variable de déclenchement (à passer au lancement de pipeline) true pour lancer la pipeline isolée de création de tag (job tag:create, cf. .gitlab/ci/tag.yml). Absente ou différente de true : la pipeline standard quality + test tourne. Voir Créer un tag de release.
FORCE_TAG Variable de déclenchement optionnelle (à passer au lancement de pipeline) true pour outrepasser le garde-fou de tag:create, qui refuse normalement de créer le tag si aucune pipeline success n'existe pour le dernier commit de main. À passer en plus de CREATE_TAG=true. Sans effet hors de la pipeline CREATE_TAG=true. Réservée aux cas exceptionnels. Voir Créer un tag de release.
DEPLOYBASE_API_KEY À créer manuellement — clé d'API deploybase (dbk_ + 64 hex) Authentifie release:site-deploy auprès de l'API deploybase (Authorization: Bearer). Masked and hidden + Protected.
DEPLOYBASE_PROJECT_ID À créer manuellement — identifiant du projet deploybase Projet qui reçoit le site vitrine. Protected.
OVH_FTP_HOST À créer manuellement Hôte FTPS de l'hébergement OVH (repli). Protected.
OVH_FTP_USER À créer manuellement Utilisateur FTP de l'hébergement OVH (repli). Protected.
OVH_FTP_PASSWORD À créer manuellement Mot de passe FTP (repli) : au moins 8 caractères, une ligne, sans espace, « Expand variable reference » décoché. Masked and hidden + Protected.
SITE_DEPLOY_PROVIDER Facultative deploybase ou ovh. Non protégée : lue aussi par castor site:build dans quality:site-check en MR. Cf. Site vitrine.
OVH_FTP_REMOTE_DIR Facultative (défaut www) Racine web OVH. Non protégée. Cf. Variables de infra/site/deploy.sh.

Secrets du site vitrine : Protected, donc tags protégés

Les variables DEPLOYBASE_* et OVH_FTP_* sont Protected : GitLab ne les transmet qu'aux refs protégées. Les tags semver sont donc protégés par le motif *.*.* ; sur un tag non protégé, release:site-deploy sort en 2 en nommant la variable manquante. Procédure : Publier le site vitrine.

Pourquoi un PAT et pas un project access token

Kirexo est hébergé sur GitLab.com en tier gratuit, où les project access tokens (et les group access tokens) ne sont disponibles qu'à partir des offres Premium/Ultimate. En gratuit, le seul type de token utilisable en variable CI/CD est un Personal Access Token (PAT) rattaché à un compte. GITLAB_TOKEN est donc un PAT du mainteneur, avec les scopes api + write_repository. Il sert aussi à Renovate, qui le lit via le mapping RENOVATE_TOKEN: $GITLAB_TOKEN défini dans le job dependencies:renovate — aucune variable RENOVATE_TOKEN distincte n'est déclarée côté GitLab.

GITLAB_TOKEN : masqué, non protégé

Cocher Mask variable au moment de la création, sans cocher Protect variable. Mask empêche le token d'apparaître en clair si un job l'echoait par mégarde. Protect, en revanche, doit rester décoché : security:container-issue (+ :builders) tourne sur la pipeline de la MR / feature branch courante pour ouvrir l'issue d'alerte CVE, et Protect variable rendrait la variable indisponible sur ces refs non protégées — l'appel POST /projects/:id/issues partirait alors sans PRIVATE-TOKEN et retomberait en HTTP 401. Le PAT doit appartenir à un compte ayant comme rôle minimum Maintainer sur le projet, pour pouvoir créer un tag (l'API repository/tags refuse les rôles inférieurs) ainsi que les branches et MRs de Renovate.

Variables exportées dans le shell hôte

Certaines variables ne sont lues ni par compose.override.yaml, ni par .env, ni par .env.local : elles doivent être exportées dans le shell hôte qui invoque la cible Castor concernée. Il n'existe pas de fichier où les poser — on les exporte pour la session, ou dans son profil shell. Toutes sont documentées dans Variables hôte du cycle de vie des worktrees :

Variable Lue par Effet
KIREXO_WORKTREES_DIR castor wt:* Racine sous laquelle vivent les worktrees.
KIREXO_CLAUDE_BYPASS castor wt:up, castor wt:claude Opt-out du mode bypassPermissions : ni flag sur la ligne de commande, ni consentement écrit dans .claude/settings.local.json.
KIREXO_WT_NO_AUTO_UP castor wt:shell, castor wt:claude Opt-out du wt:up automatique quand la stack du worktree courant ne répond pas.
USER_ID / GROUP_ID docker compose build UID/GID de l'utilisateur app de l'image dev — cf. Précédence des valeurs UID/GID.