Aller au contenu

Bundle d'installation install/ : services, volumes et variables

Référence du jeu de fichiers qui permet d'installer Kirexo avec docker et docker compose seuls, sans clone du dépôt, sans Castor et sans build local. Elle s'adresse aux développeur·ses qui maintiennent ce bundle. La procédure destinée à la personne qui installe est le tutoriel Installer Kirexo chez soi, qui fait foi ; install/README.md en est la copie hors ligne, alignée (cf. install/README.md).

Sources :

  • install/compose.yaml — services, volumes, réseaux, interpolation ;
  • install/.env.example — variables à renseigner, commentées, à renommer en .env ;
  • install/README.md — copie hors ligne, alignée, de la procédure du tutoriel Installer Kirexo chez soi, publiée seule en asset de release ;
  • src/Plugin/Web/src/Controller/WebPluginTlsAskController.php — endpoint ask de l'on-demand TLS, consommé par le scénario A2.

Les choix qui structurent le bundle (un seul fichier pour toutes les entrées HTTP, secrets vides, épinglage de php…) sont discutés dans Trois entrées HTTP, un seul fichier Compose.

Distinct de compose.yaml et de compose.prod.yaml

Fichier Usage Pourquoi il n'est pas distribuable
compose.yaml (racine) développement image construite localement, tty: true, défauts !ChangeMe!, dépendances vers Typesense et Gotenberg
compose.prod.yaml déploiement du mainteneur, cf. Déployer Kirexo en production labels Traefik en dur, aucun port publié, aucun réseau paramétré
install/compose.yaml installation par un tiers —

Le bundle est autoportant : il ne référence aucun autre fichier du dépôt et n'est pas chargé en surcouche d'un autre fichier Compose.

Invariants de forme

install/compose.yaml et install/.env.example respectent tous deux les règles suivantes :

  • aucun profiles:, build:, container_name:, tty:, init:, env_file: ni bind-mount ;
  • aucun service typesense, gotenberg, mailer ou docs ;
  • aucune variable MAIL_FROM (ni active, ni commentée), IMAGES_PREFIX, USER_ID, GROUP_ID, TYPESENSE_*, GOTENBERG_*, ni variable de l'outillage IA de développement ;
  • aucune mention de Castor, d'un chemin docs/… ou d'un autre fichier du dépôt : les messages et commentaires renvoient à .env.example ou à README.md ;
  • aucune coordonnée temporelle (numéro d'étape, de lot, de ticket, date) ;
  • restart: unless-stopped sur chaque service.

Services

Nom de projet fixe : name: kirexo. Une seconde instance sur le même hôte passe par COMPOSE_PROJECT_NAME, prioritaire sur name:.

Service Image Rôle Dépend de (service_healthy) Sonde de santé
php registry.gitlab.com/shaurifr/kirexo/kirexo-prod:${KIREXO_VERSION} Serveur FrankenPHP (Caddy) : application, hub Mercure, endpoint ask. Seul migrateur (RUN_MIGRATIONS, défaut 1) database, redis, rabbitmq curl -f http://localhost:2019/metrics, start_period: 300s, interval: 10s, timeout: 5s, retries: 5
worker même image Consommateur Messenger : e-mails, diffusion, analyse IA, tâches planifiées. Ne migre jamais (RUN_MIGRATIONS: "0") php (avec restart: true), database, redis, rabbitmq désactivée (healthcheck.disable: true)
database postgres:18-alpine Base PostgreSQL — pg_isready -d ${POSTGRES_DB:-kirexo} -U ${POSTGRES_USER:-kirexo}, start_period: 60s
redis redis:8-alpine Cache, sessions, verrou du planificateur (LOCK_DSN) — redis-cli ping
rabbitmq rabbitmq:4-alpine Files messages et plugin_web. hostname: rabbitmq fixe, pour conserver les files d'une recréation à l'autre — rabbitmq-diagnostics ping

Le start_period de php vaut 300 s parce que les migrations tournent avant le serveur : cf. RUN_MIGRATIONS. Un succès pendant ce délai rend le service sain aussitôt.

Le service php porte en plus :

  • extra_hosts: ["php:127.0.0.1"] — le conteneur s'appelle lui-même sur http://php/ (publication Mercure, endpoint ask) ;
  • trois publications de ports (80/tcp, 443/tcp, 443/udp pour HTTP/3), en syntaxe courte ${KIREXO_BIND_ADDRESS:+${KIREXO_BIND_ADDRESS}:}<port>:<cible>/<proto> — aucune clé host_ip :

    ports:
      - "${KIREXO_BIND_ADDRESS:+${KIREXO_BIND_ADDRESS}:}${KIREXO_HTTP_PORT:-80}:80/tcp"
      - "${KIREXO_BIND_ADDRESS:+${KIREXO_BIND_ADDRESS}:}${KIREXO_HTTPS_PORT:-443}:443/tcp"
      # HTTP/3
      - "${KIREXO_BIND_ADDRESS:+${KIREXO_BIND_ADDRESS}:}${KIREXO_HTTPS_PORT:-443}:443/udp"
    

    L'adresse et son : ne sont insérés que si KIREXO_BIND_ADDRESS est définie et non vide (cf. Pourquoi la syntaxe courte) ; - les réseaux default et edge ; - les volumes caddy_data:/data et caddy_config:/config.

Écarts du worker avec compose.prod.yaml

Le service worker est repris de compose.prod.yaml. Seuls ces écarts sont autorisés :

Clé compose.prod.yaml install/compose.yaml
image ancre *kirexo-prod-image (préfixe IMAGES_PREFIX interpolé) ancre *kirexo-image (nom en dur)
restart always unless-stopped
environment <<: *kirexo-app-environment <<: *kirexo-environment
commentaires renvoient à des fichiers du dépôt et à --scale sans renvoi au dépôt

Tout le reste est identique au caractère près : command (forme chaîne), scale: ${KIREXO_WORKER_REPLICAS:-1}, RUN_MIGRATIONS: "0" posé après la fusion d'ancre, depends_on (dont php.restart: true), healthcheck.disable: true, stop_signal: SIGTERM, stop_grace_period: 120s, sans init: true. La ligne command: est la suivante, dans les deux fichiers :

command: "php bin/console messenger:consume ${KIREXO_WORKER_TRANSPORTS:-scheduler_default plugin_web async} --time-limit=3600 --memory-limit=192M -vv"

Le rôle de chaque option est décrit dans Worker Messenger.

Volumes

Tous nommés, préfixés kirexo_ par le nom de projet fixe, quel que soit le répertoire d'installation.

Volume Monté dans Contenu Sauvegarde
kirexo_database_data database:/var/lib/postgresql tout l'état applicatif obligatoire (pg_dump)
kirexo_caddy_data php:/data certificats TLS, clé de compte ACME obligatoire
kirexo_caddy_config php:/config configuration Caddy autosauvegardée régénérable
kirexo_redis_data redis:/data cache, sessions, verrous transitoire
kirexo_rabbitmq_data rabbitmq:/var/lib/rabbitmq messages en attente transitoire

Depuis PostgreSQL 18, l'image range ses données dans un sous-dossier versionné de /var/lib/postgresql et refuse de démarrer si /var/lib/postgresql/data est un point de montage : le volume vise donc le dossier parent.

Le fichier .env fait lui aussi partie de la sauvegarde : il porte les secrets de l'instance.

Réseaux

Réseau Nom effectif external Rôle
default kirexo_default non réseau interne des cinq services
edge ${KIREXO_EDGE_NETWORK:-kirexo_edge} ${KIREXO_EDGE_EXTERNAL:-false} réseau de bord ; en scénario B, réseau existant du Traefik ; derrière un autre reverse proxy conteneurisé, réseau existant de ce proxy

Seul php rejoint edge, sous l'alias réseau kirexo :

    networks:
      default:
      # Cible stable des proxies qui tournent dans Docker (Nginx Proxy Manager,
      # Caddy ou Nginx conteneurisés) : http://kirexo:80 sur le réseau partagé.
      edge:
        aliases:
          - kirexo

L'alias fait partie du contrat : c'est la cible http://kirexo:80 qu'un reverse proxy conteneurisé reçoit dans Installer Kirexo derrière un reverse proxy, avec KIREXO_EDGE_EXTERNAL=true et KIREXO_EDGE_NETWORK égal au réseau de ce proxy. Le renommer ou le retirer casse ces installations. Il ne remplace pas le nom php, épinglé sur 127.0.0.1 par extra_hosts pour que le conteneur s'appelle lui-même sans viser un voisin du réseau partagé. Traefik, lui, n'utilise pas l'alias : il joint le conteneur par son adresse sur le réseau désigné par le label traefik.docker.network.

Environnement injecté

L'environnement commun à php et worker est déclaré une fois, dans le fragment x-kirexo-environment, et fusionné dans chaque service par <<: *kirexo-environment. Une variable ajoutée au fragment arrive aux deux services.

Variable injectée Valeur Sémantique
KIREXO_DOMAIN ${KIREXO_DOMAIN:?…} cf. Variables propres au bundle
APP_SECRET ${APP_SECRET:?…} Framework Symfony
CLAUDE_API_KEY_CIPHER_KEY ${CLAUDE_API_KEY_CIPHER_KEY:?…} Chiffrement de la clé API Claude
DEFAULT_URI ${DEFAULT_URI:-https://${KIREXO_DOMAIN}} Framework Symfony
KIREXO_RESERVED_DOMAINS ${KIREXO_RESERVED_DOMAINS:-${KIREXO_DOMAIN}} Multi-tenant
TRUSTED_PROXIES ${TRUSTED_PROXIES:-} Framework Symfony
TRUSTED_HOSTS ${TRUSTED_HOSTS:-} Framework Symfony
DATABASE_URL DSN postgresql composé de POSTGRES_USER (défaut kirexo), POSTGRES_PASSWORD (obligatoire), hôte database:5432, base POSTGRES_DB (défaut kirexo), serverVersion=18 Doctrine / PostgreSQL
REDIS_URL, LOCK_DSN redis://redis:6379 Redis, Symfony Lock
MESSENGER_TRANSPORT_DSN DSN amqp composé de RABBITMQ_USER (défaut kirexo), RABBITMQ_PASSWORD (obligatoire), hôte rabbitmq:5672, vhost /, file messages Messenger / RabbitMQ
MESSENGER_TRANSPORT_PLUGIN_WEB_DSN même composition, file plugin_web idem
MERCURE_URL http://php/.well-known/mercure Mercure
MERCURE_PUBLIC_URL ${MERCURE_PUBLIC_URL:-https://${KIREXO_DOMAIN}/.well-known/mercure} idem
MERCURE_PUBLISHER_JWT_KEY, MERCURE_SUBSCRIBER_JWT_KEY ${CADDY_MERCURE_JWT_SECRET:?…} idem
MAILER_DSN ${MAILER_DSN:?…} Mailer
MAILER_FROM_ADDRESS ${MAILER_FROM_ADDRESS:?…} idem ; MAIL_FROM en est dérivé par le .env embarqué dans l'image
KIREXO_ONDEMAND_TLS_ENABLED ${KIREXO_ONDEMAND_TLS_ENABLED:-0} FrankenPHP / Caddy
REMEMBER_ME_SECURE "true" en dur le public est toujours servi en HTTPS
TZ ${TZ:-UTC} Fuseau horaire
SENTRY_DSN, GRAYLOG_HOST, GRAYLOG_PORT ${…:-}, ${…:-}, ${GRAYLOG_PORT:-12201} Observabilité

Variables propres au service php, après la fusion :

Variable Valeur
SERVER_NAME ${SERVER_NAME:-${KIREXO_DOMAIN}}, php:80 — le suffixe , php:80 (vhost interne en clair) est toujours ajouté
CADDY_ONDEMAND_TLS_GLOBAL ${CADDY_ONDEMAND_TLS_GLOBAL:-}
CADDY_ONDEMAND_TLS_SITE ${CADDY_ONDEMAND_TLS_SITE:-}
RUN_MIGRATIONS ${RUN_MIGRATIONS:-1}

Le service worker reçoit RUN_MIGRATIONS: "0" en dur, non surchargeable depuis .env. POSTGRES_PASSWORD n'est pas injecté dans l'environnement applicatif : le garde-fou des secrets le lit dans DATABASE_URL.

Variables obligatoires

Chacune est déclarée ${VAR:?message} : absente ou vide, docker compose refuse de démarrer avant tout conteneur et affiche le message, qui nomme la commande de génération et renvoie à .env.example. Chacune a une ligne active VAR= dans .env.example.

Variable Valeur livrée dans .env.example Génération
KIREXO_VERSION 0.0.1 cf. Ancre KIREXO_VERSION
KIREXO_DOMAIN (vide) domaine de l'application
APP_SECRET (vide) openssl rand -hex 32
POSTGRES_PASSWORD (vide) openssl rand -hex 32
RABBITMQ_PASSWORD (vide) openssl rand -hex 32
CADDY_MERCURE_JWT_SECRET (vide) openssl rand -hex 32
CLAUDE_API_KEY_CIPHER_KEY (vide) openssl rand -base64 32
MAILER_DSN (vide) serveur SMTP sortant, ou null://null
MAILER_FROM_ADDRESS (vide) adresse d'expédition

Les cinq secrets sont livrés vides, jamais avec une valeur d'exemple. Une valeur d'exemple de développement recopiée malgré tout est arrêtée par le garde-fou de l'entrypoint.

Variables propres au bundle

Variables lues par install/compose.yaml seul, sans équivalent dans l'application.

Variable Défaut Rôle
KIREXO_VERSION (aucun, obligatoire) Tag de l'image kirexo-prod. Jamais de tag flottant
KIREXO_DOMAIN (aucun, obligatoire) Domaine de l'application. Seule saisie de domaine obligatoire : DEFAULT_URI, KIREXO_RESERVED_DOMAINS, MERCURE_PUBLIC_URL, SERVER_NAME et la règle Traefik en dérivent (cf. Dérivations)
KIREXO_BIND_ADDRESS (vide) — toutes les interfaces, IPv4 et IPv6 Adresse d'écoute sur l'hôte des trois publications de ports. Vide : port publié sans host_ip. 127.0.0.1 : host_ip: 127.0.0.1. Une adresse IPv6 s'écrit entre crochets : [::1] donne host_ip: ::1
KIREXO_HTTP_PORT 80 Port hôte publié vers le port 80 du conteneur
KIREXO_HTTPS_PORT 443 Port hôte publié vers le port 443 du conteneur, en TCP et en UDP
KIREXO_EDGE_NETWORK kirexo_edge Nom du réseau edge, repris par le label traefik.docker.network
KIREXO_EDGE_EXTERNAL false true : le réseau edge existe déjà (réseau du Traefik) et n'est pas créé par ce projet
KIREXO_TRAEFIK_ENABLE false Valeur du label traefik.enable. Tant qu'elle vaut false, les autres labels sont inertes
KIREXO_TRAEFIK_RULE Host(`${KIREXO_DOMAIN}`) Règle du routeur kirexo
KIREXO_TRAEFIK_ENTRYPOINTS websecure Entrypoint(s) du routeur kirexo
KIREXO_TRAEFIK_CERTRESOLVER letsencrypt Résolveur de certificat du routeur kirexo
KIREXO_WORKER_REPLICAS 1 scale du service worker
KIREXO_WORKER_TRANSPORTS scheduler_default plugin_web async Transports consommés par le worker, interpolés dans sa command

Autres variables interpolées, facultatives : POSTGRES_USER et POSTGRES_DB (défaut kirexo), RABBITMQ_USER (défaut kirexo), et toutes les variables applicatives listées dans Environnement injecté. Chacune figure dans .env.example, au moins en ligne commentée #VAR=.

POSTGRES_PASSWORD, POSTGRES_USER et POSTGRES_DB ne sont lus par PostgreSQL qu'à la création du volume, RABBITMQ_USER et RABBITMQ_PASSWORD par RabbitMQ qu'au premier démarrage sur un volume vide.

Labels Traefik du service php

Toujours présents, inertes tant que KIREXO_TRAEFIK_ENABLE ne vaut pas true :

labels:
  - "traefik.enable=${KIREXO_TRAEFIK_ENABLE:-false}"
  - "traefik.docker.network=${KIREXO_EDGE_NETWORK:-kirexo_edge}"
  - "traefik.http.routers.kirexo.rule=${KIREXO_TRAEFIK_RULE:-Host(`${KIREXO_DOMAIN}`)}"
  - "traefik.http.routers.kirexo.entrypoints=${KIREXO_TRAEFIK_ENTRYPOINTS:-websecure}"
  - "traefik.http.routers.kirexo.tls=true"
  - "traefik.http.routers.kirexo.tls.certresolver=${KIREXO_TRAEFIK_CERTRESOLVER:-letsencrypt}"
  - "traefik.http.routers.kirexo.service=kirexo"
  - "traefik.http.services.kirexo.loadbalancer.server.port=80"

Dérivations depuis KIREXO_DOMAIN

Cinq valeurs imbriquent une interpolation dans une valeur de repli. Avec KIREXO_DOMAIN=kirexo.example.org et aucune surcharge :

Clé Forme Valeur rendue
DEFAULT_URI ${DEFAULT_URI:-https://${KIREXO_DOMAIN}} https://kirexo.example.org
KIREXO_RESERVED_DOMAINS ${KIREXO_RESERVED_DOMAINS:-${KIREXO_DOMAIN}} kirexo.example.org
MERCURE_PUBLIC_URL ${MERCURE_PUBLIC_URL:-https://${KIREXO_DOMAIN}/.well-known/mercure} https://kirexo.example.org/.well-known/mercure
SERVER_NAME (php) ${SERVER_NAME:-${KIREXO_DOMAIN}}, php:80 kirexo.example.org, php:80
label traefik.http.routers.kirexo.rule ${KIREXO_TRAEFIK_RULE:-Host(`${KIREXO_DOMAIN}`)} Host(`kirexo.example.org`)

Une variable définie dans .env remplace la valeur dérivée, telle quelle. Les valeurs rendues se vérifient par docker compose config, dans le répertoire du bundle. Cette sortie contient les secrets : pour un simple contrôle de validité, docker compose config --quiet.

Valeurs par scénario d'entrée HTTP

Le scénario se choisit uniquement dans .env, section 3 de .env.example. Sans aucune ligne décommentée, c'est A1. Le serveur applicatif est FrankenPHP dans les quatre cas.

Variable A1 — frontal (défaut) A2 — frontal + on-demand TLS B — derrière Traefik C — derrière un proxy existant
SERVER_NAME (défaut : KIREXO_DOMAIN) 'kirexo.example.org, :443' :80 :80
KIREXO_ONDEMAND_TLS_ENABLED 0 1 0 0
CADDY_ONDEMAND_TLS_GLOBAL (vide) 'on_demand_tls { ask http://php/.well-known/kirexo/on-demand-tls }' (vide) (vide)
CADDY_ONDEMAND_TLS_SITE (vide) 'tls { on_demand }' (vide) (vide)
KIREXO_BIND_ADDRESS (vide) (vide) 127.0.0.1 127.0.0.1
KIREXO_HTTP_PORT 80 80 8080 8080
KIREXO_HTTPS_PORT 443 443 8443 8443
TRUSTED_PROXIES (vide) (vide) 127.0.0.0/8,10.0.0.0/8,172.16.0.0/12,192.168.0.0/16 mêmes plages, ou l'adresse du proxy s'il est sur une autre machine
KIREXO_TRAEFIK_ENABLE false false true false
KIREXO_EDGE_EXTERNAL false false true false
KIREXO_EDGE_NETWORK kirexo_edge kirexo_edge nom du réseau du Traefik (exemple : traefik) kirexo_edge
KIREXO_TRAEFIK_ENTRYPOINTS, _CERTRESOLVER, _RULE inertes inertes websecure, letsencrypt, 'Host(`kirexo.example.org`)' inertes
Terminaison TLS Caddy, ACME pour KIREXO_DOMAIN Caddy, certificat émis à la poignée de main après accord de l'endpoint ask Traefik, relais en HTTP clair vers php:80 sur edge le proxy, relais en HTTP clair vers 127.0.0.1:8080
Domaines de site publics en HTTPS non oui, à la première visite un Host(…) par domaine dans la règle à la charge du proxy

En A2, l'endpoint ask répond 200 pour un domaine réservé à l'application (KIREXO_RESERVED_DOMAINS) ou mappé à un Site, 403 sinon, et 403 pour tout domaine tant que KIREXO_ONDEMAND_TLS_ENABLED vaut 0. Détail de la configuration TLS : Servir les domaines de site en HTTPS.

En C, le proxy doit transmettre l'en-tête Host d'origine, poser X-Forwarded-Proto et X-Forwarded-For, ne pas mettre en tampon /.well-known/mercure (flux SSE) et accepter les domaines de site publics en plus de KIREXO_DOMAIN.

Contrat avec l'image

Le bundle ne construit rien : il consomme l'image kirexo-prod et s'appuie sur ce qu'elle fournit.

Fourni par l'image Consommé par le bundle
Entrypoint qui joue les migrations avant le serveur quand RUN_MIGRATIONS=1, et reste vivant unhealthy en cas d'échec — cf. RUN_MIGRATIONS RUN_MIGRATIONS sur php seul, start_period: 300s, restart: unless-stopped sans boucle de redémarrage
Garde-fou des secrets d'exemple — cf. Garde-fou des secrets d'exemple seconde barrière, après les :? du Compose
Extension pcntl — cf. pcntl dans le stage prod stop_signal: SIGTERM sans init: true sur le worker
.env embarqué qui dérive MAIL_FROM de MAILER_FROM_ADDRESS aucune variable MAIL_FROM injectée : une valeur vide écraserait la dérivation
frankenphp/Caddyfile : vhost unique {$SERVER_NAME}, placeholders CADDY_ONDEMAND_TLS_GLOBAL / CADDY_ONDEMAND_TLS_SITE, administration Caddy sur :2019 SERVER_NAME, les deux placeholders, sonde :2019/metrics
date.timezone = ${TZ:-UTC} (frankenphp/conf.d/10-app.ini) TZ toujours injectée avec une valeur
Commande app:install:check diagnostic par docker compose exec php bin/console app:install:check

Ancre KIREXO_VERSION

Le nom d'image est écrit en dur : registry.gitlab.com/shaurifr/kirexo/kirexo-prod. Seule la version varie, sans valeur par défaut (${KIREXO_VERSION:?…}).

Dans install/.env.example, la version tient sur une seule ligne, au format exact :

KIREXO_VERSION=0.0.1

Sans guillemets ni commentaire en fin de ligne. Le dépôt porte 0.0.1 comme valeur de référence. Cette ligne est l'ancre de la publication en assets de release : le job release:bundle-render remplace la ligne entière par KIREXO_VERSION=<tag> dans la copie publiée, et échoue si le fichier compte zéro ou plusieurs lignes commençant par KIREXO_VERSION=. Règle complète : Substitution de KIREXO_VERSION. Déplacer la ligne en commentaire, la dupliquer ou y ajouter un commentaire en fin de ligne casse l'ancre ou perd le commentaire.

install/README.md

Troisième fichier du bundle : la procédure complète de la personne qui installe et exploite une instance avec docker et docker compose seuls, sans clone du dépôt ni Castor. Il est publié seul, en asset de release, et rendu par GitLab.

Propriété Valeur
Public la personne qui héberge sa propre instance, pas le développeur·se du projet
Rendu Markdown GitLab ; hors docs_dir, jamais inclus dans mkdocs
Langue français, vouvoiement
Autonomie suivi de bout en bout sans ouvrir le dépôt, la documentation mkdocs ni aucun autre document

Le tutoriel fait foi. Le README reprend ses quatre étapes à l'identique (titres et commandes, dans le même ordre), puis la même procédure complète que les pages d'auto-hébergement : Installer Kirexo chez soi, Paramètres de l'instance, Choisir l'entrée HTTP de son instance, Sauvegarder et restaurer son instance et Mettre à jour son instance. Une modification commence par le tutoriel et descend vers le README dans le même lot, jamais l'inverse. La règle complète de rédaction de ces trois copies (tutoriel, page « Installer » du site vitrine, README) vit dans .claude/skills/_shared/documentation-installation.md. Cette page-ci ne décrit pas la procédure : elle fixe le contrat que ses gestes supposent.

Plan

Sections de niveau 2, dans cet ordre :

Section Contenu
# Installer Kirexo public visé, sommaire des trois gestes (installer, configurer, mettre à jour)
## Prérequis machine, architecture, logiciel, DNS, ports, SMTP, langue ; sous-bloc « Empreinte mesurée »
## Installer en quatre étapes phrase de prérequis, puis les quatre étapes du tutoriel, à l'identique, jusqu'à la première connexion
## Configurer ouvre sur l'encadré « Compose ne lit que .env » ; entrées HTTP A1, A2, B, C ; référence des variables ; protection de .env ; nombre de workers
## Comptes et rôles absence de compte par défaut, forme sans terminal, rôles, adresses de connexion, comptes suivants par invitation, voie de secours sans SMTP
## Vérifier l'installation app:install:check, logs, premier parcours
## Sauvegarder et restaurer périmètre, commandes, fréquence, test non destructif, restauration
## Mettre à jour séquence ordonnée (sauvegarde, fichiers de la version, KIREXO_VERSION, arrêt du worker, pull, up), retour arrière
## Mises à jour automatiques : à éviter pourquoi un suivi de latest est déconseillé
## Vérifier l'authenticité des images (facultatif) cosign verify, SBOM
## Dépannage tableau Symptôme / Cause / Remède

Règles de maintenance

Règle Portée
Alignement Les titres et les commandes des quatre étapes de ## Installer en quatre étapes sont identiques, dans le même ordre, à ceux du tutoriel Installer Kirexo chez soi. Toute ligne d'un bloc bash du README figure telle quelle dans au moins une page d'auto-hébergement de cette documentation (tutoriel, référence de paramétrage, trois guides *-son-instance.md, guides TLS et compte en ligne de commande). Verrou : tests/Bash/install/install-doc.bats. Trou accepté : ce verrou ne tourne en CI que sur les MR qui touchent install/** ou tests/Bash/** ; une MR qui ne modifie qu'une page docs/ ne le relance pas, et la dérive n'est détectée qu'à la MR suivante qui touche le bundle, ou par castor all en local
Variables Toute variable de install/.env.example, en ligne active VAR= ou commentée #VAR=, a une ligne dans la référence des variables du README, dans l'ordre du fichier et sous le même intertitre, et dans docs/reference/parametres-de-linstance.md (verrou install-doc.bats). Inversement, le README ne documente aucune variable absente de .env.example. Verrou : tests/Bash/install/install-readme.bats
Statuts La colonne « Statut » reprend le statut porté par le commentaire de la variable dans .env.example. Une divergence se corrige dans le bundle, pas dans le README seul
Services et volumes Tout service (php, worker, database, redis, rabbitmq) et tout volume (kirexo_*) cité existe dans install/compose.yaml
Version Aucun numéro de version chiffré hors du bloc d'empreinte. La version visée s'écrit X.Y.Z ; la valeur réelle vit dans le .env.example publié
Liens Aucun lien vers docs/, src/ ni vers un autre fichier du dépôt : le README publié seul rendrait ces liens morts. Seules URL externes admises : celles de la section URL figées
Vocabulaire exclu Aucune mention de Castor, compose.override.yaml, compose.prod.yaml, IMAGES_PREFIX, USER_ID, GROUP_ID, worktree, MAIL_FROM, Typesense, Gotenberg ni de l'outillage IA de développement
Coordonnées temporelles Aucun numéro d'étape, de lot, de ticket, aucun code de décision, aucune date
Domaines d'exemple kirexo.example.org pour l'application, blog.example.net pour un domaine de site (RFC 2606)
Commandes Copiables telles quelles depuis le répertoire d'installation, sans variable du shell de l'hôte, sauf dans la forme de provisionnement scriptée ($MOT_DE_PASSE, section « Comptes et rôles »), où la variable est annoncée et expliquée juste avant la commande. Une variable affectée dans le bloc même qui l'utilise (horodatage, sauvegarde) n'est rien à renseigner et reste admise. Téléchargement par curl -fsSLO seul. POSTGRES_USER et POSTGRES_DB sont lues dans le conteneur (sh -c '…', apostrophes simples). -T sur toute commande docker compose exec ou run dont le flux est redirigé, ou dont l'entrée standard est fournie par un tube
Encadrés Blockquotes Markdown (> **Attention** — …), jamais la syntaxe !!! d'admonition mkdocs

Bloc d'empreinte

Le sous-bloc « Empreinte mesurée » de la section Prérequis est délimité par deux commentaires HTML, invisibles au rendu :

<!-- kirexo:empreinte:debut -->
…
<!-- kirexo:empreinte:fin -->
  • Chaque balise apparaît une seule fois, sur sa propre ligne, debut avant fin.
  • Le contenu entre les balises est rempli par le test d'installation, qui y reporte les valeurs mesurées (mémoire, disque) de la version publiée, et n'écrit qu'entre les balises. Tant qu'aucune mesure n'est publiée, il contient un texte d'attente qui décrit la méthode de mesure.
  • Ne pas l'éditer à la main, ne pas y poser de chiffre estimé : seule une mesure y a sa place.
  • C'est la seule zone du README où un numéro de version chiffré est admis.

URL figées

Les URL de téléchargement découlent des direct_asset_path de la publication en assets de release : /compose.yaml, /.env.example, /README.md, à la racine et sans version. Le README ne contient aucune autre URL de téléchargement.

Usage URL
Page des releases https://gitlab.com/shaurifr/kirexo/-/releases
Dernière version (installation) https://gitlab.com/shaurifr/kirexo/-/releases/permalink/latest/downloads/compose.yaml
https://gitlab.com/shaurifr/kirexo/-/releases/permalink/latest/downloads/.env.example
https://gitlab.com/shaurifr/kirexo/-/releases/permalink/latest/downloads/README.md
Version précise (mise à jour, restauration, retour arrière) https://gitlab.com/shaurifr/kirexo/-/releases/X.Y.Z/downloads/compose.yaml
https://gitlab.com/shaurifr/kirexo/-/releases/X.Y.Z/downloads/.env.example

Ces URL sont aussi citées, caractère pour caractère, par les pages d'auto-hébergement de cette documentation (tutoriel Installer Kirexo chez soi, Sauvegarder et restaurer son instance, Mettre à jour son instance). Changer un direct_asset_path dans la publication impose de changer ces URL dans le README et dans ces pages, et inversement. Les direct_asset_path sont déclarés par release:create (.gitlab/ci/release.yml) ; détail des liens, du paquet et de la sémantique de latest : Assets de release et permaliens.

Vérification avant publication

Les commandes du README, et donc celles du tutoriel, ne sont pas toutes rejouées telles qu'écrites. Trois dispositifs se partagent la vérification, et une partie de la procédure n'est couverte par aucun.

Rejoué sous une forme équivalente par le test d'installation de bout en bout infra/image/install-e2e.sh (job CI docker:test-install sur la pipeline de tag, castor docker:test-install depuis un terminal hôte, cf. Jouer le test d'installation en local). Le test part du bundle rendu, copié dans un répertoire jetable, dans un projet Compose dédié (kirexo-install-e2e). Ses commandes diffèrent de celles du README :

  • docker compose y est toujours appelé avec -p, -f (le compose.yaml du bundle plus une surcouche de test, infra/image/install-e2e.compose.yaml) et --env-file ;
  • -T est utilisé partout, y compris là où le README écrit -it ; la création du premier compte passe donc par sa forme sans terminal, mot de passe sur l'entrée standard ;
  • .env est rempli par install_e2e_env_set, avec un serveur SMTP de capture, là où le README laisse la personne le renseigner à la main ;
  • up reçoit en plus --wait-timeout.

Gestes couverts ainsi : copie de .env, docker compose config --quiet, démarrage up -d --wait, ps, logs, migrations automatiques, app:install:check, création du premier compte et refus d'un doublon, connexion, invitation, site public sur un domaine distinct, publication et diffusion d'un article, deux workers, mesure de l'empreinte.

Verrouillé statiquement par les tests bats, sans Docker :

  • tests/Bash/install/install-readme.bats : variables du README ↔ .env.example, bloc d'empreinte, autoportance (aucun lien vers docs/, aucun castor ni MAIL_FROM), aucune version chiffrée hors du bloc d'empreinte, URL figées, coordonnées temporelles ;
  • tests/Bash/install/install-doc.bats : identité des quatre étapes entre tutoriel et README, présence des commandes du README dans les pages d'auto-hébergement, variables de Paramètres de l'instance ↔ .env.example, URL figées, vocabulaire.

Non vérifié automatiquement :

  • le téléchargement de l'étape 1 (curl -fsSLO …/permalink/latest/…) n'est vérifiable qu'après publication d'une version : tant qu'aucune n'existe, le permalien répond 404. Il se rejoue à la main, dans un répertoire vide, après la publication ;
  • les commandes de sauvegarde, de test de sauvegarde, de restauration et de mise à jour ne sont rejouées par aucun test : install-e2e.sh ne couvre ni pg_dump, ni pg_restore, ni changement de KIREXO_VERSION. Elles relèvent de la vérification manuelle sur une installation neuve (règle (b) de la fiche de rédaction).

Une commande qui échoue se corrige dans le tutoriel, puis dans le README dans le même lot, et le parcours est rejoué.

Modifier le bundle

  • .claude/settings.json refuse Edit(compose.yaml). Un nom de fichier nu s'applique à toute profondeur, avec la sémantique gitignore : la règle bloque aussi install/compose.yaml, pour les outils Edit et Write de Claude Code. Une copie par Bash (cp) vers ce chemin est elle aussi refusée en pratique. Le fichier s'écrit donc, comme compose.yaml et compose.prod.yaml, par un script PHP lancé via Bash : file_put_contents avec le contenu en nowdoc (<<<'EOT'), une garde d'unicité et une exécution idempotente. Les règles de permission ne se modifient pas pour contourner ce refus.
  • install/.env.example n'est visé par aucune règle : il s'édite normalement.
  • Toute variable ajoutée en ${VAR:?…} dans install/compose.yaml exige une ligne active VAR= dans install/.env.example ; toute autre variable interpolée, au moins une ligne commentée #VAR=.
  • Une modification du service worker de compose.prod.yaml se reporte dans install/compose.yaml, hors écarts autorisés.
  • Toute variable ajoutée, retirée ou renommée dans install/.env.example se reporte dans le tableau des variables de install/README.md ; toute commande modifiée s'y reporte aussi. Règles : install/README.md.

Voir aussi