Aller au contenu

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 :

docker compose up -d

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. Dans MAILER_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 :

docker compose up -d

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 par CLAUDE_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.local est ignoré sans aucun message, et ses valeurs n'arrivent jamais dans l'application.
  • Pas de secrets par fichier : les variables *_FILE ne sont pas prises en charge, toutes les valeurs vivent dans .env.

Voir aussi