Aller au contenu

Trois entrées HTTP, un seul fichier Compose

Le bundle install/ doit servir des installations très différentes : un serveur nu où Kirexo est seul sur les ports 80 et 443, un hôte où un Traefik tourne déjà pour d'autres projets, une machine où un Nginx ou un HAProxy termine le TLS de tout le reste. Il le fait avec un seul compose.yaml, que l'installateur n'édite jamais : tout se choisit dans .env. Cette page discute les choix qui rendent cela possible, et ce qu'ils coûtent. Les valeurs exactes sont dans Bundle d'installation install/.

Trois entrées, quatre configurations

Il y a trois façons de faire entrer le trafic HTTP : FrankenPHP en frontal, derrière Traefik, derrière un proxy existant. La première se décline en deux configurations, selon que Caddy émet ou non des certificats à la demande pour les domaines de site. D'où les quatre scénarios A1, A2, B et C de .env.example.

Dans les quatre cas, le serveur applicatif reste FrankenPHP. Ce qui change, c'est ce qui se trouve devant lui : rien, un Traefik ou un proxy. Le bundle n'embarque donc ni Traefik ni Nginx. Il s'adapte à celui qui existe déjà, ou s'en passe.

La contrainte qui complique tout est le multi-tenant. Chaque utilisateur peut servir son site public sur son propre domaine, déclaré dans l'interface, inconnu au moment de l'installation. L'entrée HTTP doit accepter des domaines arbitraires, ce qui écarte d'emblée les configurations qui énumèrent les noms servis. La résolution Host → Site reste côté PHP, quel que soit le scénario : cf. Multi-tenant : résolution d'un domaine vers un site.

Pourquoi aucun profil

Les profils Compose semblent faits pour ce besoin : un profil traefik, un profil proxy, et l'installateur choisit. Ils ne s'appliquent pourtant pas ici.

Un profil active ou désactive des services. Or les quatre scénarios ont exactement les mêmes services : php, worker, database, redis, rabbitmq. Ils ne diffèrent que par des valeurs : SERVER_NAME, adresse et port publiés, proxys de confiance, labels. Des profils imposeraient de dupliquer le service php en autant de variantes, qui divergeraient au premier changement porté sur l'une d'elles.

Un profil doit aussi être rappelé à chaque commande. Un docker compose up -d lancé sans le --profile du premier démarrage, pendant une mise à jour par exemple, ne démarre pas les mêmes services. Une variable dans .env, elle, est relue à chaque commande sans que personne ait à s'en souvenir.

Un seul fichier, enfin, c'est un seul artefact à publier, à vérifier et à documenter. Le coût est reporté dans .env.example, qui porte un bloc commenté par scénario, à décommenter en entier.

Les mêmes ports conteneur partout

Dans le conteneur, FrankenPHP écoute toujours sur 80 et 443. Seule la publication sur l'hôte change : en frontal, sur toutes les interfaces, ports 80 et 443 ; derrière un proxy local, sur 127.0.0.1, ports 8080 et 8443.

Rendre la publication elle-même facultative aurait exigé deux définitions du service. Publier sur la boucle locale suffit : le port n'est joignable que par le proxy de la machine. En scénario B, la publication 127.0.0.1:8443 ne sert à rien, puisque Traefik passe par le réseau Docker, mais elle ne coûte rien non plus.

Laisser KIREXO_BIND_ADDRESS vide en frontal publie sur toutes les interfaces. C'est ce qu'il faut à un serveur exposé à Internet, IPv4 comme IPv6.

Pourquoi la syntaxe courte des ports

La syntaxe longue de Compose (target, published, host_ip, protocol) se lit mieux, et semblait naturelle pour une adresse optionnelle : host_ip: "${KIREXO_BIND_ADDRESS:-}". Elle échoue pourtant dans le cas nominal. Compose refuse un host_ip vide : docker compose config s'arrête sur invalid ip address:, et le scénario A, où l'adresse reste vide, devient impossible à démarrer. Compose n'a aucun moyen d'omettre une clé selon la valeur d'une variable : une clé présente doit porter une adresse valide.

La syntaxe courte déplace le problème dans une chaîne, où l'interpolation peut le résoudre. La forme ${KIREXO_BIND_ADDRESS:+${KIREXO_BIND_ADDRESS}:} vaut l'adresse suivie de : si la variable est définie et non vide, et rien sinon. Vide, la chaîne rendue est 80:80/tcp : pas d'adresse, donc toutes les interfaces, IPv4 et IPv6. Renseignée à 127.0.0.1, elle devient 127.0.0.1:8080:80/tcp. Le fichier ne contient ainsi aucune clé host_ip.

Le prix est une contrainte d'écriture pour IPv6. Dans la syntaxe courte, : sépare déjà l'adresse et les ports : une adresse IPv6 nue serait ambiguë. Elle s'écrit donc entre crochets, KIREXO_BIND_ADDRESS=[::1], et Compose la rend en host_ip: ::1. Le commentaire de install/compose.yaml et celui de .env.example le rappellent.

SERVER_NAME=:80 derrière un proxy

Derrière Traefik ou un proxy existant, le TLS est déjà terminé : FrankenPHP reçoit du HTTP clair. Il faut alors qu'il accepte n'importe quel Host, puisque les domaines de site arrivent par la même porte, et qu'il ne tente aucune gestion de certificat.

Une adresse Caddy sans nom d'hôte, :80, fait les deux. Elle matche tout Host, et elle n'est pas éligible à l'HTTPS automatique : pas de tentative ACME vouée à l'échec, pas de redirection 308 vers HTTPS qui renverrait le proxy sur lui-même. C'est le même raisonnement que pour l'adresse :8080 du développement, décrit dans Pourquoi le proxy parle en clair au FrankenPHP.

Le suffixe , php:80 est ajouté dans tous les cas, en dehors de la variable. Il déclare le vhost interne en clair, sur lequel le conteneur publie vers le hub Mercure et Caddy interroge l'endpoint ask. Le laisser saisissable dans .env aurait permis de le retirer par mégarde.

Un réseau edge dont l'identité varie

En scénario B, php doit rejoindre le réseau Docker de Traefik, qui appartient à un autre projet et existe déjà. Dans les autres scénarios, ce réseau n'existe pas. Compose ne sait pas rattacher un service à un réseau « si une variable le demande » ; il faudrait un profil, qu'on vient d'écarter.

La solution retourne le problème : php rejoint toujours un réseau edge, et c'est l'identité de ce réseau qui varie. Par défaut, edge s'appelle kirexo_edge et il est créé par le projet. Il ne relie alors que php à lui-même, sans effet. En scénario B, KIREXO_EDGE_EXTERNAL=true et KIREXO_EDGE_NETWORK=traefik en font une référence au réseau existant. La clé external accepte une valeur interpolée : Compose convertit la chaîne en booléen après l'interpolation.

Les labels Traefik suivent la même logique. Ils sont toujours présents, et restent inertes tant que traefik.enable vaut false. Un Traefik qui surveille Docker ignore un conteneur dont ce label est à false.

Épingler php sur la boucle locale

Le conteneur s'appelle lui-même par le nom php : MERCURE_URL vaut http://php/.well-known/mercure, et Caddy interroge l'endpoint ask sur http://php/…. Sur le réseau par défaut du projet, php désigne sans ambiguïté le service du même nom.

Sur le réseau partagé de Traefik, ce n'est plus vrai. D'autres projets y branchent leurs propres services, et un service php est un nom courant. Le DNS embarqué de Docker peut alors rendre l'adresse d'un voisin : la publication Mercure, avec son jeton signé, partirait chez un autre projet, et la décision d'émettre un certificat serait prise par un serveur étranger.

extra_hosts: ["php:127.0.0.1"] court-circuite le DNS : le nom est résolu depuis /etc/hosts, avant toute requête au DNS de Docker. Le service n'a jamais besoin de joindre un autre conteneur sous ce nom, l'épinglage ne retire donc rien. Il est posé dans tous les scénarios, pour que le comportement ne dépende pas du réseau rejoint.

TRUSTED_PROXIES vide en frontal

En frontal, les clients se connectent directement à FrankenPHP. Aucun intermédiaire n'est légitime pour poser X-Forwarded-For ou X-Forwarded-Proto. Faire confiance à ces en-têtes permettrait à n'importe quel client de choisir l'adresse IP que l'application lui attribue, et donc de contourner la limitation des tentatives de connexion, qui compte par couple adresse IP et identifiant. La valeur par défaut est donc vide.

Derrière un proxy, c'est l'inverse : sans confiance, toutes les requêtes semblent venir du proxy, et l'application croit servir en HTTP ce qui a été reçu en HTTPS. Le bloc B et le bloc C proposent les plages privées (127.0.0.0/8, 10.0.0.0/8, 172.16.0.0/12, 192.168.0.0/16), parce que l'adresse source d'un proxy sur un bridge Docker n'est pas connue à l'avance. Le scénario C demande de la restreindre à l'adresse du proxy s'il tourne sur une autre machine.

TRUSTED_HOSTS, lui, reste non défini dans tous les scénarios : un filtre écrit à l'installation rejetterait les domaines de site, inconnus à cette date. Ce qui protège en son absence est dans Pourquoi TRUSTED_HOSTS n'est pas le filtre des Host en production.

L'endpoint ask autorise les domaines réservés

Le scénario A2 active tls { on_demand } dans le vhost de frankenphp/Caddyfile. Cette directive s'applique à tous les noms du bloc, et le Caddyfile n'a qu'un vhost. Le domaine de l'application passe donc, lui aussi, par l'endpoint ask avant d'obtenir son certificat.

Tant que l'endpoint ne répondait 200 qu'aux domaines mappés à un Site, l'application elle-même n'aurait jamais obtenu de certificat en A2 : les sites auraient été servis en HTTPS, pas la page de connexion. WebPluginTlsAskController (src/Plugin/Web/src/Controller/WebPluginTlsAskController.php) répond donc aussi 200 pour un domaine réservé à l'application.

Un second vhost dédié à l'application, sans on-demand, aurait évité la modification. Il aurait dupliqué le hub Mercure, le php_server et la configuration des journaux, pour un résultat identique.

La décision « ce domaine est celui de l'application » n'est pas recodée dans le contrôleur. Elle est déléguée à SiteResolver::isAppDomain() (src/Plugin/Web/src/Service/SiteResolver.php), la même égalité exacte que celle de la résolution Host → Site. Un domaine réservé obtient ainsi un certificat si et seulement s'il est servi comme application.

L'autorisation n'élargit pas la surface. KIREXO_RESERVED_DOMAINS est fixée par l'exploitant et ne contient que ses propres domaines : aucun visiteur ne peut y ajouter un nom pour obtenir un certificat. L'ordre des gardes ne change pas : manette coupée d'abord (403 pour tout domaine, sans oracle), puis domaine vide ou invalide (403), puis domaine réservé, puis domaine mappé.

Secrets vides, première barrière

L'alternative naturelle aurait été de livrer les secrets de .env.example avec une valeur d'exemple. Le bundle les livre vides, déclarés ${VAR:?message} dans compose.yaml.

Une valeur d'exemple passe Compose sans encombre. Elle n'est arrêtée qu'au démarrage du conteneur, par le garde-fou de l'entrypoint, après le téléchargement de l'image et la création des volumes. Une valeur vide fait échouer docker compose up avant tout conteneur, avec un message qui nomme la variable et la commande qui la génère. L'arrêt est plus précoce, et le message dit quoi faire.

Le garde-fou de l'entrypoint reste la seconde barrière, pour le cas où un placeholder de développement du dépôt (!ChangeMe!, guest…) aurait été recopié dans .env. Les deux ne font pas double emploi : le premier attrape l'oubli, le second la copie.

Pas de MAIL_FROM

Le bundle injecte MAILER_FROM_ADDRESS, jamais MAIL_FROM. Le .env embarqué dans l'image dérive l'expéditeur complet, Kirexo <adresse>, de MAILER_FROM_ADDRESS. Une ligne MAIL_FROM dans l'environnement du conteneur, même vide, écraserait cette dérivation, et un expéditeur vide ferait échouer tous les envois. L'absence est donc une règle, pas un oubli.

Une seule saisie de domaine

KIREXO_DOMAIN est la seule saisie de domaine obligatoire. DEFAULT_URI, KIREXO_RESERVED_DOMAINS, MERCURE_PUBLIC_URL, SERVER_NAME et la règle Traefik en dérivent par une interpolation imbriquée dans la valeur de repli, par exemple ${DEFAULT_URI:-https://${KIREXO_DOMAIN}}.

compose.prod.yaml a fait l'autre choix : ces variables y sont obligatoires, à renseigner une à une. Le mainteneur les fixe une fois pour toutes ; un installateur tiers, lui, les recopierait cinq fois, avec cinq occasions de se tromper. Une incohérence entre DEFAULT_URI et KIREXO_RESERVED_DOMAINS, par exemple, produit un lien de réinitialisation du mot de passe qui aboutit sur un 404.

La spécification Compose annonce l'interpolation imbriquée. Un commentaire de tests/Unit/Infra/ComposeProxyEgressConsistencyTest.php affirme le contraire, à propos du repli de MAIL_FROM. Le bundle retient la forme imbriquée ; les valeurs rendues se vérifient par docker compose config, et doivent correspondre au tableau Dérivations depuis KIREXO_DOMAIN. Une valeur rendue qui contiendrait encore ${ imposerait le repli de compose.prod.yaml : les cinq clés deviendraient obligatoires.

Pourquoi pas compose.prod.yaml

compose.prod.yaml sert au déploiement du mainteneur. Il est soudé à son Traefik : labels en dur, aucun port publié, aucun réseau paramétré. Le rendre paramétrable l'aurait rendu plus fragile pour son seul utilisateur actuel. Les deux fichiers coexistent donc : install/ pour le tiers, compose.prod.yaml pour le mainteneur. Le service worker est la seule partie qu'ils partagent textuellement, et ses écarts autorisés sont listés dans Écarts du worker avec compose.prod.yaml.

Ce choix a une conséquence connue. Les labels Traefik de compose.prod.yaml ne routent que SERVER_NAME : les domaines de site y restent injoignables. Le bundle traite ce cas de son côté, par la règle KIREXO_TRAEFIK_RULE ; le déploiement du mainteneur relève d'un suivi séparé.

Ce que ce choix ne couvre pas

  • Le scénario A2 n'est couvert par aucun test automatisé. L'émission ACME réelle exige un domaine public qui pointe sur la machine de test. De même, la redirection HTTP vers HTTPS d'un domaine de site par l'adresse catch-all :443 n'est pas vérifiée automatiquement. Ces deux comportements se vérifient à la main, sur une instance réelle, avant une release.
  • Traefik n'émet pas de certificat à la demande. En scénario B, chaque domaine de site exige un Host(…) de plus dans KIREXO_TRAEFIK_RULE, puis un docker compose up -d. Le multi-tenant y demande donc une intervention de l'exploitant par domaine ajouté.
  • Le proxy du scénario C est hors de portée du bundle. Rien ne vérifie qu'il transmet le Host d'origine ou qu'il ne met pas en tampon le flux Mercure. Ses obligations sont écrites dans .env.example, sans contrôle automatique.

Voir aussi