Installer Kirexo chez soi¶
Vous administrez un serveur avec Docker et vous voulez y faire tourner votre propre instance de Kirexo. Quatre étapes l'installent ; la suite de la page sert à la vérifier, l'exploiter et la dépanner.
Installer en quatre étapes¶
Il vous faut un serveur Linux (amd64 ; arm64 selon la version, voir sa note de release) avec Docker et Docker Compose 2.17 ou plus récent, un domaine qui pointe vers ce serveur, les ports 80 et 443 libres et un serveur SMTP. Un reverse proxy occupe déjà ces ports ? Faites les étapes 1 et 2, puis suivez Installer Kirexo derrière un reverse proxy avant l'étape 3.
1. Télécharger¶
Dans un répertoire dédié, par exemple /opt/kirexo :
curl -fsSLO https://gitlab.com/shaurifr/kirexo/-/releases/permalink/latest/downloads/compose.yaml
curl -fsSLO https://gitlab.com/shaurifr/kirexo/-/releases/permalink/latest/downloads/.env.example
2. Configurer¶
Renseignez .env : domaine, secrets à générer, serveur SMTP, fuseau horaire. Chaque variable y est commentée. docker compose config --quiet signale une valeur obligatoire oubliée.
3. Démarrer¶
Au premier démarrage, Kirexo prépare sa base de données puis obtient son certificat HTTPS : comptez quelques minutes.
4. Créer votre compte¶
Choisissez votre mot de passe, puis connectez-vous sur https://VOTRE_DOMAINE/admin/login.
Vérifier l'installation¶
docker compose ps affiche (healthy) pour php, database, redis et rabbitmq, et Up pour worker.
Le diagnostic contrôle les secrets (renseignés, aucun resté à une valeur d'exemple), le domaine de l'application, la structure de la base, les fichiers de l'interface, le serveur SMTP (connexion et identifiants, sans envoi), l'adresse d'expédition (domaine réel, pas localhost, .local, .test, .example…) et le worker (signe de vie depuis moins de cinq minutes). Il se termine par [OK] Installation opérationnelle. ; chaque ligne en ✗ est suivie d'une ligne ↳ qui dit quoi corriger. Juste après le démarrage, le contrôle du worker peut échouer pendant une minute. Détail de chaque contrôle : app:install:check.
Journaux en direct (Ctrl+C pour sortir, Kirexo continue de tourner) :
Une erreur de démarrage s'y signale par une ligne qui commence par [kirexo] ERREUR, avec sa cause.
Pour servir un article sur un site public, il faut en plus :
- un second domaine qui pointe vers le serveur ;
- le plugin web activé pour l'instance dans
/admin/plugins(Gérer les plugins de diffusion), puis pour le compte (Activer un plugin pour son compte) ; - le certificat de ce domaine : Servir les domaines de site en HTTPS ;
- le domaine rattaché à un carnet depuis l'espace de rédaction : Configurer le site web d'un carnet.
Comptes et rôles¶
Il n'existe aucun compte ni mot de passe par défaut : le premier compte est celui de l'étape 4.
| Rôle | Effet |
|---|---|
admin |
Ouvre /admin (tableau de bord, réglages, plugins, comptes, consultation des articles), mais pas la rédaction |
user |
L'espace de rédaction seul (rôle par défaut si --role est omis) |
both |
Les deux, et la bascule entre les deux espaces |
Connexion : https://VOTRE_DOMAINE/admin/login pour l'administration, https://VOTRE_DOMAINE/login pour l'espace de rédaction.
Les comptes suivants se créent par invitation depuis /admin/invitations (Gérer les comptes utilisateurs). L'invitation exige un worker actif, un SMTP configuré, et une page /admin ouverte par le domaine de l'application, pas par l'adresse IP : le lien envoyé reprend l'adresse de la page. Sans SMTP : Créer un compte en ligne de commande.
Régler votre instance¶
Tout se règle dans .env, jamais dans compose.yaml, remplacé à chaque mise à jour. Kirexo ne lit aucun autre fichier de réglages. Une modification de .env s'applique par :
Chaque variable, son statut et ce qui casse quand elle est fausse : Paramètres de l'instance. Choisissez TZ avant le premier démarrage : les dates sont stockées sans fuseau, le changer ensuite décale celles déjà enregistrées.
Guides dédiés : Installer Kirexo derrière un reverse proxy, Choisir l'entrée HTTP de son instance, Servir les domaines de site en HTTPS.
Sauvegarder¶
La base chaque jour et avant chaque mise à jour, le volume des certificats (kirexo_caddy_data) chaque semaine, .env à chaque modification : Sauvegarder et restaurer son instance.
Mettre à jour¶
La version est épinglée dans .env (KIREXO_VERSION) : rien ne change sans vous. Sauvegardez avant : Mettre à jour son instance.
Si quelque chose ne fonctionne pas¶
Lancez d'abord le diagnostic de Vérifier l'installation. A1, A2, B et C désignent les entrées HTTP de Choisir l'entrée HTTP de son instance ; sans réglage, l'instance est en A1.
| Symptôme | Cause | Remède |
|---|---|---|
docker compose refuse toute commande en nommant une variable |
Variable obligatoire vide ou absente de .env |
La renseigner. Pour CLAUDE_API_KEY_CIPHER_KEY sur une instance existante : remettre la valeur existante (sauvegarde), jamais une nouvelle |
WARN « variable is not set » |
$ non échappé dans une valeur, souvent le mot de passe SMTP |
Encoder le caractère (%24) dans MAILER_DSN |
port is already allocated ou address already in use |
Ports 80 ou 443 occupés | Libérer les ports, ou passer derrière le reverse proxy |
manifest unknown au téléchargement des images |
KIREXO_VERSION ne désigne aucune version publiée |
Corriger la version |
php unhealthy, secret nommé dans les journaux |
Secret resté à une valeur d'exemple | Générer une vraie valeur, puis docker compose up -d |
php unhealthy au premier démarrage, [kirexo] ERREUR sur les migrations |
Préparation de la base en échec | Relancer docker compose up -d --wait, sinon lire docker compose logs --tail 50 php |
php unhealthy après une mise à jour, [kirexo] ERREUR sur les migrations |
Migration en échec | Retour arrière |
« dependency failed » pour worker après une mise à jour, sans [kirexo] ERREUR |
Migration plus longue que l'attente, toujours en cours | Attendre « Migrations Doctrine à jour. » dans docker compose logs -f php, puis docker compose up -d |
| Avertissement de certificat dans le navigateur (A1, A2) | DNS faux, ports 80/443 filtrés, ou domaine de site non déclaré (A2) | Corriger, puis docker compose restart php. Let's Encrypt limite les essais : corriger avant de relancer |
404 sur toute l'application, /login compris |
Nom d'accès absent de KIREXO_RESERVED_DOMAINS (par défaut, KIREXO_DOMAIN seul) |
Y lister chaque nom d'accès (avec et sans www…), puis docker compose up -d |
| Aucun e-mail reçu | Worker arrêté ou SMTP injoignable | docker compose ps worker, puis le diagnostic |
| Lien de réinitialisation vers un mauvais domaine | DEFAULT_URI ou KIREXO_DOMAIN faux |
Corriger .env, docker compose up -d, redemander le lien |
| Lien d'invitation vers un mauvais domaine | /admin ouvert par une autre adresse que le domaine |
Ouvrir /admin par le domaine, relancer l'invitation |
400 sur un domaine de site |
TRUSTED_HOSTS trop restrictif |
Le retirer, ou y ajouter php et chaque domaine de site |
| Domaine de site injoignable derrière Traefik (B) | Domaine absent de KIREXO_TRAEFIK_RULE |
L'ajouter à la règle, puis docker compose up -d |