Installer Kirexo derrière un reverse proxy¶
Vous administrez un reverse proxy qui occupe déjà les ports 80 et 443 du serveur, et vous voulez qu'il serve aussi Kirexo.
Prérequis : les étapes 1 et 2 de Installer Kirexo chez soi sont faites. Les commandes docker compose se lancent depuis le répertoire d'installation.
Pour chaque proxy : posez les lignes .env, configurez le proxy, démarrez Kirexo (étape 3 du tutoriel, ou docker compose up -d sur une instance qui tourne déjà), puis vérifiez. Le certificat est obtenu par le proxy, jamais par Kirexo. Une variable déjà active dans .env se remplace : chacune n'y apparaît qu'une fois.
Dans les blocs, remplacez VOTRE_DOMAINE par la valeur de KIREXO_DOMAIN, DOMAINE_DE_SITE par un domaine de site déclaré dans l'espace de rédaction, et NOM_DU_RESEAU par le réseau Docker de votre proxy.
Ce que tout reverse proxy doit faire¶
- Transmettre
Hostd'origine,X-Forwarded-ProtoetX-Forwarded-For: sansHost, Kirexo ne reconnaît ni son domaine ni les domaines de site ; sansX-Forwarded-Proto, il se croit servi en HTTP. - Ne pas mettre en tampon
/.well-known/mercure: le flux temps réel de l'éditeur (text/event-stream) doit arriver au fil de l'eau, sur une connexion longue. - Servir et certifier chaque domaine de site en plus de
VOTRE_DOMAINE.
Où relayer les visites¶
| Votre reverse proxy | Adresse de Kirexo | Lignes de .env |
|---|---|---|
| Installé sur le serveur (paquet, binaire) | http://127.0.0.1:8080 |
bloc « sur le serveur » |
| Lancé dans un conteneur Docker | http://kirexo:80 |
bloc « dans Docker » |
Bloc « sur le serveur » :
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
Bloc « dans Docker » : les mêmes lignes, plus deux.
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
KIREXO_EDGE_EXTERNAL=true
KIREXO_EDGE_NETWORK=NOM_DU_RESEAU
Kirexo rejoint alors le réseau NOM_DU_RESEAU sous le nom kirexo, port 80. Ce réseau doit exister avant docker compose up, et ne peut être ni bridge, ni host, ni none. Un proxy lancé par docker run sans --network n'est que sur bridge : créez-lui un réseau.
Un proxy en network_mode: host prend le bloc « sur le serveur » et relaie vers http://127.0.0.1:8080 (pour Traefik avec fournisseur Docker : Traefik en réseau host). Un proxy sur une autre machine : KIREXO_BIND_ADDRESS égal à une adresse du serveur joignable par lui, et son adresse dans TRUSTED_PROXIES.
Les ports 8080 et 8443 de l'hôte doivent être libres ; le tableau de bord de Traefik occupe souvent le 8080. Sinon, changez KIREXO_HTTP_PORT et KIREXO_HTTPS_PORT, et reportez le premier dans toute adresse 127.0.0.1:8080 de la configuration du proxy. L'adresse kirexo:80 ne change pas.
Traefik¶
Configuration testée à chaque version de Kirexo
Avant chaque version, un test automatique installe Kirexo derrière Traefik 3 avec exactement les lignes ci-dessous. Il vérifie la page de connexion, la connexion, que Kirexo se sait servi en HTTPS, le flux temps réel, et qu'un domaine de site présent dans la règle est servi alors qu'un domaine absent ne l'est pas. L'obtention du certificat par votre résolveur n'en fait pas partie.
Cas couvert : Traefik dans Docker, fournisseur Docker activé. Traefik lit les étiquettes que porte déjà compose.yaml : rien à écrire côté Traefik. Avec Docker 29 ou plus récent, il faut Traefik 3.6.1 ou plus récent (sinon, client version … is too old dans son journal).
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
KIREXO_TRAEFIK_ENABLE=true
KIREXO_EDGE_EXTERNAL=true
KIREXO_EDGE_NETWORK=traefik
KIREXO_TRAEFIK_ENTRYPOINTS=websecure
KIREXO_TRAEFIK_CERTRESOLVER=letsencrypt
KIREXO_TRAEFIK_RULE='Host(`VOTRE_DOMAINE`)'
Remplacez traefik (réseau Docker de Traefik), websecure (point d'entrée HTTPS) et letsencrypt (résolveur de certificats) par les noms de votre Traefik. La redirection HTTP vers HTTPS reste dans votre Traefik. Les ports 127.0.0.1:8080 et 8443 ne servent qu'au diagnostic depuis le serveur.
Ajouter un domaine de site¶
Traefik n'émet pas de certificat à la demande : chaque domaine de site s'ajoute à la règle.
Puis docker compose up -d. Le certificat arrive en une à deux minutes ; un domaine absent de la règle reçoit 404 page not found de Traefik. Vérification : Vérifier un domaine de site.
Traefik en réseau host¶
Non couvert par le test. Posez le même bloc sans KIREXO_EDGE_EXTERNAL ni KIREXO_EDGE_NETWORK (supprimez-les s'ils sont déjà actifs) : Kirexo crée son propre réseau kirexo_edge, que Traefik joint depuis l'hôte. Le reste est identique.
Traefik sans fournisseur Docker¶
Non couvert par le test : configuration de référence, recoupée avec la documentation de Traefik. Posez le bloc « sur le serveur » (Traefik hors Docker) ou « dans Docker » (Traefik conteneurisé), sans KIREXO_TRAEFIK_ENABLE, puis déposez ce fichier dans le dossier du fournisseur fichier :
http:
routers:
kirexo:
rule: "Host(`VOTRE_DOMAINE`)"
entryPoints:
- websecure
service: kirexo
tls:
certResolver: letsencrypt
services:
kirexo:
loadBalancer:
servers:
- url: "http://127.0.0.1:8080"
Traefik conteneurisé : http://kirexo:80. Un domaine de site s'ajoute à rule comme ci-dessus, sans relancer Kirexo. Documentation : Traefik (File provider, routers et services HTTP).
Caddy¶
Configuration de référence, non testée automatiquement : signalez un écart sur le dépôt
Elle suit la documentation officielle de Caddy.
Bloc « sur le serveur », puis dans le Caddyfile :
Caddy transmet les en-têtes, relaie text/event-stream sans tampon et obtient seul les certificats. Caddy dans Docker : bloc « dans Docker » et reverse_proxy kirexo:80.
Ajouter un domaine de site¶
Puis rechargez Caddy. Documentation : reverse_proxy, HTTPS automatique.
Nginx¶
Configuration de référence, non testée automatiquement : signalez un écart sur le dépôt
Elle suit la documentation officielle de Nginx et de Certbot.
Bloc « sur le serveur », puis ce bloc server :
server {
listen 80;
listen [::]:80;
server_name VOTRE_DOMAINE;
# Déclarés au niveau server pour valoir dans les deux location : un location
# qui déclarerait son propre proxy_set_header les perdrait tous.
proxy_http_version 1.1;
proxy_set_header Connection "";
proxy_set_header Host $host;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
proxy_set_header X-Forwarded-Proto $scheme;
location / {
proxy_pass http://127.0.0.1:8080;
}
# Flux temps réel de l'éditeur : sans tampon, connexion longue.
location /.well-known/mercure {
proxy_pass http://127.0.0.1:8080;
proxy_buffering off;
proxy_cache off;
proxy_read_timeout 24h;
}
}
Certificat et redirection vers HTTPS :
Sans Certbot, ajoutez vos lignes listen 443 ssl, ssl_certificate et ssl_certificate_key au bloc.
Nginx lancé dans Docker¶
Bloc « dans Docker ». Avec proxy_pass http://kirexo:80;, Nginx résoudrait kirexo une seule fois et répondrait 502 dès que Kirexo est recréé. Faites-le résoudre par le DNS de Docker : ajoutez resolver sous server_name et remplacez les deux location par :
resolver 127.0.0.11 valid=30s;
location / {
set $kirexo_upstream http://kirexo:80;
proxy_pass $kirexo_upstream;
}
# Flux temps réel de l'éditeur : sans tampon, connexion longue.
location /.well-known/mercure {
set $kirexo_upstream http://kirexo:80;
proxy_pass $kirexo_upstream;
proxy_buffering off;
proxy_cache off;
proxy_read_timeout 24h;
}
127.0.0.11 ne répond que sur un réseau créé par Compose ou docker network create, jamais sur bridge.
Ajouter un domaine de site¶
Ajoutez le domaine au server_name de chaque bloc server (celui du port 443 et celui de la redirection créée par Certbot), puis :
sudo nginx -t
sudo certbot --nginx --expand --redirect -d VOTRE_DOMAINE -d DOMAINE_DE_SITE
sudo systemctl reload nginx
Donnez à Certbot tous les domaines, l'ancien comme le nouveau. Documentation : ngx_http_proxy_module, Certbot.
Apache¶
Configuration de référence, non testée automatiquement : signalez un écart sur le dépôt
Elle suit la documentation officielle d'Apache et de Certbot.
Apache 2.4.10 ou plus récent, bloc « sur le serveur », modules proxy, proxy_http, headers et ssl activés (sudo a2enmod proxy proxy_http headers ssl), puis :
<VirtualHost *:80>
ServerName VOTRE_DOMAINE
# Host d'origine transmis tel quel ; X-Forwarded-For est ajouté d'office.
ProxyPreserveHost On
# http sur ce bloc, https sur la copie que Certbot crée pour le port 443.
RequestHeader set X-Forwarded-Proto expr=%{REQUEST_SCHEME}
# Flux temps réel de l'éditeur, AVANT la règle « / » : Apache applique la
# première règle qui correspond. Envoyé au fil de l'eau, connexion longue.
ProxyPass /.well-known/mercure http://127.0.0.1:8080/.well-known/mercure flushpackets=on timeout=86400
ProxyPass / http://127.0.0.1:8080/
ProxyPassReverse / http://127.0.0.1:8080/
</VirtualHost>
Certificat et redirection vers HTTPS :
Sans Certbot, ajoutez un <VirtualHost *:443> avec SSLEngine on, vos lignes de certificat et les cinq lignes Proxy…/RequestHeader du bloc ci-dessus.
Ajouter un domaine de site¶
Ajoutez ServerAlias DOMAINE_DE_SITE dans les deux VirtualHost (port 80 et port 443). Certbot ne retouche pas la redirection qu'il a déjà posée : terminez sa dernière ligne RewriteCond par [OR] et ajoutez dessous RewriteCond %{SERVER_NAME} =DOMAINE_DE_SITE. Puis :
sudo apachectl configtest
sudo systemctl reload apache2
sudo certbot --apache --expand --redirect -d VOTRE_DOMAINE -d DOMAINE_DE_SITE
Documentation : mod_proxy, mod_headers, Certbot.
Nginx Proxy Manager¶
Configuration de référence, non testée automatiquement : signalez un écart sur le dépôt
Elle suit la documentation officielle et les modèles de configuration de Nginx Proxy Manager.
Bloc « dans Docker », avec le réseau de Nginx Proxy Manager. Démarrez Kirexo avant de créer l'hôte : le nom kirexo n'existe sur le réseau qu'une fois Kirexo démarré.
Hosts › Proxy Hosts › Add Proxy Host, onglet Details :
| Champ | Valeur |
|---|---|
| Domain Names | VOTRE_DOMAINE |
| Scheme | http |
| Forward Hostname / IP | kirexo |
| Forward Port | 80 |
Onglet SSL : Request a new Certificate, Force SSL. Onglet Advanced, Custom Nginx Configuration :
location /.well-known/mercure {
include conf.d/include/proxy.conf;
proxy_buffering off;
proxy_cache off;
proxy_read_timeout 24h;
}
En réseau host : bloc « sur le serveur », et 127.0.0.1 / 8080 dans Details.
Ajouter un domaine de site¶
Ajoutez-le dans Domain Names, puis redemandez un certificat (Request a new Certificate) : il couvre la liste complète. Documentation : Nginx Proxy Manager.
Vérifier¶
https://VOTRE_DOMAINE/admin/logins'affiche sans avertissement de certificat. Une502du proxy : Kirexo n'est pas joint (adresse de relais,docker compose ps,KIREXO_EDGE_NETWORK). Derrière Traefik,404 page not found: vérifiezKIREXO_TRAEFIK_ENABLE=true, le réseau etKIREXO_TRAEFIK_RULE.-
Le flux temps réel passe sans tampon :
Attendu : immédiatement
HTTP/… 200etcontent-type: text/event-stream(casse variable), puis coupure au bout de 5 secondes, normale. Rien avant la coupure : le proxy met/.well-known/mercureen tampon. 3. Le diagnostic de l'instance : Vérifier l'installation.
Vérifier un domaine de site¶
Attendu : {"site":"…","status":"ok"}. Juste après l'ajout, laissez une minute au certificat.
| Réponse | Cause |
|---|---|
| Erreur de certificat | Le proxy n'a pas (encore) le certificat de ce domaine, ou le DNS pointe ailleurs |
404 de Kirexo |
Domaine non déclaré dans l'espace de rédaction, ou écrit autrement |
404 page not found de Traefik |
Domaine absent de KIREXO_TRAEFIK_RULE |
| Page « Congratulations » de Nginx Proxy Manager | Domaine absent de Domain Names |
| Réponse d'un autre serveur | Le DNS pointe vers un autre serveur |
Détail : Servir les domaines de site en HTTPS.
Voir aussi¶
- Choisir l'entrée HTTP de son instance — les quatre configurations possibles.
- Paramètres de l'instance — chaque variable de l'entrée HTTP.