Pourquoi les migrations sont jouées au démarrage du seul service applicatif¶
En production, Kirexo applique ses migrations Doctrine sans geste manuel : le conteneur php les joue au démarrage, avant de lancer son serveur. Le mécanisme tient en quelques lignes de frankenphp/docker-entrypoint.sh, piloté par la variable RUN_MIGRATIONS. Cette page explique les choix qui le structurent : l'endroit, le nombre de migrateurs, la réaction à l'échec et le défaut en développement. La procédure de déploiement et de dépannage est dans Déployer Kirexo en production.
Le problème de départ¶
Une nouvelle version de Kirexo peut arriver avec des migrations : une table, une colonne, une extension PostgreSQL (unaccent), la table messenger_messages du transport Doctrine. Tant qu'elles ne sont pas appliquées, le code tourne sur un schéma qui ne lui correspond pas, et les erreurs apparaissent requête par requête, sans signal global.
Laisser l'opération à la main du mainteneur, c'est accepter qu'elle soit oubliée. C'est aussi accepter une fenêtre, entre up -d et le migrate manuel, pendant laquelle la nouvelle image sert déjà du trafic sur l'ancien schéma. Pour quelqu'un qui installe Kirexo sans connaître son historique, c'est un piège. Le modèle retenu est celui d'applications auto-hébergées comme Miniflux : une manette, active par défaut en production.
Pourquoi dans l'entrypoint, avant le serveur¶
Plusieurs emplacements étaient possibles.
Après le démarrage du serveur, en tâche de fond ou dans un hook applicatif, les migrations s'exécuteraient pendant que l'application répond déjà. Le serveur serait « sain » au sens du healthcheck avant que le schéma soit à jour.
Dans un service Compose dédié, lancé une fois puis arrêté, l'ordre deviendrait une affaire de déclaration : chaque service qui a besoin du schéma devrait dépendre explicitement de la fin de ce migrateur, et un oubli dans un fichier Compose suffirait à rouvrir la fenêtre. Ce service à vie courte cohabiterait aussi avec des politiques restart: always pensées pour des processus permanents. Le healthcheck de l'application, lui, ne dirait toujours rien de l'état du schéma.
Dans l'entrypoint, avant exec du serveur, l'ordre est garanti par construction : base prête, puis migrations, puis FrankenPHP. Le healthcheck du service interroge l'endpoint admin de Caddy (:2019/metrics), qui n'existe qu'une fois FrankenPHP lancé. Un conteneur php healthy a donc forcément un schéma à jour.
C'est ce qui donne sa valeur à depends_on: condition: service_healthy. Un service qui attend l'application, un worker Messenger par exemple, ne démarre qu'une fois le schéma prêt, sans mécanisme d'attente propre. Le signal de santé porte une information de plus qu'avant : « le serveur répond » devient « le serveur répond sur le bon schéma ».
Le prix est un démarrage plus long quand il y a des migrations. compose.prod.yaml porte le délai de grâce du healthcheck à 5 minutes pour qu'une migration longue ne soit pas prise pour une panne. Un démarrage sans migration n'est pas ralenti : le premier succès de la sonde suffit.
Pourquoi un seul migrateur¶
La même image sert plusieurs usages : le serveur web, le worker Messenger, les commandes ponctuelles lancées par docker compose run ou exec. Toutes passent par le même entrypoint. Si chacune migrait, deux processus pourraient appliquer les mêmes migrations en parallèle au démarrage de la pile. Une commande de maintenance anodine modifierait aussi le schéma à l'insu de son auteur.
L'entrypoint ne migre donc que pour frankenphp run, la commande du serveur applicatif. Le worker et les bin/console ponctuels ne touchent jamais au schéma, même avec RUN_MIGRATIONS=1. Il y a un seul migrateur, et c'est le service dont la santé conditionne les autres, ce qui rend l'ordre du point précédent vérifiable.
Pourquoi attendre plutôt que sortir¶
La réaction naturelle d'un script de démarrage à une erreur est de sortir en code non nul. En production, le service php porte restart: always : Docker le relancerait aussitôt, la migration échouerait de nouveau, et ainsi de suite. On obtiendrait une boucle de redémarrage qui noie le diagnostic utile dans des logs répétés. À chaque tour, elle rejouerait aussi une opération sur la base qui vient d'échouer.
L'entrypoint fait donc l'inverse : il écrit un diagnostic lisible, préfixé [kirexo], puis reste en vie sans lancer le serveur. Le healthcheck échoue, le service passe unhealthy, et rien ne redémarre puisque le processus ne meurt pas. Le conteneur reste disponible pour docker exec : on peut y lire l'état du schéma et relancer la migration une fois la cause corrigée. docker stop reste honoré immédiatement.
La même logique vaut pour une valeur de RUN_MIGRATIONS qui n'est ni 0 ni 1. Interpréter true ou yes comme un « oui » ou un « non » serait un pari : un mauvais pari laisserait tourner une production sur un schéma périmé sans le dire. Le refus rend l'erreur visible au premier démarrage.
Une base injoignable reste traitée à part. L'attente initiale sort en erreur après ses essais et laisse la politique de redémarrage retenter. Il s'agit alors d'une panne probablement transitoire, qu'une relance peut résoudre. Une migration cassée ne se résout pas en la relançant.
Les migrations sont appliquées en une seule transaction (--all-or-nothing), ce que PostgreSQL permet puisque son DDL est transactionnel, CREATE EXTENSION compris. Un échec laisse le schéma dans son état antérieur, pas à mi-chemin.
Pourquoi 0 en développement¶
En développement, le schéma évolue au fil du travail : on écrit une migration, on la corrige, on recharge des fixtures. Une migration appliquée à chaque démarrage de la stack exécuterait sans prévenir une migration en cours d'écriture. Le geste reste donc manuel (castor doctrine:migrate) et le défaut de compose.yaml vaut 0.
La stack de développement ne lance d'ailleurs pas frankenphp run directement : compose.override.yaml confie le démarrage de FrankenPHP et du worker à un superviseur. La manette y est sans effet, ce qui évite qu'un RUN_MIGRATIONS=1 exporté par erreur sur un poste ne change ce comportement.
La valeur 1 de la production n'est pas écrite dans .env, mais portée par compose.prod.yaml sous forme de défaut (${RUN_MIGRATIONS:-1}). Docker Compose lit .env pour l'interpolation : une valeur posée dans ce fichier, même 0 pour le développement, désactiverait silencieusement les migrations automatiques de toute production déployée depuis le dépôt cloné.
Ce que ce choix ne couvre pas¶
Migrer automatiquement rend les mises à jour plus sûres à appliquer, pas réversibles. Revenir à une image antérieure ne défait pas les migrations déjà jouées. La sauvegarde de la base avant chaque mise à jour reste le seul moyen de retour arrière sur le schéma. Le guide de déploiement l'intègre à la procédure.