Installer la CA du proxy de développement et migrer un poste existant¶
Vous êtes développeur·se sur le dépôt Kirexo et vous voulez que les URLs de développement (https://app.main.localhost, celles de vos worktrees, la documentation, Mailpit) s'ouvrent sans avertissement de certificat, ou remettre en état un poste installé avant le renommage des URLs en app.. Cette page ne concerne pas une instance installée avec le bundle : pour celle-ci, voir Servir les domaines de site en HTTPS.
En dev — dépôt principal comme worktrees — le mode Caddy à la demande décrit dans Servir les domaines de site en HTTPS reste hors sujet : KIREXO_ONDEMAND_TLS_ENABLED conserve son défaut 0, les placeholders Caddy restent vides, et les domaines de test sont des .localhost. Le TLS local est assuré par le proxy Caddy hôte, qui signe chaque nom avec sa CA locale (tls internal) : aucun endpoint ask, aucune ACME, aucun réglage à poser. La sonde /.kirexo/health reste testable localement sur un domaine de site mappé (app.demo.localhost, cf. SiteFixtures::DEMO_HOST dans src/DataFixtures/SiteFixtures.php).
Le proxy de dev n'émet rien à la demande
Tous ses blocs, y compris le repli qui sert les domaines de site en .localhost, déclarent tls internal : chaque adresse déclarée est provisionnée au chargement de la configuration, avec la CA locale. Aucun endpoint ask, aucune ACME, donc rien de commun avec le mode Caddy à la demande. Un régime à la demande (tls internal { on_demand }) a été essayé sur le repli puis retiré — c'était une régression, et le raisonnement est dans Le régime d'émission n'est pas le levier.
Toutes les URLs de dev ont au moins deux labels sous .localhost
app.<worktree>.localhost, docs.<worktree>.localhost, mailpit.<worktree>.localhost, et app.demo.localhost pour le site de démonstration. Ce n'est pas une convention d'écriture : un certificat qui ne couvrirait qu'un seul label sous un TLD serait refusé par OpenSSL comme par les navigateurs, et c'est ce nommage qui garantit une feuille dédiée à chaque nom. Le raisonnement complet est dans Pourquoi tout nom servi a au moins deux labels. Corollaire opérationnel : n'ajoutez jamais un service sur un nom d'un seul label.
Ce qui change en dev, c'est qui termine le TLS : ce n'est plus le FrankenPHP de la stack, c'est le proxy Caddy hôte (castor proxy:up), seul publisher de l'environnement de développement sur 127.0.0.1:80 et 127.0.0.1:443. Il sert tous les noms en .localhost — l'application, la documentation, Mailpit et les domaines de site — et signe chacun avec sa CA locale. Le raisonnement est dans Routage des worktrees : DNS, TLS et cloisonnement réseau.
Installer la CA du proxy¶
Trois points à connaître :
- Aucune visite préalable n'est nécessaire. La CA est créée dès le premier démarrage du proxy — tous les blocs déclarent
tls internal, provisionné au chargement de la configuration. - Le geste est unique. Seule la racine est installée, et elle vaut 10 ans : elle couvre tous les worktrees, présents et futurs. Feuilles (12 h) et intermédiaire (7 j) sont renouvelés automatiquement par le proxy.
- Firefox garde un trust store séparé. Soit importer
var/caddy-root.crt(Paramètres → Vie privée et sécurité → Certificats → Importer, cocher « Autorités »), soit passersecurity.enterprise_roots.enabledàtruedansabout:config. Chrome, Edge et Safari lisent le trust store système : un redémarrage du navigateur suffit.
Détail de la cible et de ses garde-fous : castor cert:trust.
Retirer l'ancienne racine FrankenPHP¶
Un poste qui a servi avant que le proxy hôte ne devienne l'unique terminateur TLS porte encore, dans son trust store, la racine émise par le FrankenPHP de la stack — c'est elle que castor cert:trust installait alors. Elle ne signe plus rien de joignable depuis l'hôte, le service ne publiant plus de port : son retrait est un nettoyage, pas une correction.
- Linux — rien à faire. La nouvelle racine est installée sous le même nom de fichier (
/usr/local/share/ca-certificates/caddy-local-root.crt) :update-ca-certificatesécrase l'ancienne. Il n'y a pas d'accumulation. - macOS et Windows — l'ancienne racine survit dans le trousseau. Son retrait est manuel.
Ne supprimez pas par nom
Les deux racines sont des autorités locales Caddy et portent un sujet de la même famille (Caddy Local Authority …). Une suppression par nom risque d'emporter celle qu'il faut garder. Repérez d'abord l'empreinte de la racine à conserver :
macOS — lister les racines Caddy du trousseau système avec leur empreinte, puis supprimer celle qui n'est pas l'empreinte ci-dessus :
security find-certificate -a -c "Caddy Local Authority" -Z /Library/Keychains/System.keychain
sudo security delete-certificate -Z EMPREINTE_SHA1_DE_LANCIENNE /Library/Keychains/System.keychain
Windows (terminal administrateur) — lister le magasin ROOT, relever le numéro de série de l'ancienne racine, puis la retirer :
certutil -store ROOT | findstr /C:"Caddy Local Authority"
certutil -delstore ROOT NUMERO_DE_SERIE_DE_LANCIENNE
Vérifier¶
Le contrôle qui prouve l'installation est un curl sans -k : c'est l'absence de cette option qui exige un certificat validé par le trust store de l'hôte. Toutes les URLs de dev y passent désormais, application comprise.
# HÔTE
curl -sS -o /dev/null -w '%{http_code}\n' https://app.main.localhost/ # → 200
curl -sS -o /dev/null -w '%{http_code}\n' https://docs.main.localhost/ # → 200
Même contrôle pour la boucle applicative sur le site de démonstration — toujours sans -k, puisque le certificat vaut maintenant pour le nom demandé :
Could not resolve host n'est pas un échec du proxy
Sur un hôte sans systemd-resolved, les navigateurs résolvent les noms en .localhost mais pas curl. castor proxy:status sonde ce point et imprime la ligne /etc/hosts à ajouter — c'est le seul cas où une configuration système reste nécessaire.
Migrer un poste existant vers les URLs app.¶
Vous aviez déjà démarré le dépôt avant le renommage des URLs de développement. Quatre noms ont changé, et un rechargement de la configuration du proxy ne suffit pas : les alias réseau des conteneurs et le domaine du site de démonstration sont hors de sa portée.
| Avant | Après |
|---|---|
https://<worktree>.localhost |
https://app.<worktree>.localhost |
https://demo.localhost |
https://app.demo.localhost |
https://local.localhost, https://docs.local.localhost |
https://app.main.localhost, https://docs.main.localhost |
https://mailpit.localhost |
https://mailpit.main.localhost (le bloc mailpit.localhost a été retiré) |
Cinq étapes, dans cet ordre — l'ordre n'est pas cosmétique, les deux dernières dépendent de ce que la troisième a posé :
# 1. HÔTE — régénère 01-main.caddy et le repli, puis recharge le proxy
castor proxy:up
# 2. HÔTE, à la racine du dépôt principal — recrée les conteneurs pour qu'ils
# prennent les alias réseau `php-main` et `docs-main`
castor docker:up
# 3. HÔTE — une fois par worktree déjà créé (remplacer TICKET)
castor wt:up TICKET
# 4. HÔTE — LECTURE SEULE : relève, section « Sites chargés », le worktree qui
# sert `app.demo.localhost`. Ce n'est pas forcément le dépôt principal.
castor proxy:status
# 5. HÔTE, à la racine du dépôt principal — repasse le site de démonstration sur
# `app.demo.localhost` en rechargeant les fixtures de LA base relevée en 4.
# Une seule des deux lignes, selon le nom obtenu — et les deux PURGENT
# la base ciblée (détail dans la sous-section ci-dessous).
castor fixtures:load # si l'étape 4 a rendu `main`
castor wt:up WORKTREE --fixtures # si elle a rendu un nom de worktree
Chacune répare une panne distincte, et aucune ne rattrape l'autre :
- Sans l'étape 2, le proxy sert un TLS parfaitement valide puis cherche un upstream
php-mainque personne ne porte :502sur tout le dépôt principal. Les conteneurs lancés avant le renommage répondent encore àphp-local— un alias que plus aucune conf ne vise. - Sans l'étape 3, le worktree garde un fichier de site à l'ancien nommage et un
.env.worktreedontKIREXO_RESERVED_DOMAINSne contient pasapp.<worktree>.localhost.wt:upréécrit l'un et réconcilie l'autre ; sans lui, la résolutionHost → Siteprend l'URL de l'application du worktree pour celle d'un site public et rend404sur toutes ses routes,/logincompris, pendant que le proxy répond parfaitement. - Sans l'étape 5, le
Sitede démonstration reste mappé en base sur l'ancien domaine :404surhttps://app.demo.localhost, servi par un proxy qui, lui, route correctement. L'étape 4 ne le répare pas :castor proxy:statusest un diagnostic en lecture seule, il ne touche à aucune base. Il sert à savoir laquelle l'étape 5 doit viser.
Rien à faire côté trust store : castor cert:trust est inchangé, la racine installée couvre les nouveaux noms comme les anciens. Si un navigateur garde une exception de sécurité acceptée du temps de l'ancien nommage, elle porte sur un nom qui n'est plus servi : elle est sans effet, son retrait est un nettoyage.
Le 308 de https://localhost reste en cache dans le navigateur
Avant le renommage, le repli redirigeait https://localhost en 308 — une redirection permanente, donc mise en cache durablement par Chrome comme par Firefox — vers https://<worktree par défaut>.localhost, soit https://local.localhost quand ce défaut était le dépôt principal. Un navigateur qui a visité cette URL rejoue la redirection mémorisée sans interroger le proxy : rouvrir https://localhost après la migration renvoie encore sur l'ancien nom.
Or ce nom n'a plus de bloc de site. Il retombe sous le joker *.localhost du repli (infra/proxy/fallback.caddy.tpl), donc sur le certificat wildcard : avertissement de sécurité, exactement ce que la migration supprime. Et si le worktree par défaut n'est pas le dépôt principal, son KIREXO_RESERVED_DOMAINS ne porte pas ce nom, contrairement à celui du dépôt principal qui le garde pour les signets : la résolution Host → Site le prend alors pour un domaine de site public et rend 404 sur toutes les routes, par-dessus l'avertissement.
Deux remèdes, l'un ou l'autre :
- viser directement la nouvelle URL,
https://app.<worktree par défaut>.localhost— le nom relevé à l'étape 4 ; - vider le cache du navigateur, où la redirection permanente est stockée avec les autres réponses HTTP. Pour seulement vérifier sans y toucher, une fenêtre de navigation privée suffit : son cache est vierge.
Le gabarit à jour redirige https://localhost vers https://app.<worktree par défaut>.localhost : un premier chargement hors cache réamorce la bonne cible, et le signet redevient utilisable.
Étapes 4 et 5 — sur quelle base recharger les fixtures¶
Le domaine du site de démonstration est porté par la base de données, et pas par celle du dépôt principal « par défaut » : app.demo.localhost (SiteFixtures::DEMO_HOST, src/DataFixtures/SiteFixtures.php) est servi par le worktree par défaut du repli, or database est un service par projet Compose. La base à recharger est donc celle de ce worktree-là ; recharger le dépôt principal purgerait une base qui ne sert pas le site de démonstration et laisserait le 404 intact.
L'étape 3 peut par ailleurs faire basculer ce rôle : wt_reconcile_proxy (castor/worktree.php) reprend la désignation du défaut dès que le routage effectif vaut - ou le nom du dépôt principal — exactement l'état que laisse l'étape 1, et aussi celui d'un marqueur périmé, rabattu sur le dépôt principal (cf. Les trois cas où wt:up reprend le rôle de worktree par défaut). Le premier castor wt:up de la migration devient donc le worktree par défaut. D'où l'ordre : on ne relève le défaut qu'après avoir rejoué tous les worktrees.
Étape 4 — relever le nom. castor proxy:status l'affiche, section « Sites chargés » :
La commande peut aussi imprimer deux lignes. Dès qu'une ligne routage effectif apparaît, c'est elle qui fait foi — c'est ce nom-là que le proxy applique, et donc la base que l'étape 5 doit viser. La ligne du marqueur, elle, décrit l'état du fichier 00-fallback.caddy et prend deux formulations selon la divergence constatée : (PÉRIMÉ — aucune conf de site) quand il désigne un worktree qui n'a plus de conf, aucun worktree désigné quand il ne désigne rien. Aucune des deux ne change la consigne. Détail des trois états : Les trois états du worktree par défaut.
worktree par défaut : aucun worktree désigné
routage effectif : main (sa conf de site existe) — relance `castor proxy:up`
Étape 5 — recharger. Selon le nom obtenu, et une seule de ces commandes :
| Nom retenu à l'étape 4 | Commande à jouer |
|---|---|
main — le dépôt principal |
castor fixtures:load, depuis la racine du dépôt principal |
| un worktree | castor wt:up WORKTREE --fixtures |
- — aucun |
rien à recharger : le repli est alors dans sa variante « aucun worktree démarré », qui ne déclare aucun bloc app.demo.localhost. Le nom n'est pas servi du tout, et c'est un castor wt:up TICKET qui reprend la désignation. |
Les deux commandes ne sont pas interchangeables. castor fixtures:load s'exécute dans le conteneur php du projet Compose du répertoire courant : jouée ailleurs qu'à la racine du dépôt principal, elle purgerait une autre base que celle visée. castor wt:up, lui, sait viser la stack du worktree nommé, quel que soit le répertoire d'appel.
L'option --fixtures n'est pas facultative sur un worktree : infra/worktree/bootstrap-data.sh ne charge les fixtures que sur une base vierge, un castor wt:up nu laisse donc le domaine du site de démonstration sur son ancienne valeur — cf. Quand les fixtures sont chargées.
Ces deux commandes PURGENT la base ciblée
Sans --append, doctrine:fixtures:load vide la base avant de recharger — c'est vrai de castor fixtures:load comme de castor wt:up --fixtures. Sur une base où vous avez du travail en cours, préférez corriger le domaine du site de démonstration à la main plutôt que de tout repartir de zéro.
Voir aussi¶
- Routage des worktrees : DNS, TLS et cloisonnement réseau — pourquoi le TLS de dev est terminé par un proxy hôte et pourquoi la CA ne s'installe qu'une fois.
- Commandes Castor — Proxy hôte —
proxy:up,proxy:reload,proxy:down,proxy:status,cert:trust. - Premier démarrage pour développer — mise en route du dépôt.