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.yamlou 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 aussidown,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
.envdu répertoire du projet Compose (celui decompose.yamlquand 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.envversionné 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=, 43Asuivis de=) etguest. - La valeur vide n'y figure pas : elle est refusée par un test séparé.
- Tout placeholder de secret ajouté à
.envoucompose.yamldoit 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 { … }dufrankenphp/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
:2019ne répond jamais et le healthcheck échoue. - Le processus reste vivant : la politique
restart: alwaysdecompose.prod.yamlne relance rien, il n'y a pas de boucle de redémarrage. SIGTERMetSIGINT(docker stop,docker compose down) sont honorés immédiatement ; le processus sort en code143.docker execreste 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 :
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.envmasquerait le vault à l'exécution (l'environnement du process et.envont priorité sur le secret déchiffré). En prod, Compose lit.envpour l'interpolation decompose.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 proddans leDockerfile. La clé est injectée commeAPP_SECRET, par une variable d'environnement du serveur quecompose.prod.yamldé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 32ouphp -r 'echo base64_encode(random_bytes(32));'. Sans la variable (absente ou vide), toute commandedocker compose -f compose.yaml -f compose.prod.yaml …échoue avec le messageCLAUDE_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 :
| 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.worktreeest 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 dansinfra/worktree/env.lib.shet 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é estwt_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 :
Elle est à vous, jamais réécrite par la réconciliation. Trois points à connaître :
.env.worktreeest le seul endroit où la décommenter a un effet en mode worktree —compose.override.yamllit${XDEBUG_MODE:-off}depuis l'environnement d'interpolation de Compose, qui ne contient ni.env.local, ni la cascade Symfony.xdebug.modene se règle que par cette variable. Passer le mode dansXDEBUG_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.localest 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.distporte 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 legit statusde 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 :
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.defaultModeretirée — mais uniquement si elle vautbypassPermissions: 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 modebypassPermissions). Unplanou unacceptEditsposé à la main est un choix du développeur, que Claude Code honore toujours depuis ce fichier : il survit.skipDangerousModePermissionPromptposé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
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 :
- Variable d'environnement réelle présente au moment du
docker compose(la plus prioritaire) :- Castor l'injecte automatiquement via
posix_getuid()/posix_getgid()(fonctionhost_user_env()decastor.php) →castor docker:up --build, commecastor wt:up <ticket>, donne toujours vos vraies valeurs, sans rien configurer. - Tout lanceur hors Castor (un
docker compose buildjoué à 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.
- Castor l'injecte automatiquement via
- Défaut
1000:1000versionné dans.env(lu par Docker Compose). - Repli
:-1000du blocargs:decompose.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 :
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.orgen é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_PROXYcouvrirait déjà le cas ; le flag supprime toute dépendance au parsing deno_proxypar Chromium. NO_PROXYn'est pas honoré par tous les clients : lewgetdes images Alpine est celui de BusyBox, qui lithttp_proxymais ignoreno_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-tokensur 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:renovateetsecurity: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. |
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. |