Aller au contenu

Guides

Cette section rassemble des guides pratiques : des recettes pas-à-pas pour résoudre un problème précis, qui supposent que vous connaissez déjà les bases de Kirexo.

Héberger son instance

Pour une instance installée en suivant Installer Kirexo chez soi :

  • Choisir l'entrée HTTP de son instance — Kirexo seul sur les ports 80 et 443 (avec ou sans certificats de site à la demande), derrière un Traefik ou derrière un autre proxy : les lignes de .env de chaque configuration et leurs points d'attention.
  • Installer Kirexo derrière un reverse proxy — un reverse proxy occupe déjà les ports 80 et 443 : les exigences communes, où relayer (http://127.0.0.1:8080 sur le serveur, http://kirexo:80 depuis Docker), puis une configuration complète pour Traefik (testée à chaque version), Caddy, Nginx, Apache et Nginx Proxy Manager, l'ajout d'un domaine de site et la vérification.
  • Servir les domaines de site en HTTPS — rendre joignables en HTTPS les domaines de site des utilisateurs selon l'entrée HTTP choisie (certificats à la demande, Traefik, autre proxy), et vérifier via l'adresse de contrôle /.kirexo/health.
  • Sauvegarder et restaurer son instance — ce qu'il faut sauvegarder (base, certificats, .env), les commandes, la fréquence, le test d'une sauvegarde sans toucher à l'instance et la restauration en six étapes.
  • Mettre à jour son instance — passer à une version X.Y.Z en huit étapes (sauvegarde, fichiers de la version, KIREXO_VERSION, arrêt du worker, images, redémarrage, vérification), le retour arrière et la vérification facultative des signatures.

Guides disponibles

  • Gérer les comptes utilisateurs — depuis les écrans Invitations et Utilisateurs de l'espace admin, les huit gestes : inviter, renvoyer une invitation (délai de 5 minutes, ancien lien invalidé), supprimer une invitation, désactiver, réactiver, supprimer, réintégrer (le compte revient désactivé) et supprimer définitivement (seulement depuis l'encart des comptes supprimés).
  • Créer un compte utilisateur en ligne de commande — amorcer le premier administrateur d'une instance (ou provisionner un compte user, admin ou mixte) via app:user:create, l'inscription publique étant fermée.
  • Se connecter à Kirexo — la page de connexion email-first des espaces user (/login) et admin (/admin/login), avec son message neutre anti-énumération.
  • Rester connecté avec « Se souvenir de moi » — cocher la case à l'étape mot de passe, la durée du cookie persistant par espace, et les trois situations qui l'invalident.
  • Réinitialiser son mot de passe — demander un lien de réinitialisation depuis « Mot de passe oublié ? », pour l'espace user ou admin (parcours fonctionnel jusqu'à la réception de l'email).
  • Recevoir les e-mails en développement — faire arriver dans Mailpit les e-mails partis sur la file Messenger asynchrone (worker supervisé, diagnostic, gotcha worker stale).
  • Écrire, enregistrer et publier un article — le parcours d'écriture complet depuis /u : créer un brouillon, l'éditeur Milkdown et sa poignée de bloc, l'autosave (Ctrl+S, hors-ligne, multi-onglets), publier, republier, dépublier, corbeille et restauration.
  • Rédiger un article structuré — habiller un article avec la titraille de presse (surtitre, sous-titre, chapô) et l'attribution (signature, lieu, crédits) depuis l'éditeur, avec le rappel de ce qui reste du markdown dans le corps.
  • Choisir les destinations d'un article et prévisualiser son rendu web — depuis l'éditeur (/u/articles/{id}/edition), cocher/décocher les canaux de diffusion (défaut « publier partout », au moins une destination obligatoire) et ouvrir l'« Aperçu web » qui montre l'article dans la mise en page du site public (avec le cas « plugin web non activé »).
  • Gérer les plugins de diffusion (administrateur) — depuis /admin/plugins, activer/désactiver globalement chaque canal (kill switch), lire le compteur d'articles publiés par canal et comprendre le verrou qui interdit de couper un canal déjà utilisé.
  • Installer le plugin web sur une instance — brancher le plugin web fourni sur une instance : enregistrement du bundle dans config/bundles.php, import de routes, importmap, migration des tables web_plugin_*, et la checklist « install simple ».
  • Activer un plugin pour son compte — depuis /u/reglages/plugins, activer/désactiver pour son propre compte les canaux ouverts globalement par l'administration, avec les 4 états (indisponible / disponible / activé / activé-verrouillé) et l'infobulle de verrou.
  • Personnaliser son site — carte d'aiguillage pour façonner le site public d'un carnet (plugin web) : domaine, pages spéciales, thème, avec les limites de sécurité.
  • Choisir l'apparence de son site — depuis l'onglet Apparence de /u/web/reglages/site/{notebookId}, appliquer au site d'un carnet l'un des trois thèmes fournis (Par défaut, Classique, Minimal) ou l'un des vôtres ; effet immédiat sur le site public.
  • Créer, dupliquer, modifier et supprimer un thème de site — depuis la bibliothèque de thèmes du compte (/u/web/themes, accessible par « Gérer mes thèmes » de l'onglet Apparence), dupliquer un thème fourni, en créer un à partir de « Par défaut », écrire ses quatre sources avec l'éditeur CSS assisté, et supprimer (les sites concernés repassent à « Par défaut »).
  • Accéder à mes thèmes — ouvrir la bibliothèque de thèmes (/u/web/themes) depuis le menu du compte (« Mes thèmes »), sans carnet ni domaine configuré ; l'entrée n'apparaît que si le plugin web est activé.
  • Configurer le site web d'un carnet — depuis « Mon espace », ouvrir le menu ⋯ du carnet › « Configurer Web » (/u/web/reglages/site/{notebookId}, seul point d'entrée), rattacher un domaine — ce qui crée le site du carnet — puis régler ses pages spéciales et son apparence.
  • Réordonner les pages du menu de son site — depuis l'onglet Pages spéciales de /u/web/reglages/site/{notebookId}, changer l'ordre des pages du menu public par glisser-déposer (ordre implicite, sans champ numéro), avec la limite no-JS.
  • Créer, renommer, archiver et supprimer un carnet — depuis l'accueil de l'espace (/u), tout le cycle de vie d'un carnet : créer (titre + tagline) via « Nouveau carnet », renommer via le menu ⋯ › Réglages, archiver via ⋯ › « Archiver ce carnet », restaurer, et supprimer (ses articles partent en corbeille).
  • Rechercher un article dans son espace — depuis l'accueil de l'espace (/u), filtrer ses articles par titre via le champ de recherche (insensible aux accents et à la casse, tous carnets actifs et archivés), lire les résultats surlignés, ouvrir un aperçu, revenir aux carnets (champ vidé ou Échap).
  • Basculer entre l'espace administrateur et l'espace utilisateur — pour un compte mixte, passer d'un espace à l'autre sans ressaisir ses identifiants.
  • Configurer la clé API Claude pour l'analyse IA — fournir la clé de chiffrement (vault en dev, variable d'environnement en prod), puis saisir la clé API Claude dans /admin/reglages (champ write-only) pour activer l'analyse de conformité.
  • Consulter et analyser la conformité d'un article publié (espace admin) — depuis le dashboard /admin, accéder à la liste des articles publiés, lire le statut d'analyse de chaque ligne (badge « Analysé » / « Non analysé »), ouvrir un article en mode aperçu, lancer l'analyse de conformité et naviguer par le fil d'Ariane.
  • Analyser un article avec l'IA (Claude) — déclencher l'analyse depuis le panneau « Analyse de conformité », comprendre son caractère asynchrone (transport async) et lire le rapport : résumé, thèmes et grille de conformité à cinq lignes.
  • Définir la couleur d'accent de la plateforme — depuis /admin/reglages, choisir l'une des 6 teintes d'accent appliquée à toute l'instance.
  • Choisir le thème clair, sombre ou système — depuis le sélecteur de l'entête (présent sur tous les écrans), régler l'apparence en clair, sombre ou suivi du système ; préférence locale par visiteur.
  • Activer l'autocomplétion Castor sur l'hôte — bash, zsh, fish ; dans le conteneur de dev, c'est déjà actif.
  • Exécuter les tests — lancer la suite de tests unitaires, d'intégration et E2E.
  • Diagnostiquer un échec E2E en CI — dans les artefacts du job test:e2e, où trouver le log verbeux Chromium (var/log/chrome.log), les captures d'erreur (var/error-screenshots/) et le JUnit, et comment distinguer un navigateur qui n'a pas démarré d'un scénario applicatif qui a échoué.
  • Enregistrer une vidéo de démo pour un ticket — produire un .mp4 avec le skill /demo-video (Chromium + ffmpeg de l'image de dev), l'attacher à un work-item, et savoir quand la vidéo est obligatoire (par lot sur un .twig, par cycle sur toute surface visuelle).
  • Créer et détruire un worktree — castor wt:up, wt:shell (alias wt:bash), wt:claude, wt:list, wt:destroy et wt:gc : une stack Docker complète et isolée par ticket (base, réseau, image, trois URLs), avec ce que wt:up réconcilie, le contrôle du point de départ qu'il propose, comment entrer dans le conteneur — cd dans le worktree, puis wt:bash ou wt:claude, qui ne prennent pas de ticket —, ce que wt:destroy ne supprime pas, et les limites de C8 sur l'historique git.
  • Réparer un worktree dont la stack ne démarre plus — wt:up échoue et le worktree ne sert rien : entrer malgré tout en se plaçant dans le répertoire du worktree puis castor wt:shell (conteneur en maintenance, ou conteneur jetable), lire le marqueur de maintenance et les journaux, réparer depuis l'intérieur, et laisser le healthcheck remonter la stack.
  • Installer la CA du proxy de développement et migrer un poste existant — sur le poste de développement : faire confiance à la CA du proxy hôte, retirer l'ancienne racine FrankenPHP et migrer un poste existant vers les URLs app..
  • Brancher PhpStorm sur un worktree — ouvrir le worktree nativement et n'utiliser le conteneur que comme interpréteur distant (PHP, Composer, PHPUnit, Xdebug) : interpréteur Docker Compose, path mappings, port de debug propre au worktree, Server nommé comme le worktree, et les trois pannes silencieuses.
  • Ouvrir un domaine dans l'allowlist du proxy sortant — autoriser un domaine refusé par le proxy de sortie réseau.
  • Diagnostiquer un blocage réseau sortant — lire les sondes, les logs du proxy et l'allowlist appliquée quand une commande échoue sur le réseau.
  • Relancer FrankenPHP ou le worker Messenger depuis le conteneur — une 502, un e-mail qui ne part pas ou un article publié absent de son site public : identifier lequel des deux programmes supervisés est mort, lire son journal et le relancer sans toucher à l'autre.
  • Exploiter un coredump — un fichier core de plusieurs gigaoctets est apparu à la racine : lire la commande qui l'a produit (file, note ELF tronquée à 80 caractères), pourquoi l'analyse n'est pas faisable dans l'image de dev, la procédure côté hôte, et la position du projet (détection oui, interdiction non, suppression jamais automatique).
  • Monitorer le serveur et le hub Mercure avec Ember — castor monitor : la TUI branchée sur l'admin API Caddy (:2019) pour suivre en direct requêtes/s, latences, status codes, workers FrankenPHP et compteurs Mercure. Moniteur live, sans historisation ni alerting.
  • Pousser sur GitLab depuis un worktree — pousser depuis le conteneur (réécriture HTTPS, credential helper qui lit le jeton dans l'environnement), ce que le hook pre-push refuse (main, branches d'intégration, tags), et comment pousser malgré lui quand c'est délibéré.
  • Garder mon image de dev à jour — repérer une image kirexo-dev périmée (alerte du dashboard de session), reconstruire la surcouche locale, rafraîchir la base publiée et bumper les versions d'outils figées dans le Dockerfile.
  • Créer et faire tourner le jeton GitLab de Kirexo — un jeton dédié au seul projet (compte bot ou PAT de repli), écrit dans ~/.kirexo/secrets/gitlab-token : création, vérification de la portée, rotation, révocation.
  • Bootstrapper la pipeline CI — séquence d'actions one-shot sur une nouvelle instance GitLab (DNS, PAT, variable CI/CD, custom domain Pages, schedule, premier build des images CI). À jouer avant les autres guides CI.
  • Jouer le test d'installation du bundle en local — castor docker:test-install en terminal hôte : jouer le bundle install/ comme un tiers, lire le verdict étape par étape (S0 à S17), déboguer avec --keep, nettoyer, et reporter l'empreinte mesurée entre les balises de install/README.md.
  • Créer un tag de release — choisir le niveau patch / minor / major et déclencher une release en version sémantique (build Docker, doc, release GitLab) via la pipeline CREATE_TAG=true.
  • Publier le site vitrine — configuration à faire une fois (projet et clé deploybase, variables CI Masked + Protected, tags protégés *.*.*, CNAME de www.kirexo.app et redirection du domaine nu chez OVH), publication par le job release:site-deploy à chaque tag, simulation castor site:deploy --dry-run, retour à une version précédente, bascule vers le repli OVH et dépannage.
  • Déployer Kirexo en production — pull d'une image immuable taggée et rollback via KIREXO_VERSION, et dépannage d'un conteneur resté unhealthy (migration en échec, secret d'exemple refusé).
  • Configurer la cleanup policy du registry — empêcher le Container Registry du projet d'accumuler les tags de version kirexo-prod:<x.y.z> au fil des releases, et purger les images horodatées historiques.
  • Configurer le domaine GitLab Pages — associer doc.kirexo.app et provisionner le certificat Let's Encrypt.
  • Configurer l'audit de sécurité quotidien — créer la schedule GitLab qui lance composer audit chaque matin et tente d'ouvrir une MR de patch (fallback issue), et qui déclenche en même temps Renovate, le contrôle des outils et le scan CVE des images (kirexo-prod, kirexo-base, kirexo-dev).
  • Configurer le rebuild hebdomadaire de la doc — schedule dédiée (REBUILD_DOCS=true) qui réveille pages chaque lundi pour rafraîchir le rendu de la doc figée sur la dernière version semver.
  • Configurer les montées de version automatiques (Renovate) — activer le bot qui ouvre des MRs de montée de version et de sécurité (réutilise le GITLAB_TOKEN).

Guides à venir

Voici les guides qui seront publiés au fur et à mesure de l'avancement du projet :

  • Connecter son compte Mastodon à Kirexo.
  • Migrer ses articles depuis WriteFreely.

Si vous cherchez un guide qui n'est pas dans cette liste, ouvrez une issue sur le dépôt.