Déployer Kirexo en production¶
Vous êtes mainteneur·se de Kirexo avec un accès SSH au serveur de production et vous voulez mettre en ligne une release déjà buildée par la CI, ou revenir à une release antérieure. Cette recette couvre le déploiement, le rollback et l'exploitation du worker Messenger.
Vous installez Kirexo chez vous ?
Cette page décrit le déploiement du mainteneur depuis le dépôt (compose.prod.yaml). Pour votre propre instance, suivez Installer Kirexo chez soi.
Prérequis¶
- Une release a déjà été créée via la pipeline (cf. Créer un tag de release) : un tag Git de version sémantique (ex.
0.0.1) existe, et le jobdocker:manifest-proda publié l'imagekirexo-prod:<version>dans le registry. - Le serveur de prod est un hôte Docker avec Traefik en reverse proxy (cf. labels dans
compose.prod.yaml).linux/amd64est publié pour chaque release ;linux/arm64selon la release : si sa note contient une section « Architecture », elle est publiée pourlinux/amd64seulement. Aucune autre architecture n'est publiée. - Le dépôt est cloné sur le serveur (pour disposer de
compose.yamletcompose.prod.yaml), ou ces deux fichiers y sont présents. - Les secrets de prod (
APP_SECRET,POSTGRES_PASSWORD,RABBITMQ_PASSWORD,TYPESENSE_API_KEY,CADDY_MERCURE_JWT_SECRET,SENTRY_DSN,CLAUDE_API_KEY_CIPHER_KEY…) et les variables d'infra (SERVER_NAME…) sont exportés dans l'environnement du serveur — jamais versionnés. Voir À surcharger obligatoirement en production. - Les cinq variables d'exécution obligatoires (
KIREXO_RESERVED_DOMAINS,DEFAULT_URI,MAILER_DSN,MAILER_FROM_ADDRESS,MERCURE_PUBLIC_URL) sont exportées dans l'environnement persistant du serveur, cf. Exporter les variables obligatoires. CLAUDE_API_KEY_CIPHER_KEY(clé de chiffrement de la clé API Claude) est obligatoire : sans elle, Compose refuse de démarrer. Sa valeur doit rester identique d'un déploiement à l'autre, sinon la clé API Claude déjà enregistrée devient illisible. Génération et contrôle : Configurer la clé API Claude pour l'analyse IA.
CLAUDE_API_KEY_CIPHER_KEY est requise par toute commande Compose de prod
La déclaration ${CLAUDE_API_KEY_CIPHER_KEY:?…} de compose.prod.yaml est évaluée à chaque interpolation du fichier. Toute commande docker compose -f compose.yaml -f compose.prod.yaml … échoue si la variable n'est pas exportée dans le shell courant — pull et up, mais aussi down, logs, ps et exec. Exportez-la dans l'environnement persistant du serveur, au même endroit que APP_SECRET, plutôt qu'à la main avant chaque commande.
- Vous avez authentifié le démon Docker auprès du registry GitLab :
docker login registry.gitlab.com. cosign≥ v2.x est installé sur le serveur (paquet de distributioncosignou binaire téléchargé depuis les releases sigstore). C'est ce binaire qui vérifie la signature keyless de l'image avant le pull (cf. Vérifier la signature de l'image avant de la pull). Épinglez la même version majeure que celle utilisée par la CI (cf. Signature keyless dekirexo-prod) pour éviter une dérive de format d'attestation.
Exporter les variables obligatoires¶
compose.prod.yaml exige cinq variables sous la forme ${VAR:?…} et les transmet aux services php et worker. Rôle et forme de chacune : Variables d'exécution obligatoires.
-
Choisir les valeurs de l'instance. Exemple pour une application servie sur
kirexo.example.org:export KIREXO_RESERVED_DOMAINS=kirexo.example.org export DEFAULT_URI=https://kirexo.example.org export MAILER_DSN='smtp://smtp.example.org:587' # identifiants URL-encodés insérés avant l'hôte export MAILER_FROM_ADDRESS=noreply@example.org export MERCURE_PUBLIC_URL=https://kirexo.example.org/.well-known/mercure export TZ=UTC- L'hôte de
DEFAULT_URIdoit figurer dansKIREXO_RESERVED_DOMAINS, sinon le lien de réinitialisation du mot de passe aboutit sur un404. KIREXO_RESERVED_DOMAINSne liste que les domaines de l'application, jamais un domaine de site.- Ne pas exporter
MAIL_FROM: il est dérivé deMAILER_FROM_ADDRESSdans l'image. TZn'est pas obligatoire (défautUTC), mais l'exporter fige sa valeur (voir l'avertissement ci-dessous).
- L'hôte de
-
Placer ces lignes dans l'environnement persistant du serveur, au même endroit que
APP_SECRETetCLAUDE_API_KEY_CIPHER_KEY(fichier d'environnement chargé par le shell de déploiement, variables systemd, gestionnaire de secrets).MAILER_DSNcontient des identifiants : jamais dans un fichier versionné. -
Vérifier que l'interpolation voit bien vos valeurs, et non celles du dépôt :
docker compose -f compose.yaml -f compose.prod.yaml config \ | grep -E 'KIREXO_RESERVED_DOMAINS|DEFAULT_URI|MAILER_FROM_ADDRESS|MERCURE_PUBLIC_URL|TZ:'Chaque variable doit apparaître avec vos valeurs, dans l'environnement des services
phpetworker.MAILER_DSNest volontairement absente du filtre : elle contient des identifiants. Une valeur enlocalhost,mailer-intoukirexo.localvient du.envdu clone : voir l'avertissement ci-dessous.
Le .env du clone désarme :?
Docker Compose lit le .env du répertoire du projet pour l'interpolation. Sur un serveur qui contient un clone du dépôt, ce fichier versionné fournit les cinq variables avec leurs valeurs de développement : :? ne se déclenche pas, et l'instance démarre sans erreur, mais répond 404 partout, n'envoie aucun e-mail et génère des liens vers https://localhost. Une variable exportée dans le shell l'emporte sur .env : c'est pourquoi l'export doit être fait avant chaque commande, par l'environnement persistant, et vérifié à l'étape 3.
:? est évalué à chaque commande Compose
Comme pour CLAUDE_API_KEY_CIPHER_KEY, une variable absente fait échouer toute commande docker compose -f compose.yaml -f compose.prod.yaml … : pull et up, mais aussi down, logs, ps, exec. Une session SSH ouverte sans l'environnement de déploiement ne peut même pas lire les logs.
Un TZ du shell décale l'historique sans message
compose.prod.yaml déclare TZ: "${TZ:-UTC}" : le défaut UTC n'est atteint que si aucun TZ n'existe dans le shell qui lance docker compose. Un TZ posé par le profil du serveur ou par la session de l'opérateur est repris tel quel, et PHP écrit alors les nouvelles dates dans ce fuseau. Les dates étant stockées sans fuseau, changer d'environnement shell entre deux déploiements décale tout l'historique, sans erreur ni avertissement. Exportez TZ explicitement (étape 1), avec la valeur choisie à l'installation, et ne la changez plus. Raisons : Pourquoi le fuseau PHP est figé en dev et choisi à l'installation en production.
Le serveur pull, il ne build pas¶
Les services php et worker de compose.prod.yaml référencent la même image immuable poussée par la CI, au lieu de la builder sur place :
x-kirexo-prod-image: &kirexo-prod-image ${IMAGES_PREFIX:-registry.gitlab.com/shaurifr/kirexo/}kirexo-prod:${KIREXO_VERSION:-latest}
Le serveur pull cette image. Builder sur la prod serait non reproductible (build différent de celui testé par la CI), exigerait toute la toolchain Docker plus le code source sur le serveur, et ferait perdre la traçabilité de version. Le bloc build: est conservé en commentaire dans compose.prod.yaml uniquement pour un rebuild local ponctuel de debug — jamais pour un déploiement.
Deux variables pilotent l'image tirée (détail dans Image de production et préfixe de registry) :
KIREXO_VERSION— la version à déployer : un tag Git de version sémantiqueMAJEUR.MINEUR.CORRECTIF, sans préfixev(ex.0.0.1). Défautlatest.IMAGES_PREFIX— le préfixe de registry. Défaut prod :registry.gitlab.com/shaurifr/kirexo/(notez le/final obligatoire).
Toujours exporter KIREXO_VERSION
Le défaut latest est un tag mutable, réécrit à chaque release. Déployer sans KIREXO_VERSION, c'est déployer « la dernière release du moment » sans pouvoir la rejouer ni revenir en arrière de façon déterministe. Exportez toujours un tag précis.
kirexo-prod:<version> est un index : docker compose pull y choisit l'image qui correspond à l'architecture du serveur, sans réglage. L'index contient linux/amd64 et, selon la release, linux/arm64 ; une release sans arm64 le dit dans la section « Architecture » de sa note de release. Le registry contient aussi des tags kirexo-prod:<version>-amd64 et, parfois, kirexo-prod:<version>-arm64 : ce sont des étapes intermédiaires de la pipeline, qui servent à assembler l'index. N'y épinglez pas KIREXO_VERSION : ils ne font pas partie du contrat d'installation (cf. Images publiées dans le registry).
Vérifier la signature de l'image avant de la pull¶
Chaque image kirexo-prod poussée sur tag de release est signée par la CI en mode keyless via cosign (cf. Signature keyless de kirexo-prod). Avant tout docker compose pull, vérifiez côté serveur que l'image cible porte bien une signature émise par le pipeline GitLab de ce projet. Une image non signée ou signée par un autre pipeline doit faire refuser le déploiement.
export KIREXO_VERSION=0.0.1
cosign verify "registry.gitlab.com/shaurifr/kirexo/kirexo-prod:${KIREXO_VERSION}" \
--certificate-identity-regexp='^https://gitlab\.com/shaurifr/kirexo' \
--certificate-oidc-issuer='https://gitlab.com'
| Option | Rôle |
|---|---|
--certificate-identity-regexp='^https://gitlab\.com/shaurifr/kirexo' |
Restreint les signatures acceptées à celles émises par un pipeline du projet GitLab Kirexo. Toute autre identité (autre projet, autre namespace) est rejetée. |
--certificate-oidc-issuer='https://gitlab.com' |
Restreint l'émetteur OIDC au provider GitLab.com — un certificat Fulcio délivré sur la base d'un JWT GitHub Actions, par exemple, serait rejeté. |
Sur un tag de version, cette commande vérifie la signature de l'index. La CI signe l'index et chacune des images de plateforme qu'il référence (cf. Signature keyless de kirexo-prod) : la commande ci-dessus suffit pour décider du déploiement. Pour vérifier en plus l'image propre à l'architecture du serveur, voir Vérifier l'image de sa plateforme.
Variante durcie : n'accepter que les pipelines de tag de version
La regex ci-dessus accepte toute signature émise par un pipeline du projet. Pour n'accepter que celles d'un pipeline de tag semver, ancrez l'identité sub complète :
cosign verify "registry.gitlab.com/shaurifr/kirexo/kirexo-prod:${KIREXO_VERSION}" \
--certificate-identity-regexp='^https://gitlab\.com/shaurifr/kirexo//\.gitlab-ci\.yml@refs/tags/[0-9]+\.[0-9]+\.[0-9]+$' \
--certificate-oidc-issuer='https://gitlab.com'
Avant de l'adopter, comparez cette regex à l'identité sub réellement affichée par un cosign verify réussi (cf. Lire la sortie) : une regex qui ne correspond à aucune signature réelle bloquerait tous les déploiements.
Lire la sortie¶
Sur succès, cosign écrit en sortie une liste d'objets JSON contenant :
- les claims OIDC capturés par Fulcio au moment de la signature : URL du projet, ref / sha du commit, identité
subdu pipeline (https://gitlab.com/<group>/<project>//.gitlab-ci.yml@refs/tags/<version>, ex.…//.gitlab-ci.yml@refs/tags/0.0.1) ; - le hash de l'entrée Rekor correspondante (
logIndex,logID) — preuve immuable que la signature a bien été publiée dans le log de transparence public.
La chaîne de confiance est complète : le tag de version est lié au pipeline GitLab qui l'a buildé, lui-même attesté par une entrée Rekor que l'on peut auditer a posteriori sans dépendre du serveur GitLab.
Sur échec (signature absente, certificat émis par un autre projet, image altérée), cosign termine en code non nul avec un message du type no matching signatures ou certificate identity does not match. Ne pas déployer : reprendre l'image, identifier la source de la divergence, et ré-investiguer côté pipeline avant d'aller plus loin.
Intégrer la vérification au shell de déploiement
Encapsulez la commande dans la même fonction shell qui fait le pull / up -d : un cosign verify ... || exit 1 placé avant docker compose pull interdit physiquement un déploiement non vérifié. Plus de risque d'oublier l'étape un soir de hotfix.
Vérifier l'image de sa plateforme¶
Étape facultative : elle vérifie, par son digest, l'image de plateforme que docker compose pull va réellement tirer.
-
Lister les images de plateforme de l'index et leur digest :
docker buildx imagetools inspect "registry.gitlab.com/shaurifr/kirexo/kirexo-prod:${KIREXO_VERSION}" \ --format '{{range .Manifest.Manifests}}{{with .Platform}}{{.OS}}/{{.Architecture}}{{end}} {{.Digest}}{{"\n"}}{{end}}'La sortie compte une ligne par plateforme publiée :
linux/amd64 sha256:…, etlinux/arm64 sha256:…si la release inclut arm64.uname -mdonne l'architecture du serveur :x86_64correspond àlinux/amd64,aarch64àlinux/arm64. -
Vérifier la signature du digest de votre plateforme, avec la même identité :
Un échec sur le digest de plateforme alors que le tag de version passe signale une image qui n'est pas celle signée par la pipeline : ne pas déployer.
Déployer une release¶
Sauvegarder la base avant up -d
En production, les migrations Doctrine sont appliquées automatiquement au démarrage du conteneur php (RUN_MIGRATIONS vaut 1 dans compose.prod.yaml). Dès que up -d recrée le conteneur sur la nouvelle image, le schéma est modifié. Revenir ensuite à une image antérieure ne défait pas ces migrations : seule une sauvegarde prise avant permet de restaurer l'état précédent.
-
Identifier la version à déployer (l'onglet Tags ou Deploy → Releases sur GitLab, ou Deploy → Container Registry pour confirmer que
kirexo-prod:<version>existe). Lire ses notes de version : tant que Kirexo est en0.y.z, un changement de mineure (ex.0.1.x→0.2.0) peut casser l'installation — variable renommée, étape manuelle, migration non réversible — et la note de version décrit alors la marche à suivre. Une release qui change la version majeure de PostgreSQL suit Monter PostgreSQL de version majeure à la place de cette procédure. -
Sauvegarder la base, par exemple avec
pg_dumpdans le conteneurdatabase:docker compose -f compose.yaml -f compose.prod.yaml exec -T database \ pg_dump -U "${POSTGRES_USER:-app}" "${POSTGRES_DB:-app}" > "kirexo-$(date +%Y%m%d%H%M).sql"Vérifier que le fichier produit n'est pas vide avant de continuer.
-
Arrêter le worker Messenger :
Sans cet arrêt, l'ancien worker peut encore traiter des messages, avec l'ancien code, pendant que le nouveau conteneur
phpmigre le schéma. Arrêtez-le à chaque mise à jour, même quand la release semble ne contenir aucune migration destructive. Les messages déposés pendant l'arrêt attendent dans RabbitMQ. -
Sur le serveur, exporter la version puis pull et redémarrer :
export KIREXO_VERSION=0.0.1 docker compose -f compose.yaml -f compose.prod.yaml pull docker compose -f compose.yaml -f compose.prod.yaml up -dpullrécupère l'image taggée depuis le registry ;up -drecrée le conteneurphpsur la nouvelle image. Au démarrage, son entrypoint attend la base, applique les migrations en attente, puis lance FrankenPHP. Le worker n'est recréé qu'une foisphppassé àhealthy, donc sur le schéma migré. Les autres services (database,redis,rabbitmq,typesense,gotenberg) ne changent pas d'image et ne sont redémarrés que si nécessaire. -
Suivre l'application des migrations :
Attendre la ligne
[kirexo] Migrations Doctrine à jour.Sur un schéma déjà à jour, Doctrine l'indique et la ligne arrive aussitôt. -
Vérifier que les conteneurs sont sains :
Le service
phpdoit êtrerunningethealthy(le healthcheck interroge l'endpoint admin Caddy:2019/metrics, défini danscompose.yaml). Pendant une migration longue, il peut resterstartingjusqu'à 5 minutes (start_period: 300sdanscompose.prod.yaml) : c'est attendu, le serveur ne démarre qu'après les migrations. S'il passeunhealthy, voir Le conteneurphpresteunhealthyaprès une mise à jour.Chaque instance du service
workerdoit êtrerunning. Elle n'affiche pas d'état de santé : son healthcheck est désactivé.
Rendre la version persistante
Pour qu'un redémarrage ultérieur du serveur ne retombe pas sur le défaut latest, persistez KIREXO_VERSION côté serveur (variable d'environnement systemd, fichier d'env chargé par le shell de déploiement, gestionnaire de config…). Ne la mettez pas dans un fichier versionné du dépôt.
Revenir à une version antérieure (rollback)¶
Le rollback consiste à réexporter un KIREXO_VERSION antérieur et à re-pull — l'image cible existe déjà dans le registry, rien à rebuilder.
Exemple : retour de 0.0.2 vers 0.0.1.
export KIREXO_VERSION=0.0.1 # une version connue et fonctionnelle
docker compose -f compose.yaml -f compose.prod.yaml stop worker
docker compose -f compose.yaml -f compose.prod.yaml pull
docker compose -f compose.yaml -f compose.prod.yaml up -d
Comme pour un déploiement, le worker est arrêté avant pull et up -d, puis recréé sur l'image cible une fois php sain.
Le rollback ne couvre que l'image applicative
Revenir à une image antérieure ne défait pas les migrations de base de données déjà appliquées : elles l'ont été automatiquement au démarrage de la release fautive. Au redémarrage sur l'ancienne image, l'entrypoint ne trouve aucune migration à jouer et ne revient pas en arrière. Si la release fautive a joué une migration Doctrine destructive ou incompatible avec l'ancienne image, restaurez la sauvegarde prise avant son up -d (cf. Déployer une release). Le tag d'image ne versionne que le code, pas l'état du schéma.
Monter PostgreSQL de version majeure (16 → 18)¶
PostgreSQL ne lit pas les fichiers de données d'une autre version majeure. Le service database de la prod garde son volume historique database_data, monté sur /var/lib/postgresql (compose.prod.yaml). Une fois le clone passé à la version qui utilise postgres:18-alpine (compose.yaml, POSTGRES_VERSION=18 dans .env), PostgreSQL 18 refuse de démarrer sur ce volume, qui contient des données 16 : le conteneur database sort en erreur et up -d échoue. C'est voulu : rien n'est effacé, la base ne repart pas vide en silence. La montée se fait par pg_dump puis restauration.
Les commandes suivantes se lancent depuis le clone, avec l'environnement de déploiement chargé (cf. Exporter les variables obligatoires).
-
Avant de mettre à jour le clone, arrêter l'application, puis exporter la base avec l'image 16 encore en service :
docker compose -f compose.yaml -f compose.prod.yaml stop worker php docker compose -f compose.yaml -f compose.prod.yaml exec -T database \ pg_dump -U "${POSTGRES_USER:-app}" "${POSTGRES_DB:-app}" > kirexo-pg16.sql tail -n 3 kirexo-pg16.sqlLa dernière ligne utile doit être
-- PostgreSQL database dump complete. Copier ce fichier hors du serveur avant de continuer. -
Arrêter la pile, sans
-v: -
Mettre le volume des données 16 de côté. Son nom complet est préfixé par le nom du projet Compose (par défaut, le nom du répertoire du clone) : le relever avec
docker volume ls --filter name=database_data. Docker ne renomme pas un volume : le copier, puis supprimer l'original.VOL=kirexo_database_data # nom relevé par docker volume ls docker volume create "${VOL}_pg16" docker run --rm -v "${VOL}:/from:ro" -v "${VOL}_pg16:/to" alpine cp -a /from/. /to/ docker volume rm "${VOL}"La copie
…_pg16sert de retour arrière. Elle n'est pas lisible par PostgreSQL 18 ; supprimez-la une fois la nouvelle base validée. -
Mettre à jour le clone vers la release qui passe à PostgreSQL 18, exporter
KIREXO_VERSION, puis démarrer la base seule : PostgreSQL 18 initialise un volumedatabase_dataneuf. -
Restaurer l'export :
docker compose -f compose.yaml -f compose.prod.yaml exec -T database \ psql -v ON_ERROR_STOP=1 -U "${POSTGRES_USER:-app}" -d "${POSTGRES_DB:-app}" < kirexo-pg16.sqlRestaurer avant de démarrer
php: sur une base vide, son entrypoint jouerait toutes les migrations, et la restauration entrerait ensuite en conflit avec le schéma créé. -
Démarrer le reste de la pile, puis suivre les étapes 5 et 6 de Déployer une release :
L'entrypoint de
phptrouve le schéma restauré et n'applique que les migrations propres à la nouvelle release.
Revenir à PostgreSQL 16
Arrêter la pile (down), supprimer le volume database_data créé par la 18, le recréer à partir de la copie (même commande docker run … cp -a, source et cible inversées), remettre le clone et KIREXO_VERSION sur la release précédente, puis up -d. Les données écrites depuis la montée sont perdues.
Le worker Messenger¶
Le service worker consomme les transports Messenger : e-mails et analyse IA (async), diffusion des articles publiés sur le site public (plugin_web), tâches périodiques comme la purge de la corbeille (scheduler_default). Il tourne sur la même image et avec le même environnement que php, et ne démarre qu'une fois php sain. Sans lui, aucun de ces traitements n'a lieu, et rien ne le signale.
Les exemples ci-dessous abrègent la pile Compose de production :
Lire les logs du worker¶
La première ligne d'une instance qui démarre annonce les transports consommés :
Avec -vv, chaque message traité produit ensuite une ligne Received message puis Message handled. Toutes les heures (--time-limit=3600), ou dès que la mémoire dépasse 192 Mo, le worker sort en 0 et Docker le relance (restart: always) : ce recyclage est normal.
Pour ne lire qu'une instance quand il y en a plusieurs, visez son conteneur (docker logs -f <projet>-worker-2, le nom exact est donné par dcp ps).
Changer le nombre d'instances¶
Le nombre d'instances vient de KIREXO_WORKER_REPLICAS (défaut 1). Pour le rendre persistant, exportez-le dans l'environnement du serveur, au même endroit que KIREXO_VERSION, jamais dans .env (cf. Worker Messenger) :
Pour un changement ponctuel, --scale a priorité sur la variable :
Un dcp up -d ultérieur sans --scale revient à la valeur de KIREXO_WORKER_REPLICAS, soit 1 si elle n'est pas exportée.
Plusieurs instances se partagent les messages des files RabbitMQ. Une seule déclenche les tâches périodiques : les autres attendent et prennent le relais si elle s'arrête. Ajouter des instances n'accélère donc pas la purge planifiée (cf. Plusieurs workers : haute disponibilité).
Vérifier qu'un seul worker détient le verrou du planificateur¶
Avec un ou plusieurs workers démarrés, la sortie compte exactement deux lignes : un jeton et __write__. Deux jetons signaleraient deux détenteurs : vérifiez alors que toutes les instances reçoivent le même LOCK_DSN.
Arrêter ou redémarrer le worker¶
dcp stop worker # arrête toutes les instances
dcp start worker # les redémarre
dcp restart worker # arrêt puis redémarrage
À l'arrêt, chaque instance termine le message en cours puis sort en 0, en quelques secondes si elle est inactive. Docker lui laisse 120 s (stop_grace_period) avant de la tuer. Un message interrompu par cet arrêt forcé n'est pas perdu : RabbitMQ le redélivre à la prochaine instance.
Pour vérifier qu'un arrêt a été propre :
Le code attendu est 0. Un 137 signale un arrêt par SIGKILL, après expiration du délai de grâce.
Au redémarrage du serveur
Le démon Docker relance les conteneurs sans respecter l'ordre de depends_on : le worker peut repartir avant que php soit sain. C'est sans conséquence, le schéma ayant été migré au dernier déploiement.
SBOM disponible en asset de la release¶
Chaque release GitLab expose en assets des Software Bill of Materials de l'image kirexo-prod:<version> correspondante : un par architecture publiée et par format (produits par le job release:sbom, cf. Job release:sbom). Les deux SBOM linux/amd64 sont toujours présents ; les deux SBOM linux/arm64 seulement si l'image arm64 a été publiée pour cette release :
| Asset (widget « Assets » de la release) | Format | Consommateurs typiques |
|---|---|---|
| SBOM linux/amd64 (SPDX JSON), SBOM linux/arm64 (SPDX JSON) | SPDX 2.x — référence côté conformité (OpenChain, NTIA Minimum Elements). | Outils d'audit logiciel, exports juridiques. |
| SBOM linux/amd64 (CycloneDX JSON), SBOM linux/arm64 (CycloneDX JSON) | CycloneDX — référence côté outillage de sécurité. | Dependency-Track, Trivy en mode SBOM, Snyk. |
Chaque fichier liste les paquets OS Alpine, les extensions PHP et les dépendances Composer présentes dans vendor/ de l'image d'une architecture. Utilisez celui de l'architecture de votre serveur (uname -m : x86_64 pour amd64, aarch64 pour arm64). Les SBOM sont publiés dans le Generic Package Registry du projet et n'expirent pas.
Pour les télécharger sans passer par l'interface, depuis la dernière release (exemple pour un serveur arm64, remplacez par amd64 le cas échéant) :
curl -fsSLO https://gitlab.com/shaurifr/kirexo/-/releases/permalink/latest/downloads/sbom/kirexo-prod-linux-arm64.spdx.json
curl -fsSLO https://gitlab.com/shaurifr/kirexo/-/releases/permalink/latest/downloads/sbom/kirexo-prod-linux-arm64.cdx.json
Les permaliens linux/arm64 n'existent que si la dernière release inclut arm64 : sur une release linux/amd64 seule, curl -f échoue sur ces deux URL.
Pour la version déployée, remplacez permalink/latest par le tag :
curl -fsSLO "https://gitlab.com/shaurifr/kirexo/-/releases/${KIREXO_VERSION}/downloads/sbom/kirexo-prod-linux-amd64.cdx.json"
Liste complète des permaliens SBOM : Assets de release et permaliens.
latest désigne la release publiée le plus récemment, pas forcément la plus haute version (cf. Ce que désigne latest) : pour auditer l'image en service, utilisez la forme par version.
Si vous opérez un Dependency-Track ou un Trivy en pipeline d'audit, alimentez-le directement avec ces fichiers. Aucun retraitement intermédiaire n'est nécessaire — les SBOM sont émis dans des formats consommés tels quels par ces outils.
Cas d'erreur¶
Le conteneur php reste unhealthy après une mise à jour : migration en échec¶
Quand une migration échoue, ou quand RUN_MIGRATIONS porte une valeur autre que 0 ou 1, l'entrypoint ne démarre pas le serveur mais garde le conteneur en vie : pas de boucle de redémarrage, état unhealthy (après le délai de grâce de 5 minutes). Le site ne répond plus, et up -d échoue sur dependency failed to start: container … is unhealthy : le worker, qui attend un php sain, n'est pas recréé. Il le sera par un nouvel up -d une fois php réparé (étape 5 ci-dessous).
-
Lire le diagnostic :
Chercher la ligne
[kirexo] ERREUR : …. La sortie de Doctrine qui la précède donne la cause d'une migration en échec. -
Corriger la cause, selon le message.
-
valeur invalide RUN_MIGRATIONS=…— corriger d'abord la valeur dans l'environnement du serveur (1, ou retirer la variable pour revenir au défaut decompose.prod.yaml), et vérifier que.envne contient aucune ligne activeRUN_MIGRATIONS=. Recréer ensuite le conteneur pour qu'il relise l'environnement :Ne pas suivre les lignes de reprise affichées par le conteneur (
doctrine:migrations:migratepuisdocker restart) : elles sont communes aux deux causes, et unrestartconserve la valeur invalide. Les étapes 3 et 4 sont inutiles ici : au démarrage du conteneur recréé, l'entrypoint joue lui-même les migrations. -
échec des migrations Doctrine (code N)— corriger la cause signalée par Doctrine : base pleine, droits, données incompatibles avec la migration… Si c'est la migration elle-même qui est fautive, déployer une release corrigée (KIREXO_VERSION,pull,up -d) ou revenir à la release précédente en restaurant la sauvegarde ; les étapes 3 et 4 sont alors inutiles.
-
-
Rejouer les migrations dans le conteneur, qui est toujours en vie :
docker compose -f compose.yaml -f compose.prod.yaml exec php bin/console doctrine:migrations:migrate --no-interaction --all-or-nothingAu démarrage, l'entrypoint applique les migrations en une seule transaction (
--all-or-nothing) : après un échec, le schéma est resté dans son état antérieur et cette commande rejoue l'ensemble, avec la même option. -
Redémarrer le conteneur :
L'entrypoint rejoue les migrations (aucune n'est plus en attente), puis démarre FrankenPHP. Vérifier le retour à
healthyavecps. -
Recréer le worker, resté arrêté depuis l'étape 3 du déploiement :
Messages et comportement détaillés : RUN_MIGRATIONS.
Le conteneur reste unhealthy : secret d'exemple refusé¶
En production, l'entrypoint refuse de lancer le serveur et le worker quand APP_SECRET, le mot de passe PostgreSQL, le secret Mercure ou CLAUDE_API_KEY_CIPHER_KEY est absent, vide ou égal à une valeur d'exemple. Le conteneur reste en vie, unhealthy, sans boucle de redémarrage ; up -d échoue sur dependency failed to start, le worker attendant un php sain.
-
Identifier les secrets refusés :
Chaque secret fautif a sa ligne
[kirexo] - <libellé> : absente, vide ou valeur d'exemple. Générer : <commande>. Le libellé nomme la variable à renseigner côté hôte, entre parenthèses quand elle diffère de celle du conteneur (POSTGRES_PASSWORD (dans DATABASE_URL),… (CADDY_MERCURE_JWT_SECRET)). Si la ligneERREURannoncegarde-fou des secrets inopérant, l'image est incomplète : redéployer une image publiée par la pipeline d'un tag, les étapes suivantes ne s'appliquent pas. -
Générer une valeur pour chaque secret cité, avec la commande indiquée :
openssl rand -hex 32 # APP_SECRET, POSTGRES_PASSWORD, CADDY_MERCURE_JWT_SECRET openssl rand -base64 32 # CLAUDE_API_KEY_CIPHER_KEYPour
CLAUDE_API_KEY_CIPHER_KEY, ne générer une nouvelle clé que si aucune clé API Claude n'est encore enregistrée : sinon, reprendre la valeur existante (cf. Configurer la clé API Claude pour l'analyse IA). -
Si
POSTGRES_PASSWORDest cité et que la base contient déjà des données, changer d'abord le mot de passe du rôle dans PostgreSQL. Le volume de la base a été initialisé avec l'ancien mot de passe, et changer la variable ne le modifie pas : le conteneurphprecréé ne pourrait plus se connecter. Depuis le conteneurdatabase, qui accepte la connexion locale :docker compose -f compose.yaml -f compose.prod.yaml exec database psql -U "${POSTGRES_USER:-app}" -d "${POSTGRES_DB:-app}"Puis, dans
psql, saisir la nouvelle valeur à l'invite (elle n'apparaît ni à l'écran ni dans l'historique du shell) :Remplacer
apppar la valeur dePOSTGRES_USERsi elle diffère. -
Placer les nouvelles valeurs dans l'environnement persistant du serveur, au même endroit que les variables obligatoires, puis les charger dans le shell courant. Jamais dans le
.envdu clone : il est versionné. Le message du conteneur mentionne « le fichier .env de l'installation » : sur cette procédure, c'est cet environnement persistant. -
Recréer les conteneurs pour qu'ils relisent l'environnement :
restart phpne suffit pas : un redémarrage conserve l'environnement de création et retombe dans le même refus. -
Vérifier le retour à
healthyavecps, puis lancer le diagnostic complet :Il contrôle aussi le mot de passe RabbitMQ, que l'entrypoint ne vérifie pas. Verdicts et remédiations : Commande
app:install:check.
Secrets contrôlés, liste des valeurs refusées et messages : Garde-fou des secrets d'exemple.
docker compose pull échoue sur manifest unknown ou not found¶
Le tag KIREXO_VERSION exporté ne correspond à aucune image dans le registry. Vérifier dans Deploy → Container Registry que kirexo-prod:<tag> existe — il n'est créé que si le job docker:manifest-prod a réussi sur la pipeline du tag, donc si docker:build-prod (amd64) est vert ; docker:build-prod-arm64 est best-effort et ne conditionne pas l'index (cf. Créer un tag de release). La présence de kirexo-prod:<tag>-amd64 seule signale une pipeline de tag interrompue : l'index n'a pas été assemblé, la version n'est pas installable. Un kirexo-prod:<tag>-arm64 peut aussi venir d'une jambe arm64 tombée après son push : il n'entre pas dans l'index et ne s'installe pas.
Un no matching manifest for linux/arm64 sur un serveur arm64 signale une release publiée pour linux/amd64 seulement : sa note de release le dit dans une section « Architecture ». Déployez une release qui inclut arm64. Un no matching manifest for linux/… sur une autre architecture signale un serveur ni amd64 ni arm64 : aucune image n'est publiée pour elle.
docker compose échoue sur CLAUDE_API_KEY_CIPHER_KEY manquante ou vide¶
La variable CLAUDE_API_KEY_CIPHER_KEY n'est pas exportée dans le shell, ou elle est vide. Exportez la valeur existante, conservée dans l'environnement de déploiement du serveur, puis relancez pull / up -d. N'en générez pas une nouvelle si une clé API Claude est déjà enregistrée : elle deviendrait illisible et devrait être ressaisie dans /admin/reglages (cf. Configurer la clé API Claude pour l'analyse IA).
docker compose échoue sur <VARIABLE> manquante ou vide¶
Le message nomme l'une des cinq variables obligatoires (KIREXO_RESERVED_DOMAINS, DEFAULT_URI, MAILER_DSN, MAILER_FROM_ADDRESS, MERCURE_PUBLIC_URL). Elle n'est pas exportée dans le shell courant, ou elle est vide. Charger l'environnement de déploiement du serveur, puis relancer la commande. Si la variable n'y figure pas encore, l'ajouter selon Exporter les variables obligatoires.
L'application répond 404 partout, /login compris¶
Le domaine servi n'est pas dans KIREXO_RESERVED_DOMAINS : la résolution Host → Site le traite comme un domaine de site inconnu. Cause la plus fréquente : la variable n'a pas été exportée, et l'interpolation a repris la valeur de développement du .env du clone (localhost,127.0.0.1,…) sans déclencher :?. Même cause probable si les e-mails ne partent pas ou si le lien de réinitialisation pointe vers https://localhost.
- Contrôler les valeurs vues par Compose (étape 3 de Exporter les variables obligatoires).
- Exporter les bonnes valeurs dans l'environnement persistant du serveur.
-
Recréer les conteneurs pour qu'ils relisent l'environnement :
docker compose pull échoue sur unauthorized / denied¶
Le démon Docker du serveur n'est pas (ou plus) authentifié auprès du registry. Relancer docker login registry.gitlab.com avec un compte ayant accès au projet.
Le préfixe d'image est collé au nom (kirexokirexo-prod)¶
IMAGES_PREFIX a été redéfini manuellement sans / final. Le corriger pour qu'il se termine par une barre oblique (cf. l'avertissement dédié).
cosign verify échoue avec no matching signatures¶
L'image cible n'a pas été signée par le pipeline GitLab Kirexo. Causes possibles : tag manuellement poussé hors release officielle (ex. wip-foo), image antérieure à l'introduction de docker:sign-prod, ou divergence d'identité (autre fork du projet). Refuser le déploiement tant que la signature n'est pas valide ; relancer une release officielle via Créer un tag de release si nécessaire.
cosign verify échoue avec certificate identity does not match¶
L'image a été signée — mais par un pipeline qui ne matche pas la regex d'identité (autre namespace, autre projet, ou JWT émis par un provider OIDC différent de GitLab). Vérifier que le tag pointe bien sur le bon registry (registry.gitlab.com/shaurifr/kirexo/kirexo-prod:<tag>) ; ne jamais assouplir la regex pour faire passer une signature suspecte.
Voir aussi¶
- Créer un tag de release — produire l'image
kirexo-prod:<tag>que cette recette déploie. - Image de production et préfixe de registry — détail de
KIREXO_VERSIONetIMAGES_PREFIX. - Pipeline GitLab CI — Images publiées — quels tags la CI pousse et quand.
- Pipeline GitLab CI — Signature keyless de
kirexo-prod— détail du jobdocker:sign-prodet chaîne de confiance Fulcio / Rekor. - Pipeline GitLab CI — Job
release:sbom— génération des SBOM SPDX et CycloneDX attachés à la release. - Assets de release et permaliens — fichiers attachés à chaque release, paquet générique et URL de téléchargement.
- Supply chain et signatures — pourquoi signer et publier un SBOM.
RUN_MIGRATIONS— défauts, portée et messages des migrations au démarrage.- Pourquoi les migrations sont jouées au démarrage du seul service applicatif — l'endroit, le migrateur unique, l'attente plutôt que la sortie.
- Worker Messenger —
KIREXO_WORKER_TRANSPORTSetKIREXO_WORKER_REPLICAS. - Commande
app:install:check— diagnostic d'une installation : secrets, migrations, assets, SMTP, worker. - Pourquoi refuser de démarrer plutôt qu'avertir, et diagnostiquer par contrôles indépendants — le garde-fou des secrets et le diagnostic.
- Variables d'exécution obligatoires — forme et effet des cinq variables exigées par
compose.prod.yaml. - Fuseau horaire (
TZ) — comportement deTZen production, valeurs vides ou invalides. - Pourquoi
TRUSTED_HOSTSn'est pas le filtre desHosten production — les protections qui prennent le relais. - Pourquoi un worker Messenger dédié et un verrou sur le planificateur — service dédié, ordre de démarrage, verrou, arrêt propre.
- Configurer le domaine GitLab Pages — non lié au déploiement applicatif, concerne la doc.