Aller au contenu

Choisir l'entrée HTTP de son instance

Vous hébergez votre propre instance de Kirexo et vous voulez décider de ce qui reçoit les visites sur votre serveur : Kirexo seul, ou un proxy déjà en place (Traefik, Nginx, Caddy, HAProxy…).

Prérequis : les fichiers compose.yaml et .env sont dans le répertoire d'installation, comme après l'étape 2 de Installer Kirexo chez soi. Toutes les commandes se lancent depuis ce répertoire.

Principe

Un proxy est un logiciel qui reçoit les visites sur les ports 80 (HTTP) et 443 (HTTPS) et les relaie à l'application. Le TLS est le chiffrement de HTTPS ; il repose sur un certificat, que fournit gratuitement Let's Encrypt. « Terminer le TLS », c'est détenir ce certificat et déchiffrer les visites.

Kirexo sert deux sortes de domaines :

  • le domaine de l'application (administration, espace de rédaction), déclaré dans .env par KIREXO_DOMAIN ;
  • les domaines de site de vos utilisateurs, par exemple blog.example.net, déclarés dans l'application et jamais dans .env.

Ce qui se trouve devant Kirexo doit donc accepter des domaines qu'il ne connaît pas à l'avance. Quatre configurations le permettent :

Configuration Qui reçoit les visites Choisissez-la si
A1 Kirexo seul Kirexo est seul sur le serveur et vos utilisateurs n'ont pas de domaine de site en HTTPS
A2 Kirexo seul, certificats de site émis à la demande Kirexo est seul sur le serveur et vos utilisateurs publient sur leurs propres domaines
B Votre Traefik Un Traefik occupe déjà les ports 80 et 443
C Votre Nginx, Caddy, HAProxy… Un autre proxy occupe déjà les ports 80 et 443

Chaque configuration correspond à un bloc de lignes commentées dans .env.example. Les lignes à poser dans .env sont recopiées ci-dessous : décommentez toutes les lignes du bloc choisi, et d'aucun autre. Ne modifiez jamais compose.yaml : il se remplace à chaque mise à jour. Le serveur web intégré à Kirexo, Caddy, reste toujours en place ; seul change ce qui se trouve devant lui.

Après toute modification de .env sur une instance déjà démarrée, appliquez :

docker compose up -d

A1 — Kirexo seul (défaut)

Lignes à poser dans .env : aucune. Les défauts s'appliquent : KIREXO_HTTP_PORT=80, KIREXO_HTTPS_PORT=443, KIREXO_BIND_ADDRESS vide (toutes les interfaces réseau, IPv4 et IPv6), SERVER_NAME égal à KIREXO_DOMAIN.

Résultat : Kirexo obtient seul le certificat Let's Encrypt de KIREXO_DOMAIN et redirige HTTP vers HTTPS.

Avant de démarrer en A1

Les ports 80 et 443 doivent être joignables depuis Internet et le DNS en place avant le démarrage. Limite : les sites publics sur un domaine de site ne sont pas servis en HTTPS ; pour cela, passez en A2. Le volume kirexo_caddy_data, qui conserve les certificats, est à sauvegarder : voir Sauvegarder et restaurer son instance.

A2 — Kirexo seul, avec certificats à la demande

Lignes à poser dans .env, en remplaçant kirexo.example.org par la valeur de KIREXO_DOMAIN :

SERVER_NAME='kirexo.example.org, :443'
KIREXO_ONDEMAND_TLS_ENABLED=1
CADDY_ONDEMAND_TLS_GLOBAL='on_demand_tls { ask http://php/.well-known/kirexo/on-demand-tls }'
CADDY_ONDEMAND_TLS_SITE='tls { on_demand }'

Résultat : en plus de A1, Kirexo obtient un certificat à la première visite de chaque domaine de site déclaré dans l'application, jamais pour un domaine inconnu.

Avant la première visite d'un domaine de site

Le domaine de site doit être déclaré dans l'application et son DNS en place avant la première visite. Si vous définissez TRUSTED_HOSTS, il doit accepter php, sinon aucun certificat n'est émis.

Suite : Servir les domaines de site en HTTPS.

B — Derrière un Traefik existant

Un Traefik que vous administrez occupe déjà les ports 80 et 443 : il obtient les certificats et relaie les visites à Kirexo, qu'il découvre sur son réseau Docker. Les lignes à poser dans .env, la façon de retrouver les noms propres à votre Traefik et l'ajout d'un domaine de site sont dans Installer Kirexo derrière un reverse proxy, section Traefik.

C — Derrière un proxy existant

Pour Nginx, Caddy, HAProxy ou tout autre proxy. Cette configuration s'adresse à vous si vous administrez déjà ce proxy. Si ce n'est pas votre cas et qu'un serveur web installé d'office (Apache ou Nginx sans site) occupe les ports 80 et 443, arrêtez-le et restez en A1.

Lignes à poser dans .env :

SERVER_NAME=:80
KIREXO_BIND_ADDRESS=127.0.0.1
KIREXO_HTTP_PORT=8080
KIREXO_HTTPS_PORT=8443
TRUSTED_PROXIES=127.0.0.0/8,10.0.0.0/8,172.16.0.0/12,192.168.0.0/16

Avec ces lignes, Kirexo n'écoute que sur 127.0.0.1 : seul le serveur lui-même peut le joindre. Un proxy installé sur une autre machine demande en plus KIREXO_BIND_ADDRESS égal à une adresse du serveur que cette machine peut joindre (une adresse privée de préférence), et l'adresse de cette machine dans TRUSTED_PROXIES.

Résultat : le proxy termine le TLS pour tous les domaines servis et relaie vers http://127.0.0.1:8080. Le certificat de votre domaine est alors obtenu par votre proxy, pas par Kirexo : à l'étape 3 de Installer Kirexo chez soi, ce qui porte sur le certificat ne s'applique pas tel quel. Un avertissement de sécurité dans le navigateur se règle dans la configuration de votre proxy.

La configuration à écrire dépend de votre proxy : Installer Kirexo derrière un reverse proxy en donne une, complète, pour Caddy, Nginx, Apache et Nginx Proxy Manager, avec les lignes à ajouter quand le proxy tourne lui-même dans Docker. Toute configuration doit respecter ces trois exigences.

Ce que le proxy doit faire

  1. Transmettre les en-têtes du visiteur : l'en-tête Host d'origine (le nom de domaine demandé par le visiteur), et les en-têtes X-Forwarded-Proto et X-Forwarded-For (le protocole et l'adresse IP du visiteur).
  2. Ne pas mettre en tampon /.well-known/mercure : c'est le flux temps réel de l'éditeur, il doit arriver au navigateur au fil de l'eau.
  3. Accepter les domaines de site de vos utilisateurs, en plus de KIREXO_DOMAIN, et obtenir leurs certificats.

Vérifier

Une fois l'instance démarrée, ouvrez https://kirexo.example.org/admin/login (avec votre domaine) : la page de connexion s'affiche, avec un cadenas dans la barre d'adresse. Puis lancez le diagnostic décrit dans Vérifier l'installation.

Voir aussi