Aller au contenu

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

# HÔTE, à la racine du dépôt
castor proxy:up
castor cert:trust

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 passer security.enterprise_roots.enabled à true dans about: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 :

openssl x509 -in var/caddy-root.crt -noout -subject -fingerprint -sha1

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é :

# HÔTE
curl -sS https://app.demo.localhost/.kirexo/health                       # → {"site":"…","status":"ok"}

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-main que personne ne porte : 502 sur 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.worktree dont KIREXO_RESERVED_DOMAINS ne contient pas app.<worktree>.localhost. wt:up réécrit l'un et réconcilie l'autre ; sans lui, la résolution Host → Site prend l'URL de l'application du worktree pour celle d'un site public et rend 404 sur toutes ses routes, /login compris, pendant que le proxy répond parfaitement.
  • Sans l'étape 5, le Site de démonstration reste mappé en base sur l'ancien domaine : 404 sur https://app.demo.localhost, servi par un proxy qui, lui, route correctement. L'étape 4 ne le répare pas : castor proxy:status est 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 » :

worktree par défaut : ticket-185

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