Paramètres de l'instance (fichier .env)¶
Cette page s'adresse à vous si vous avez installé Kirexo avec les fichiers compose.yaml et .env téléchargés depuis la page des versions. Elle décrit chaque réglage de .env. Pour l'installation pas à pas : Installer Kirexo chez soi.
Lire les tableaux¶
Le fichier .env est un fichier texte, placé à côté de compose.yaml dans le répertoire d'installation : une ligne NOM=valeur par réglage. Une ligne qui commence par # est un commentaire, ignoré tant que vous ne retirez pas ce #.
Les tableaux suivent l'ordre de .env.example et ses intertitres. Une ligne par variable, y compris celles livrées en commentaire.
| Colonne | Contenu |
|---|---|
| Variable | Nom exact de la ligne dans .env |
| Statut | Obligatoire : sans elle, rien ne démarre. Optionnelle : une valeur par défaut s'applique. Dérivée : sa valeur par défaut est calculée à partir d'une autre variable, le plus souvent KIREXO_DOMAIN ; ne la renseignez que pour vous en écarter. A2, B, C : ne sert qu'avec l'entrée HTTP de ce nom, décrite dans Choisir l'entrée HTTP de son instance |
| Rôle | Ce que la variable règle |
| Ce qui casse | Le symptôme d'une valeur absente, fausse ou modifiée après coup |
« Compose refuse » signifie que docker compose refuse toute commande et nomme la variable en cause. Un secret est une valeur aléatoire que personne n'a besoin de connaître : vous le générez à l'installation (étape 2 du tutoriel), avec la commande openssl rand indiquée au-dessus de sa ligne dans .env.example.
Toute modification de .env sur une instance démarrée s'applique par :
Version¶
| Variable | Statut | Rôle | Ce qui casse |
|---|---|---|---|
KIREXO_VERSION |
Obligatoire (pré-remplie) | Version de Kirexo, épinglée : elle ne change que si vous la modifiez | Rien tant qu'elle n'est pas modifiée. Ne jamais mettre latest : vous perdez la maîtrise des mises à jour et du retour arrière. Version inexistante : manifest unknown au téléchargement des images. Pour changer de version : Mettre à jour son instance |
Domaine de l'application¶
Le domaine de l'application est celui où se trouvent la connexion, l'espace de rédaction et l'administration. Les domaines de site, où vos utilisateurs publient leurs articles, se déclarent dans l'application, jamais dans .env.
| Variable | Statut | Rôle | Ce qui casse |
|---|---|---|---|
KIREXO_DOMAIN |
Obligatoire — seule saisie de domaine | Domaine de l'application ; KIREXO_RESERVED_DOMAINS, DEFAULT_URI, MERCURE_PUBLIC_URL, SERVER_NAME et la règle Traefik en dérivent |
Vide (valeur livrée) ou absente : Compose refuse. Domaine faux : aucun certificat, application injoignable |
KIREXO_RESERVED_DOMAINS |
Optionnelle, dérivée de KIREXO_DOMAIN |
Domaine(s) de l'application, comparés par égalité exacte, séparés par des virgules | Domaine de l'application absent (par exemple un nom en www. ajouté au DNS mais pas ici) : ce domaine est pris pour un domaine de site, d'où un 404 sur toute l'application, /login compris, alors que le serveur répond. Ne jamais y mettre un domaine de site |
DEFAULT_URI |
Optionnelle, dérivée de KIREXO_DOMAIN (défaut : https:// suivi de KIREXO_DOMAIN) |
Adresse de base des liens envoyés par e-mail, dont le lien de réinitialisation du mot de passe | Fausse : lien de réinitialisation inutilisable, plus aucun moyen de récupérer un compte. Les liens d'invitation n'en dépendent pas : ils reprennent le domaine par lequel l'administrateur ouvre /admin |
MERCURE_PUBLIC_URL |
Optionnelle, dérivée de KIREXO_DOMAIN (défaut : https:// suivi de KIREXO_DOMAIN et de /.well-known/mercure) |
Adresse publique du temps réel (Mercure), utilisée par le navigateur | Fausse : enregistrement automatique de l'éditeur et mises à jour en direct cassés |
Entrée HTTP¶
L'entrée HTTP est ce qui reçoit les visites sur votre serveur : Kirexo lui-même (A1, A2), ou un proxy déjà en place, c'est-à-dire un logiciel qui reçoit les visites et les relaie à Kirexo (B pour Traefik, C pour Nginx, Caddy, HAProxy…). Le TLS est le chiffrement qui fait le « S » de HTTPS. Choix et lignes à poser : Choisir l'entrée HTTP de son instance.
| Variable | Statut | Rôle | Ce qui casse |
|---|---|---|---|
KIREXO_BIND_ADDRESS |
Optionnelle (défaut : vide = toutes les interfaces réseau, IPv4 et IPv6) | Adresse d'écoute des ports publiés sur le serveur. Une adresse IPv6 s'écrit entre crochets : [::1] |
En B ou C, laissée vide : l'application est joignable en clair depuis l'extérieur, en contournant le proxy |
KIREXO_HTTP_PORT |
Optionnelle (défaut 80) |
Port HTTP publié sur le serveur | Port déjà pris : le démarrage échoue (« address already in use ») |
KIREXO_HTTPS_PORT |
Optionnelle (défaut 443, TCP et UDP) |
Port HTTPS publié sur le serveur | Idem ; en B ou C, laisser 443 entre en conflit avec le proxy |
SERVER_NAME |
Optionnelle, dérivée de KIREXO_DOMAIN ; imposée en A2, B, C |
Noms servis par Caddy, le serveur web intégré à Kirexo | En B ou C laissée par défaut : Caddy tente d'obtenir un certificat derrière le proxy, redirections en boucle. En A2 sans :443 : aucun certificat de site |
KIREXO_ONDEMAND_TLS_ENABLED |
Optionnelle (défaut 0) ; 1 en A2 |
Autorise l'émission de certificats à la demande, à la première visite d'un domaine de site | À 0 en A2 : aucun certificat de domaine de site |
CADDY_ONDEMAND_TLS_GLOBAL |
A2 seulement | Déclare l'adresse que Caddy interroge avant d'émettre un certificat à la demande | Absente en A2 : aucun certificat de domaine de site |
CADDY_ONDEMAND_TLS_SITE |
A2 seulement | Active l'émission à la demande sur le site | Idem |
TRUSTED_PROXIES |
Optionnelle (défaut : vide) ; requise en B et C | Adresses des proxys de confiance, dont Kirexo accepte les indications sur le visiteur | En B ou C, absente ou fausse : protocole et adresse IP du visiteur faux (redirections vers HTTP, limitation des tentatives de connexion appliquée à la mauvaise adresse). En A1 ou A2, la renseigner permettrait à un visiteur de déclarer une fausse adresse IP |
KIREXO_TRAEFIK_ENABLE |
B seulement (défaut false) |
Annonce Kirexo à Traefik | À false en B : Traefik ignore Kirexo, 404 de Traefik |
KIREXO_EDGE_EXTERNAL |
B seulement (défaut false) |
Rejoint un réseau Docker existant au lieu d'en créer un | À false en B : Kirexo n'est pas sur le réseau de Traefik, erreur 502 |
KIREXO_EDGE_NETWORK |
B seulement (défaut kirexo_edge) |
Nom du réseau Docker de Traefik | Nom faux : le démarrage échoue (réseau introuvable) |
KIREXO_TRAEFIK_ENTRYPOINTS |
B seulement (défaut websecure) |
Point(s) d'entrée de votre Traefik | Nom différent de celui de votre Traefik : Kirexo n'est jamais servi |
KIREXO_TRAEFIK_CERTRESOLVER |
B seulement (défaut letsencrypt) |
Nom du fournisseur de certificats configuré dans votre Traefik | Nom faux : certificat par défaut de Traefik, avertissement du navigateur |
KIREXO_TRAEFIK_RULE |
B, optionnelle, dérivée de KIREXO_DOMAIN (défaut : Host(`KIREXO_DOMAIN`)) |
Règle qui dit à Traefik quels domaines envoyer à Kirexo | Domaine de site non ajouté à la règle : ce site est injoignable |
Secrets¶
Les cinq secrets obligatoires se génèrent à l'étape 2 du tutoriel, par la commande openssl rand commentée au-dessus de chacun dans .env.example. Ils font partie de la sauvegarde.
| Variable | Statut | Rôle | Ce qui casse |
|---|---|---|---|
APP_SECRET |
Obligatoire, secret | Signature des sessions de connexion, des jetons de protection des formulaires et des liens signés | Vide : Compose refuse. Valeur d'exemple publique recopiée : l'application refuse de démarrer. Changé après coup : sessions et liens en cours invalidés |
POSTGRES_PASSWORD |
Obligatoire, secret | Mot de passe de la base de données PostgreSQL | Vide : Compose refuse. Valeur d'exemple publique : l'application refuse de démarrer. Changé après le premier démarrage : sans effet sur la base existante, qui n'accepte plus l'application (à changer aussi dans PostgreSQL) |
POSTGRES_USER |
Optionnelle (défaut kirexo) |
Utilisateur de la base de données | Changé après le premier démarrage : l'application ne se connecte plus |
POSTGRES_DB |
Optionnelle (défaut kirexo) |
Nom de la base de données | Idem |
RABBITMQ_PASSWORD |
Obligatoire, secret | Mot de passe de RabbitMQ, la file qui transmet les tâches au worker (utilisateur kirexo par défaut) |
Vide : Compose refuse. guest : signalé par le diagnostic. Changé après le premier démarrage : sans effet sur RabbitMQ déjà initialisé, worker déconnecté |
RABBITMQ_USER |
Optionnelle (défaut kirexo) |
Utilisateur RabbitMQ | Changé après le premier démarrage : idem |
CADDY_MERCURE_JWT_SECRET |
Obligatoire, secret | Secret du temps réel (enregistrement automatique de l'éditeur) | Vide : Compose refuse. Valeur d'exemple publique : l'application refuse de démarrer |
CLAUDE_API_KEY_CIPHER_KEY |
Obligatoire, secret | Chiffre la clé API Claude saisie dans /admin/reglages |
Vide ou absente : Compose refuse toute commande. Valeur d'exemple publique : l'application refuse de démarrer. Changée : la clé API enregistrée devient illisible et doit être ressaisie. À conserver avec la même valeur pour toujours |
E-mails sortants¶
Un serveur SMTP est le service qui envoie les e-mails, fourni par votre hébergeur de messagerie.
| Variable | Statut | Rôle | Ce qui casse |
|---|---|---|---|
MAILER_DSN |
Obligatoire | Adresse du serveur SMTP, de la forme smtp://smtp.example.org:587. Si votre hébergeur vous a donné un identifiant et un mot de passe, insérez-les juste après smtp://, séparés par : et suivis de @. Dans l'identifiant et le mot de passe, les lettres, les chiffres et les caractères ., -, _ et ~ restent tels quels ; tout autre caractère s'encode : @ devient %40, : %3A, $ %24, # %23, / %2F, % %25… La valeur s'écrit sans guillemets. null://null désactive tout envoi, en connaissance de cause |
Vide : Compose refuse. Faux : aucun e-mail (invitations, réinitialisation du mot de passe) |
MAILER_FROM_ADDRESS |
Obligatoire | Adresse d'expédition ; l'expéditeur affiché est « Kirexo » suivi de cette adresse | Vide : Compose refuse. Adresse hors d'un domaine que vous gérez, ou non couverte par ses enregistrements SPF et DKIM (les déclarations DNS qui autorisent un serveur à envoyer pour ce domaine) : e-mails classés en spam ou rejetés |
Exploitation¶
Le worker est le service qui exécute les tâches en arrière-plan : envoi des e-mails, diffusion des articles, analyse IA, tâches périodiques.
| Variable | Statut | Rôle | Ce qui casse |
|---|---|---|---|
RUN_MIGRATIONS |
À laisser à 1 |
Met à jour automatiquement la structure de la base de données au démarrage (migrations) | À 0 : l'application démarre sur une structure périmée après une mise à jour |
TZ |
Optionnelle (livrée à UTC) |
Fuseau horaire de l'instance (nom IANA, par exemple Europe/Paris) |
Hors UTC non réglé : dates et heure des tâches planifiées décalées. Changé sur une instance existante : tout l'historique est décalé (dates stockées sans fuseau). Nom invalide (par exemple Europe/Pariss) : retour à UTC, avec un avertissement visible dans docker compose logs php |
KIREXO_WORKER_REPLICAS |
Optionnelle (livrée à 1) |
Nombre d'instances du worker | À 0 : ni e-mail, ni diffusion, ni analyse IA, ni purge. Au-delà de 1 : sans risque, tâches périodiques non doublées |
KIREXO_WORKER_TRANSPORTS |
À laisser commentée | Files de tâches traitées par le worker | Une file retirée : la fonction correspondante s'arrête sans erreur visible |
Observabilité¶
| Variable | Statut | Rôle | Ce qui casse |
|---|---|---|---|
SENTRY_DSN |
Facultative | Envoi des erreurs vers Sentry, un service de suivi des erreurs | Rien : les journaux restent lisibles avec docker compose logs |
GRAYLOG_HOST |
Facultative | Envoi des journaux vers Graylog, un service de centralisation des journaux | Rien (l'absence de Graylog n'est pas bloquante) |
GRAYLOG_PORT |
Facultative (défaut 12201) |
Port GELF (le format d'envoi) de Graylog | Faux : journaux non reçus par Graylog, application intacte |
Filtrage des hôtes¶
| Variable | Statut | Rôle | Ce qui casse |
|---|---|---|---|
TRUSTED_HOSTS |
À laisser non définie | Liste, sous forme d'expression régulière, des noms de domaine auxquels l'application accepte de répondre | Définie : elle doit accepter le domaine de l'application, php et chaque domaine de site, sinon erreur 400 sur les sites et aucun certificat en A2. Non définie est le réglage prévu : un domaine inconnu reçoit un 404, et le lien de réinitialisation passe toujours par DEFAULT_URI |
Protéger .env¶
chmod 600 .env: lisible par vous seul.- Jamais versionné, jamais partagé.
- Il fait partie de la sauvegarde : sans lui, sessions et secrets de l'instance sont perdus. Voir Sauvegarder et restaurer son instance.
- Un
$dans une valeur est interprété par Docker Compose. DansMAILER_DSN, il s'encode en%24, comme les autres caractères spéciaux (voir E-mails sortants), sans guillemets. Toute autre valeur saisie à la main qui contient un$s'entoure de guillemets simples, qui la rendent littérale.
Nombre de workers¶
Le worker traite en arrière-plan les e-mails, la diffusion des articles, l'analyse IA et les tâches périodiques (purge…). Pour en lancer plusieurs, réglez par exemple KIREXO_WORKER_REPLICAS=2 dans .env, puis appliquez :
Les tâches périodiques ne sont pas doublées : une seule instance les déclenche, les autres prennent le relais si elle s'arrête.
Pas de --scale
N'utilisez pas docker compose up --scale : la valeur de .env reviendrait au prochain up.
Ce que .env ne contient pas¶
- La clé API Claude n'est pas une variable : elle se saisit dans
/admin/reglages, où elle est stockée chiffrée parCLAUDE_API_KEY_CIPHER_KEY. L'analyse IA des articles reste optionnelle. - Aucun autre fichier n'est lu : Docker Compose ne lit que
.env. Un.env.localest ignoré sans aucun message, et ses valeurs n'arrivent jamais dans l'application. - Pas de secrets par fichier : les variables
*_FILEne sont pas prises en charge, toutes les valeurs vivent dans.env.
Voir aussi¶
- Installer Kirexo chez soi — l'installation pas à pas.
- Commande
app:install:check— le diagnostic qui vérifie ces réglages sur une instance démarrée. - Choisir l'entrée HTTP de son instance — les lignes à poser pour A2, B et C.
- Trois entrées HTTP, un seul fichier Compose — pourquoi tout se règle dans
.env. - Pourquoi refuser de démarrer plutôt qu'avertir — pourquoi une valeur d'exemple bloque le démarrage.