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— endpointaskde 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,maileroudocs; - 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.exampleou àREADME.md; - aucune coordonnée temporelle (numéro d'étape, de lot, de ticket, date) ;
restart: unless-stoppedsur 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 surhttp://php/(publication Mercure, endpointask) ;-
trois publications de ports (
80/tcp,443/tcp,443/udppour 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 siKIREXO_BIND_ADDRESSest définie et non vide (cf. Pourquoi la syntaxe courte) ; - les réseauxdefaultetedge; - les volumescaddy_data:/dataetcaddy_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 :
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 :
- Chaque balise apparaît une seule fois, sur sa propre ligne,
debutavantfin. - 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 composey est toujours appelé avec-p,-f(lecompose.yamldu bundle plus une surcouche de test,infra/image/install-e2e.compose.yaml) et--env-file;-Test 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 ;.envest rempli parinstall_e2e_env_set, avec un serveur SMTP de capture, là où le README laisse la personne le renseigner à la main ;upreç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 versdocs/, aucuncastorniMAIL_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épond404. 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.shne couvre nipg_dump, nipg_restore, ni changement deKIREXO_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.jsonrefuseEdit(compose.yaml). Un nom de fichier nu s'applique à toute profondeur, avec la sémantique gitignore : la règle bloque aussiinstall/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, commecompose.yamletcompose.prod.yaml, par un script PHP lancé via Bash :file_put_contentsavec 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.examplen'est visé par aucune règle : il s'édite normalement.- Toute variable ajoutée en
${VAR:?…}dansinstall/compose.yamlexige une ligne activeVAR=dansinstall/.env.example; toute autre variable interpolée, au moins une ligne commentée#VAR=. - Une modification du service
workerdecompose.prod.yamlse reporte dansinstall/compose.yaml, hors écarts autorisés. - Toute variable ajoutée, retirée ou renommée dans
install/.env.examplese reporte dans le tableau des variables deinstall/README.md; toute commande modifiée s'y reporte aussi. Règles :install/README.md.
Voir aussi¶
- Trois entrées HTTP, un seul fichier Compose — le pourquoi de ces choix.
- Variables d'environnement — sémantique de chaque variable applicative.
- Commande
app:install:check— diagnostic d'une instance installée. - Assets de release et permaliens — publication du bundle avec chaque release.
- Worker Messenger et planificateur en production — conception du service
worker.