Garder mon image de dev à jour¶
Vous êtes développeur·se sur Kirexo et votre image de développement a dérivé : le Dockerfile a bougé — nouvel outil, bump de version — mais votre conteneur tourne encore sur l'ancienne image, sans le moindre message. Cette recette montre comment repérer la dérive, la corriger, et bumper les versions d'outils figées dans le Dockerfile.
Prérequis¶
- Un terminal côté hôte à la racine du dépôt principal ou du worktree concerné : toutes les cibles de cette page sont hôte-only.
- La stack de dev démarrée (
castor wt:up <ticket>oucastor docker:up).
L'inventaire de ce que contient l'image et le détail du mécanisme de versions sont dans Image de développement kirexo-dev.
Le problème : deux images, deux façons de dériver¶
Deux causes s'empilent, et aucune des deux ne produit d'erreur visible.
- Amont — l'image publiée
kirexo-dev:php8.5-alpinen'est reconstruite que par le job CIdocker:build-dev. Il tourne automatiquement surmaindès le merge d'un changement des stagesfrankenphp_baseoufrankenphp_dev, une fois la pipeline push au vert, et à chaque tag de release. Entre le merge et la fin de ce job, un commit qui touche le stagefrankenphp_devduDockerfilene s'est pas encore propagé dans le registry. LeDockerfileest la spécification,kirexo-devest son artefact : les deux peuvent diverger. - Aval — votre stack n'utilise pas directement l'image publiée, mais une surcouche locale
kirexo-dev-local:<tag>d'une seule ligne (réalignement de l'UID/GID). Tant que cette surcouche n'est pas reconstruite depuis une base fraîche, elle continue de porter l'ancien contenu.
Le signal : l'alerte du dashboard de session¶
Quand l'image en cours est en retard sur le Dockerfile, le dashboard de session Claude affiche :
Ou, si l'image ne porte aucune estampille (build antérieur au suivi de fraîcheur) :
⚠ Image dev sans estampille de build (antérieure au suivi de fraîcheur) ⇒ périmée
→ castor image:refresh
@a1b2c3dest le SHA de build, lu dans/etc/kirexo-dev.ref.- La comparaison est faite sur l'état local du dépôt (
git log -1 -- Dockerfile), sansgit fetch. - Silence total si l'image est à jour, si l'estampille vaut
unknown(build local assumé) ou si le SHA est inconnu du dépôt : la détection se dégrade en silence plutôt que d'émettre un faux positif.
La logique vit dans infra/image/image-freshness.lib.sh, appelée par .claude/hooks/session-dashboard.sh. C'est de la détection seule : aucun rebuild automatique.
Cas 1 — le Dockerfile du dépôt a changé, l'image publiée est à jour¶
C'est le cas courant après un git pull. Il suffit de reconstruire la surcouche locale, ce que castor wt:up fait tout seul :
wt:up compare la date de l'image kirexo-dev-local:ticket-185 aux mtime du Dockerfile et de compose.override.yaml. Si l'un des deux est plus récent, il rebuilde et le dit dans son rapport de réconciliation :
Une ligne = image signifie qu'il n'y avait rien à faire. --no-build saute cette étape et signale la dérive sans la corriger (! image … --no-build demandé).
Dans le dépôt principal, l'équivalent est :
Cas 2 — l'image publiée elle-même a bougé¶
Le rebuild local repart d'une base tirée du registry. Si c'est cette base qui a changé (la CI vient de republier kirexo-dev), une seule commande suffit :
La cible va au bout : elle enchaîne cinq étapes numérotées 0/4 à 4/4 dans sa sortie — préalable d'infrastructure, docker pull de la base, arrêt du service, nettoyage d'héritage, puis up -d --build --wait php — et rend la main sur un service déjà reconstruit et sain. Le détail de chaque étape est en référence.
L'étape 4/4 empile les fichiers Compose du contexte d'où vous la lancez : depuis un worktree, compose.worktree.yaml en fait partie, et les variables de .env.worktree sont publiées dans l'environnement du process. Le conteneur revient donc avec le bind du git common dir et son identité de worktree — la cible est autonome des deux côtés, dépôt principal comme worktree.
Deux lignes de sa sortie méritent une lecture :
- « aucune surcouche : le poste est déjà sur le mode natif » à l'étape
3/4— c'est le cas nominal, pas un avertissement. Cette étape ne sert qu'à désencombrer un poste venant de l'ancien mode d'ouverture de l'IDE, où PhpStorm construisait sa propre imagejb-<hash>-uidde plusieurs gigaoctets. - un échec à l'étape
4/4surnetwork kirexo-egress declared as external— le préalable0/4n'a pas abouti. Cf. Diagnostiquer un blocage réseau sortant.
Il n'y a rien à faire dans PhpStorm : depuis que l'IDE ouvre le code nativement, il ne construit plus d'image et se reconnecte seul au conteneur au prochain run (cf. Brancher PhpStorm sur un worktree).
Hôte uniquement
castor image:refresh appelle assert_outside_container() : lancée depuis l'intérieur, elle échoue en erreur. On ne retire pas l'image qui héberge le conteneur courant.
Cas 3 — bumper les versions d'outils figées dans le Dockerfile¶
Castor, glab, Claude Code et Node sont épinglés par des ARG. Pour savoir si une version plus récente existe, sans rien modifier :
La cible affiche un tableau ARG | Actuel | Dernier | Δ et sort en exit 2 si au moins un outil — ou l'image de base FrankenPHP — a bougé. Elle est utilisable en CI pour notifier une dérive.
Pour appliquer :
# HÔTE
castor image:upgrade-tools # interactif : affiche le diff, demande confirmation
castor image:upgrade-tools --apply # applique directement
Elle réécrit les ARG du Dockerfile — version et SHA-256 ensemble pour Castor et glab, sans quoi le sha256sum -c du build rejetterait le binaire fraîchement bumpé — puis met à jour les tableaux de versions de docs/reference/image-dev.md.
Reconstruisez ensuite, puis commitez les deux fichiers :
Hôte uniquement, et pour une raison précise
La cible interroge deux hôtes absents de l'allowlist du proxy sortant : hub.docker.com pour le drift de l'image de base, et dl-cdn.alpinelinux.org pour la version de Node (APKINDEX Alpine). Depuis le conteneur, curl échouerait et le message masquerait la vraie cause.
L'image de base FrankenPHP se bumpe à la main
Elle est figée par une instruction FROM, pas par un ARG : image:upgrade-tools la surveille et affiche un warning avec le tag candidat, mais ne modifie jamais la ligne. Le bump implique de lire le changelog amont — c'est une décision, pas une substitution.
Vérifier¶
# Dans le conteneur
cat /etc/kirexo-dev.ref # SHA de build, postérieur au dernier commit touchant le Dockerfile
castor doctor # les binaires embarqués (castor, glab, node, npm, claude) sont présents
Et au tour suivant, le dashboard de session Claude n'affiche plus l'alerte de retard.
Un binaire manquant dans castor doctor remonte avec la remédiation castor image:refresh : il vient de l'image, rien ne se répare depuis l'intérieur du conteneur.
Voir aussi¶
- Image de développement
kirexo-dev— outillage, versions figées, procédure de mise à jour. - Référence du Dockerfile multi-stage — stages et paquets.
- Worktrees et environnement de développement — la stack qui exécute l'image.
- Pourquoi une image Alpine multi-stage — le raisonnement derrière cette structure d'images.