Jouer le test d'installation du bundle en local¶
Vous êtes mainteneur·se de Kirexo et vous voulez vérifier depuis votre poste que le bundle install/ s'installe et fonctionne comme chez un tiers, comprendre un échec du job CI docker:test-install, ou relever l'empreinte de la stack pour install/README.md.
Ce guide suit le fil d'une exécution. La liste complète des étapes, des variables et des codes de sortie est dans castor docker:test-install.
Prérequis¶
- Un terminal hôte, à la racine du dépôt. Dans le conteneur de dev, la cible refuse de tourner : le socket Docker n'y est pas monté.
dockeret le plugindocker composev2, pluscastor.- Les ports
18080et18443libres sur127.0.0.1. Sinon, choisissez-en d'autres avecINSTALL_E2E_HTTP_PORTetINSTALL_E2E_HTTPS_PORT. - Un accès à Docker Hub si les images PostgreSQL, Redis, RabbitMQ ou Mailpit ne sont pas encore présentes sur le poste.
Lancer le test¶
La cible construit l'image de production (kirexo-prod:check-local), rend le bundle avec la version sentinelle 0.0.0, tague l'image sous le nom que cite le bundle, puis joue le bundle dans un projet Compose dédié, kirexo-install-e2e. Votre stack de dev et celles de vos worktrees ne sont pas touchées.
Si l'image est déjà construite, par exemple juste après le garde-fou de fichiers, évitez un second build :
Lire le verdict¶
Chaque étape s'annonce par une ligne == S<n> <titre>, suivie d'une ligne par contrôle :
✓: contrôle conforme ;✗: contrôle en échec — le test s'arrête là ;–: contrôle non applicable, annoncé.
En local, deux lignes – sont normales à l'étape S4, puisque l'image n'est ni tirée du registry ni comparée à un digest de pipeline :
== S4 Pull anonyme
– pull non demandé : image locale (contrôle non applicable en local)
– digest de build non fourni : contrôle non applicable en local
Une ligne – peut aussi apparaître en S12 (plugin web déjà actif) : l'activation n'est faite que si elle est nécessaire.
Une exécution conforme se termine ainsi, puis la cible sort en 0 :
suivi de Bundle d'installation conforme. Empreinte : var/install-e2e/footprint.md.
En cas d'échec¶
La dernière ligne ✗ nomme le contrôle fautif. Si la stack avait démarré, elle est suivie d'un bloc == Diagnostic (projet kirexo-install-e2e) : docker compose ps -a, le stderr des commandes en échec, puis les 300 dernières lignes de logs de chaque service, worker et Mailpit compris. La stack est ensuite démontée.
Premier ✗, ou sortie en 2 |
Où chercher |
|---|---|
S1, KIREXO_VERSION du .env.example publié = … |
Le rendu du bundle : KIREXO_VERSION de install/.env.example et infra/release/publish-bundle.sh. Aucune stack n'a démarré. |
Sortie en 2 à l'étape S2 |
Une variable refusée par docker compose config : le message nomme la variable, jamais sa valeur. |
Sortie en 2 à l'étape S5 |
php resté non sain (migration en échec, secret refusé) : logs php du diagnostic. |
S8a, hôte du lien ≠ app.kirexo.test |
Le lien de réinitialisation ne vient pas de DEFAULT_URI. |
S14, article absent de blog.exemple.test |
Le transport plugin_web : logs worker du diagnostic. |
S15, N instance(s) du worker en cours d'exécution, 2 instances attendues |
KIREXO_WORKER_REPLICAS ou INSTALL_E2E_WORKER_REPLICAS. |
Les fichiers de l'exécution restent dans var/install-e2e/ après le démontage : results.txt (lignes de contrôle), logs/stderr.log, logs/compose.log. C'est ce même dossier, sans son .env, que le job CI publie en artifact.
Déboguer avec --keep¶
Pour inspecter la stack au lieu de la voir disparaître, relancez avec --keep :
La stack est conservée, succès comme échec, et le script affiche la commande de nettoyage et une commande curl vers le site public. Depuis la racine du dépôt, la même base de commande donne accès à la stack :
docker compose -p kirexo-install-e2e \
-f var/install-e2e/bundle/compose.yaml \
-f infra/image/install-e2e.compose.yaml \
--env-file var/install-e2e/.env \
ps
Remplacez ps par ce dont vous avez besoin, par exemple :
logs php worker— journaux de l'application et du worker ;exec -T php bin/console app:install:check— le diagnostic d'installation ;exec -T redis redis-cli ZRANGE kirexo_scheduler_default 0 -1— les membres du verrou du planificateur.
Pour voir le site public par les ports publiés, avec la commande curl affichée en fin de test (ports par défaut) :
C'est aussi le seul moyen de constater que les ports publiés répondent : le test, lui, interroge l'application depuis l'intérieur du conteneur php.
var/install-e2e/.env contient les secrets du run
Ils sont jetables, mais ne collez jamais ce fichier dans un ticket ou une discussion. Le script ne l'affiche jamais, et le job CI l'exclut de son artifact.
Nettoyer¶
Après un --keep, jouez la commande de nettoyage affichée par le script, c'est-à-dire :
docker compose -p kirexo-install-e2e \
-f var/install-e2e/bundle/compose.yaml \
-f infra/image/install-e2e.compose.yaml \
--env-file var/install-e2e/.env \
down -v --remove-orphans
Vérifiez que rien ne reste :
Ni kirexo-install-e2e ni kirexo-install-e2e_edge ne doivent apparaître.
Le démontage ne supprime aucune image. Deux tags restent sur le poste : kirexo-prod:check-local, réutilisable par les autres cibles docker:*-prod-image, et registry.gitlab.com/shaurifr/kirexo/kirexo-prod:0.0.0, qui ne sert qu'à ce test. Pour libérer l'espace :
Les dossiers var/install-e2e/ et var/install-e2e-bundle/ sont recréés à chaque exécution : inutile de les supprimer.
Vérifier que le test sait échouer¶
Un test qui ne rougit jamais ne prouve rien. Pour constater qu'il détecte un défaut, demandez un seul worker :
Attendu : ✗ 1 instance(s) du worker en cours d'exécution, 2 instances attendues à l'étape S15, le bloc de diagnostic, le démontage, puis une sortie en 1.
Reporter l'empreinte dans install/README.md¶
L'étape S16 écrit var/install-e2e/footprint.md : une phrase de méthode (délai de stabilisation, nombre de workers, architecture, version), le tableau de mémoire par conteneur avec son total, la taille de l'image et l'espace disque initial des volumes. Le fichier est prêt à coller.
- Prenez la mesure de référence : celle du job CI
docker:test-installd'une pipeline de tag, qui tourne en amd64. Dans GitLab, ouvrez le job, puis Browse dans le panneau des artifacts, et téléchargezvar/install-e2e/footprint.md. Tant qu'aucune version n'a été publiée, une mesure locale sur un poste amd64 en tient lieu : elle porte alors la version0.0.0, qui doit rester dite comme telle. -
Dans
install/README.md, remplacez uniquement le contenu compris entre les deux balises, sans toucher aux balises ni au reste du fichier : -
Ajoutez sous le tableau une recommandation arrondie au-dessus de la mesure, par exemple « 2 Gio de RAM conseillés » pour un total mesuré de 900 Mio.
- Citez la version mesurée, jamais un numéro de ticket, de lot ou d'étape : ce fichier est publié tel quel en asset de release.
Voir aussi¶
castor docker:test-install— étapes S0 à S17, variablesINSTALL_E2E_*, stack jouée, codes de sortie et limites.- Job
docker:test-install— le même test dans la pipeline de tag, qui bloque la publication du bundle. - Bundle d'installation
install/— services, volumes et variables du bundle testé. - Créer un tag de release — déclencher la pipeline de tag qui joue ce test.