Servir les domaines de site en HTTPS¶
Vous administrez une instance Kirexo et vos utilisateurs publient leur site sur leur propre domaine (par exemple blog.example.net) : cette recette rend ces domaines joignables en HTTPS.
HTTPS est la version chiffrée du web : le navigateur n'affiche un site en HTTPS que si le serveur présente un certificat TLS valide pour ce domaine, c'est-à-dire un fichier délivré par une autorité reconnue (ici Let's Encrypt, gratuite et automatique) qui prouve que le serveur répond bien pour ce nom.
Principe¶
Le domaine d'un site se déclare dans l'espace de rédaction, carnet par carnet (Configurer le site web d'un carnet), et Kirexo l'associe au bon site. Le certificat de ce domaine, lui, est obtenu par ce qui se trouve devant Kirexo et reçoit les visites. C'est donc l'entrée HTTP choisie à l'installation qui décide de ce que vous avez à faire.
Prérequis¶
- Une instance installée en suivant Installer Kirexo chez soi, dont vous connaissez l'entrée HTTP (A1, A2, B ou C, décrites dans Choisir l'entrée HTTP de son instance).
- Le domaine du site déclaré dans l'espace de rédaction par son auteur.
- Le DNS du domaine (l'annuaire qui relie un nom à l'adresse d'un serveur) qui pointe vers votre serveur, ou vers votre proxy inverse si un logiciel comme Traefik ou Nginx reçoit les visites avant Kirexo : enregistrements A, et AAAA si le serveur a une adresse IPv6.
Toutes les commandes se lancent depuis le répertoire d'installation, par exemple /opt/kirexo.
Selon votre entrée HTTP¶
| Entrée HTTP | Qui obtient le certificat du domaine de site | Ce que vous avez à faire |
|---|---|---|
| A1 — Kirexo seul (défaut) | personne : les domaines de site ne sont pas servis en HTTPS | passer en A2 |
| A2 — Kirexo seul, avec certificats à la demande | Kirexo, automatiquement, à la première visite | rien, une fois le domaine déclaré et son DNS en place |
| B — derrière un Traefik existant | Traefik | ajouter le domaine à la règle Traefik dans .env |
| C — derrière un proxy existant | votre proxy | configurer le proxy pour ce domaine |
A1 — Kirexo seul¶
Dans cette configuration, Kirexo obtient seul le certificat du domaine de l'application (KIREXO_DOMAIN), et seulement celui-là. Un domaine de site s'ouvre en HTTP, mais pas en HTTPS.
Pour servir les domaines de site en HTTPS, passez en A2 : le bloc de lignes à poser dans .env est dans A2 — Kirexo seul, avec certificats à la demande. Le passage ne demande ni nouveau téléchargement ni nouvelle installation.
A2 — Certificats à la demande¶
Kirexo demande un certificat à Let's Encrypt la première fois qu'un domaine de site déclaré reçoit une visite, puis le renouvelle seul. Avant chaque demande, il vérifie que ce domaine est bien déclaré dans l'application, ou qu'il est le domaine de l'application : un domaine inconnu n'obtient jamais de certificat.
Rien à faire pour un nouveau domaine, à deux conditions :
- le domaine est déclaré dans l'espace de rédaction avant la première visite ;
- son DNS pointe déjà vers votre serveur.
Les certificats sont conservés dans le volume Docker kirexo_caddy_data (l'espace de stockage que Docker garde d'un redémarrage à l'autre) : pensez à le sauvegarder après l'ajout de domaines, comme décrit dans Sauvegarder et restaurer son instance.
B — Derrière un Traefik existant¶
Traefik ne demande pas de certificat à la volée : chaque domaine de site doit figurer dans la règle de routage KIREXO_TRAEFIK_RULE de .env. La règle est une liste de Host(`…`) reliés par || (« ou »).
Pour ajouter le domaine de site blog.example.net, remplacez la ligne KIREXO_TRAEFIK_RULE de .env par :
en remplaçant kirexo.example.org par le domaine de votre application et blog.example.net par le domaine du site. Pour un domaine de plus, ajoutez un autre || Host(`…`) avant le guillemet final.
Puis appliquez :
Résultat attendu : la commande recrée le service php et rend la main sans erreur. Traefik obtient ensuite le certificat du nouveau domaine avec son propre résolveur de certificats (KIREXO_TRAEFIK_CERTRESOLVER).
C — Derrière un proxy existant¶
Votre proxy (Nginx, Caddy, HAProxy…) obtient et présente les certificats : Kirexo n'en gère aucun. Pour chaque domaine de site, configurez le proxy comme pour le domaine de l'application :
- obtenir un certificat pour ce domaine, avec l'outil habituel de votre proxy ;
- relayer les visites vers Kirexo, à l'adresse locale choisie à l'installation (
http://127.0.0.1:8080dans l'exemple de Choisir l'entrée HTTP de son instance) ; - transmettre l'en-tête
Hostd'origine (le nom de domaine demandé par le navigateur), c'est lui qui permet à Kirexo de reconnaître le site.
Pour Caddy, Nginx, Apache et Nginx Proxy Manager, la marche à suivre est dans la sous-section « Ajouter un domaine de site » de chaque configuration de Installer Kirexo derrière un reverse proxy.
Vérifier¶
Kirexo répond, sur chaque domaine de site, à une adresse de contrôle /.kirexo/health. Depuis n'importe quel ordinateur, en remplaçant blog.example.net par le domaine du site :
Résultat attendu, une ligne de la forme :
Le champ site porte l'identifiant du site que Kirexo a reconnu pour ce domaine. Cette réponse prouve que le certificat est valide (sinon curl se serait arrêté avant), que le domaine arrive bien jusqu'à Kirexo et qu'il est rattaché à un site.
Si vous obtenez :
- une erreur de certificat ou de connexion sécurisée (en A2) : Kirexo n'a pas obtenu le certificat. Vérifiez que le domaine est déclaré dans l'espace de rédaction, que son DNS pointe vers le serveur, que les lignes du bloc A2 sont toutes présentes dans
.env, et, si vous avez définiTRUSTED_HOSTS, la section suivante. Les messages de Let's Encrypt apparaissent dansdocker compose logs php; - une page d'erreur
404: la requête arrive bien à Kirexo, mais il ne reconnaît pas ce domaine comme domaine de site. Soit le domaine n'est pas déclaré dans l'espace de rédaction (ou il y est écrit autrement), soit son DNS pointe vers un autre serveur que le vôtre. L'adresse de contrôle ne répond que sur un domaine de site déclaré : sur le domaine de l'application, elle renvoie elle aussi cette page404.
Si vous définissez TRUSTED_HOSTS¶
TRUSTED_HOSTS est un filtre facultatif sur les noms de domaine que Kirexo accepte de servir. Par défaut, il n'est pas défini et Kirexo ne filtre aucun nom : rien à faire dans ce cas, et c'est le réglage recommandé.
Avec TRUSTED_HOSTS, php et chaque domaine de site doivent y figurer
En A2, avant de demander un certificat, Kirexo s'interroge lui-même sous le nom interne php. Un TRUSTED_HOSTS qui n'accepte pas php fait refuser cette vérification par une erreur 400 : aucun certificat n'est émis.
Le même filtre doit aussi accepter chaque domaine de site, sans quoi ces sites répondent 400 eux aussi.
TRUSTED_HOSTS est une expression régulière, c'est-à-dire un motif qui décrit les noms acceptés. Si vous le définissez dans .env, faites-y figurer php, le domaine de l'application et chaque domaine de site, entre guillemets simples (un $ hors guillemets simples serait interprété par Docker Compose) :
en remplaçant kirexo\.example\.org par le domaine de votre application et blog\.example\.net par vos domaines de site, chaque point précédé de \, séparés par |. Ce motif est à mettre à jour à chaque nouveau domaine de site : c'est pourquoi le laisser non défini est plus simple. Ce que Kirexo fait d'un domaine inconnu quand le filtre est absent : Pourquoi TRUSTED_HOSTS n'est pas le filtre des Host en production.
Puis appliquez :
Le rôle de chaque variable citée ici est décrit dans Paramètres de l'instance.
Pour le mainteneur et les développeurs¶
Cette section ne concerne pas une instance installée avec le bundle.
Pile du mainteneur (compose.prod.yaml)¶
Le déploiement du mainteneur depuis le dépôt (compose.yaml + compose.prod.yaml) correspond à l'entrée B : Traefik termine le TLS (Let's Encrypt, labels certresolver=letsencrypt de compose.prod.yaml) et relaie en clair vers Caddy. compose.prod.yaml fixe KIREXO_ONDEMAND_TLS_ENABLED=0 ; CADDY_ONDEMAND_TLS_GLOBAL et CADDY_ONDEMAND_TLS_SITE restent vides, donc inertes. Les variables vivent dans l'environnement persistant du serveur : voir Déployer Kirexo en production, et leur sémantique dans Variables d'environnement du dépôt — FrankenPHP / Caddy.
Côté code :
- l'endpoint
askconsulté par Caddy avant chaque émission à la demande estsrc/Plugin/Web/src/Controller/WebPluginTlsAskController.php. Il répond200pour un domaine mappé à unSiteou réservé à l'application (KIREXO_RESERVED_DOMAINS),403sinon, et403pour tout domaine tant queKIREXO_ONDEMAND_TLS_ENABLEDvaut0. La décision « domaine réservé » est celle deSiteResolver::isAppDomain()(src/Plugin/Web/src/Service/SiteResolver.php). Pourquoi l'endpoint autorise aussi les domaines réservés : L'endpointaskautorise les domaines réservés ; - la sonde
/.kirexo/healthestsrc/Plugin/Web/src/Controller/WebPluginPublicHealthController.php.
En développement¶
En développement, le TLS de tous les noms en .localhost, domaines de site compris, est assuré par le proxy Caddy hôte et sa CA locale : voir Installer la CA du proxy de développement et migrer un poste existant.
Voir aussi¶
- Choisir l'entrée HTTP de son instance — les quatre entrées A1, A2, B et C, et les lignes
.envde chacune. - Paramètres de l'instance — chaque réglage de
.env, dontKIREXO_TRAEFIK_RULEetTRUSTED_HOSTS. - Configurer le site web d'un carnet — déclarer le domaine d'un site.
- Référence — Domaines de site — les règles du rattachement de domaine.
- Trois entrées HTTP, un seul fichier Compose — pourquoi ces quatre entrées.
- Multi-tenant : résolution d'un domaine vers un site — comment Kirexo associe un domaine à un site.