Aller au contenu

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 job docker:manifest-prod a publié l'image kirexo-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/amd64 est publié pour chaque release ; linux/arm64 selon la release : si sa note contient une section « Architecture », elle est publiée pour linux/amd64 seulement. Aucune autre architecture n'est publiée.
  • Le dépôt est cloné sur le serveur (pour disposer de compose.yaml et compose.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 distribution cosign ou 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 de kirexo-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.

  1. 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_URI doit figurer dans KIREXO_RESERVED_DOMAINS, sinon le lien de réinitialisation du mot de passe aboutit sur un 404.
    • KIREXO_RESERVED_DOMAINS ne liste que les domaines de l'application, jamais un domaine de site.
    • Ne pas exporter MAIL_FROM : il est dérivé de MAILER_FROM_ADDRESS dans l'image.
    • TZ n'est pas obligatoire (défaut UTC), mais l'exporter fige sa valeur (voir l'avertissement ci-dessous).
  2. Placer ces lignes dans l'environnement persistant du serveur, au même endroit que APP_SECRET et CLAUDE_API_KEY_CIPHER_KEY (fichier d'environnement chargé par le shell de déploiement, variables systemd, gestionnaire de secrets). MAILER_DSN contient des identifiants : jamais dans un fichier versionné.

  3. 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 php et worker. MAILER_DSN est volontairement absente du filtre : elle contient des identifiants. Une valeur en localhost, mailer-int ou kirexo.local vient du .env du 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émantique MAJEUR.MINEUR.CORRECTIF, sans préfixe v (ex. 0.0.1). Défaut latest.
  • 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é sub du 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.

  1. 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:…, et linux/arm64 sha256:… si la release inclut arm64. uname -m donne l'architecture du serveur : x86_64 correspond à linux/amd64, aarch64 à linux/arm64.

  2. Vérifier la signature du digest de votre plateforme, avec la même identité :

    cosign verify "registry.gitlab.com/shaurifr/kirexo/kirexo-prod@sha256:<digest de votre plateforme>" \
        --certificate-identity-regexp='^https://gitlab\.com/shaurifr/kirexo' \
        --certificate-oidc-issuer='https://gitlab.com'
    

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.

  1. 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 en 0.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.

  2. Sauvegarder la base, par exemple avec pg_dump dans le conteneur database :

    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.

  3. Arrêter le worker Messenger :

    docker compose -f compose.yaml -f compose.prod.yaml stop worker
    

    Sans cet arrêt, l'ancien worker peut encore traiter des messages, avec l'ancien code, pendant que le nouveau conteneur php migre 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.

  4. 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 -d
    

    pull récupère l'image taggée depuis le registry ; up -d recrée le conteneur php sur 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 fois php passé à 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.

  5. Suivre l'application des migrations :

    docker compose -f compose.yaml -f compose.prod.yaml logs -f php
    

    Attendre la ligne [kirexo] Migrations Doctrine à jour. Sur un schéma déjà à jour, Doctrine l'indique et la ligne arrive aussitôt.

  6. Vérifier que les conteneurs sont sains :

    docker compose -f compose.yaml -f compose.prod.yaml ps
    

    Le service php doit être running et healthy (le healthcheck interroge l'endpoint admin Caddy :2019/metrics, défini dans compose.yaml). Pendant une migration longue, il peut rester starting jusqu'à 5 minutes (start_period: 300s dans compose.prod.yaml) : c'est attendu, le serveur ne démarre qu'après les migrations. S'il passe unhealthy, voir Le conteneur php reste unhealthy après une mise à jour.

    Chaque instance du service worker doit être running. 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).

  1. 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.sql
    

    La dernière ligne utile doit être -- PostgreSQL database dump complete. Copier ce fichier hors du serveur avant de continuer.

  2. Arrêter la pile, sans -v :

    docker compose -f compose.yaml -f compose.prod.yaml down
    
  3. 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 …_pg16 sert de retour arrière. Elle n'est pas lisible par PostgreSQL 18 ; supprimez-la une fois la nouvelle base validée.

  4. Mettre à jour le clone vers la release qui passe à PostgreSQL 18, exporter KIREXO_VERSION, puis démarrer la base seule : PostgreSQL 18 initialise un volume database_data neuf.

    export KIREXO_VERSION=0.0.2   # la release qui passe à PostgreSQL 18
    docker compose -f compose.yaml -f compose.prod.yaml pull
    docker compose -f compose.yaml -f compose.prod.yaml up -d --wait database
    
  5. 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.sql
    

    Restaurer 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éé.

  6. Démarrer le reste de la pile, puis suivre les étapes 5 et 6 de Déployer une release :

    docker compose -f compose.yaml -f compose.prod.yaml up -d
    

    L'entrypoint de php trouve 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 :

alias dcp='docker compose -f compose.yaml -f compose.prod.yaml'

Lire les logs du worker

dcp logs -f worker

La première ligne d'une instance qui démarre annonce les transports consommés :

[OK] Consuming messages from transports "scheduler_default, plugin_web, async".

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) :

export KIREXO_WORKER_REPLICAS=2
dcp up -d

Pour un changement ponctuel, --scale a priorité sur la variable :

dcp up -d --scale worker=3

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

dcp exec redis redis-cli ZRANGE kirexo_scheduler_default 0 -1

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 :

docker inspect -f '{{.State.ExitCode}}' <projet>-worker-1

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).

  1. Lire le diagnostic :

    docker compose -f compose.yaml -f compose.prod.yaml logs php
    

    Chercher la ligne [kirexo] ERREUR : …. La sortie de Doctrine qui la précède donne la cause d'une migration en échec.

  2. 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 de compose.prod.yaml), et vérifier que .env ne contient aucune ligne active RUN_MIGRATIONS=. Recréer ensuite le conteneur pour qu'il relise l'environnement :

      docker compose -f compose.yaml -f compose.prod.yaml up -d php
      

      Ne pas suivre les lignes de reprise affichées par le conteneur (doctrine:migrations:migrate puis docker restart) : elles sont communes aux deux causes, et un restart conserve 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.

  3. 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-nothing
    

    Au 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.

  4. Redémarrer le conteneur :

    docker compose -f compose.yaml -f compose.prod.yaml restart php
    

    L'entrypoint rejoue les migrations (aucune n'est plus en attente), puis démarre FrankenPHP. Vérifier le retour à healthy avec ps.

  5. Recréer le worker, resté arrêté depuis l'étape 3 du déploiement :

    docker compose -f compose.yaml -f compose.prod.yaml up -d
    

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.

  1. Identifier les secrets refusés :

    docker compose -f compose.yaml -f compose.prod.yaml logs php | grep '\[kirexo\]'
    

    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 ligne ERREUR annonce garde-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.

  2. 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_KEY
    

    Pour 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).

  3. Si POSTGRES_PASSWORD est 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 conteneur php recréé ne pourrait plus se connecter. Depuis le conteneur database, 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) :

    \password app
    \q
    

    Remplacer app par la valeur de POSTGRES_USER si elle diffère.

  4. 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 .env du clone : il est versionné. Le message du conteneur mentionne « le fichier .env de l'installation » : sur cette procédure, c'est cet environnement persistant.

  5. Recréer les conteneurs pour qu'ils relisent l'environnement :

    docker compose -f compose.yaml -f compose.prod.yaml up -d
    

    restart php ne suffit pas : un redémarrage conserve l'environnement de création et retombe dans le même refus.

  6. Vérifier le retour à healthy avec ps, puis lancer le diagnostic complet :

    docker compose -f compose.yaml -f compose.prod.yaml exec php bin/console app:install:check
    

    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.

  1. Contrôler les valeurs vues par Compose (étape 3 de Exporter les variables obligatoires).
  2. Exporter les bonnes valeurs dans l'environnement persistant du serveur.
  3. Recréer les conteneurs pour qu'ils relisent l'environnement :

    docker compose -f compose.yaml -f compose.prod.yaml up -d
    

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