Aller au contenu

Image de développement kirexo-dev

Inventaire factuel de l'image de développement Kirexo : ce qu'elle embarque, comment ses versions sont figées, et comment la mettre à jour. Pour la stack qui l'exécute (réseaux, services, URLs, variables), voir Worktrees et environnement de développement. Pour l'inventaire exhaustif des paquets par stage, voir la Référence du Dockerfile multi-stage.

Chemin de fichier contraint

castor image:upgrade-tools écrit dans cette page : le chemin docs/reference/image-dev.md est codé en dur dans castor/image.php, et les motifs de substitution dans castor/src/Image/ToolsUpgrader.php. Déplacer la page ou reformater les tableaux de versions ci-dessous rend la synchronisation automatique inopérante — la cible émet alors un warning « Aucune correspondance dans la doc » et seul le Dockerfile est mis à jour.

Deux images empilées

Image Origine Rôle
registry.gitlab.com/shaurifr/kirexo/kirexo-dev:php8.5-alpine Stage frankenphp_dev du Dockerfile, construite et publiée par le job CI docker:build-dev Artefact versionné qui porte tout l'outillage (Chromium, Node, Claude Code, glab, Castor…). C'est aussi l'image dans laquelle tournent les jobs de test de la CI.
kirexo-dev-local:<tag> dockerfile_inline du service php (compose.override.yaml), FROM l'image ci-dessus Surcouche locale d'une seule ligne : réaligne l'UID/GID du user app sur l'hôte. Buildée en quelques secondes. <tag> vaut KIREXO_IMAGE_TAG, c'est-à-dire l'identifiant du worktree (latest dans le dépôt principal).

Conséquence : modifier le stage frankenphp_dev du Dockerfile ne se propage pas au poste de développement tant que la CI n'a pas republié kirexo-dev. Le Dockerfile reste la spécification ; kirexo-dev est son artefact.

La CI republie kirexo-dev automatiquement sur main, dès le merge d'un changement des stages frankenphp_base ou frankenphp_dev, une fois les stages quality et test de la pipeline push au vert. Elle la republie aussi à chaque tag de release. Les fichiers qui déclenchent la reconstruction sont listés dans Chaînage docker:build-base → dev / prod.

L'option pull: true du bloc build: force le docker build local à re-tirer la base si une version plus récente existe sur le registry.

Estampille de build

Le dernier layer du stage frankenphp_dev écrit le SHA de commit d'où sort l'image :

cat /etc/kirexo-dev.ref

Valeur unknown = build local nu, sans --build-arg BUILD_REF. Le fichier est écrit en toute fin de stage pour n'invalider aucun layer lourd quand le SHA change.

Outillage ajouté au stage frankenphp_dev

En plus de ce que fournit frankenphp_base (git, jq, curl, file, Castor) :

Paquet apk Rôle
bash Requis par la directive SHELL du stage et par les scripts infra/ (mapfile, [[ =~ ]], tableaux).
ca-certificates Validation TLS des connexions sortantes — le proxy sortant ne terminant pas le TLS, la chaîne reste vérifiée de bout en bout par le client.
iproute2 Diagnostic réseau (ip route, ip addr).
musl-utils Fournit getent, absent de busybox/musl — résolution intra-stack et création d'utilisateur.
coreutils date -Iseconds, mktemp, seq : busybox ne garantit pas ces options.
procps pgrep -x / pkill -x (busybox n'a pas -x).
findutils xargs -L.
shadow useradd / usermod (busybox n'a qu'adduser).
libcap setcap cap_net_bind_service=+ep sur le binaire frankenphp, en fin de stage.
shellcheck Linter des scripts shell — cible castor lint:shell.
bats Tests des fonctions pures des libs Bash — cible castor test:bash.
ffmpeg Capture vidéo des démos E2E.
bash-completion Framework requis par les scripts de complétion Symfony Console. Cf. Autocomplétion Castor.
chromium, chromium-chromedriver Tests E2E Panther. Épinglés sur la même branche Alpine que l'image de base (ARG CHROMIUM_ALPINE_BRANCH, CHROMIUM_VERSION) et validés par un smoke-test --headless=new qui fait échouer le docker build si le navigateur ne démarre pas.
nodejs, npm Cf. Node et Claude Code.

L'extension PHP xdebug est installée via install-php-extensions, mais reste inerte : xdebug.mode = off dans frankenphp/conf.d/20-app.dev.ini.

Ce qui a été retiré de l'image

sudo, iptables, ip6tables, ipset et dnsmasq ne sont plus installés. Ils servaient au pare-feu qui vivait dans le conteneur ; ce dispositif a été démantelé au profit d'un réseau sans route et d'un proxy d'allowlist extérieur. Il n'existe donc plus aucun chemin d'élévation à root dans le conteneur — c'est la matérialisation de l'invariant de confinement C6, vérifié par son effet. Cf. Pourquoi la sortie réseau passe par un proxy à allowlist.

Le seul privilège fin conservé est le setcap 'cap_net_bind_service=+ep' posé sur frankenphp, qui n'a aucun rapport avec l'administration réseau.

Versions figées

Les quatre outils ci-dessous sont épinglés par des ARG du Dockerfile et synchronisés par castor image:upgrade-tools.

Binaires statiques

Binaire Version Provenance Vérification d'intégrité
castor v1.8.1 (ARG CASTOR_VERSION) https://github.com/jolicode/castor/releases/download/${CASTOR_VERSION}/castor.linux-amd64.phar SHA-256 via ARG CASTOR_SHA256, vérifié par sha256sum -c avant install.
glab 1.119.0 (ARG GLAB_VERSION) https://gitlab.com/gitlab-org/cli/-/releases/v${GLAB_VERSION}/downloads/glab_${GLAB_VERSION}_linux_amd64.tar.gz SHA-256 via ARG GLAB_SHA256, vérifié sur l'archive avant tar -xzf.

Le SHA-256 est figé au même titre que la version : il protège contre un mirror compromis ou une release republiée sous le même tag. castor image:upgrade-tools bumpe la version et le hash ensemble — sans quoi le sha256sum -c du Dockerfile rejetterait le binaire fraîchement bumpé et le build casserait.

Node et Claude Code

Composant Version Installation
Node + npm + npx NODE_VERSION=24.18.1-r0 (ARG Dockerfile) apk add --repository .../${NODE_ALPINE_BRANCH}/community "nodejs=${NODE_VERSION}" npm, branche release figée NODE_ALPINE_BRANCH=v3.24. Intégrité garantie par l'index apk signé — aucun SHA-256 manuel.
Claude Code CLAUDE_CODE_VERSION=2.1.282 (ARG Dockerfile) npm install -g @anthropic-ai/claude-code@${CLAUDE_CODE_VERSION}. Pas de pin SHA-256 : npm valide nativement l'integrity SRI (sha512) publiée par le registre.

Node et Claude Code sont installés directement dans le stage frankenphp_dev, jamais par un mécanisme de features d'un outil tiers : les pipelines de build de features génèrent un Dockerfile temporaire qui ne contient pas les stages du nôtre, et le build échoue sur target stage "frankenphp_dev" could not be found.

Conséquences pratiques :

  • castor ts:check utilise directement le binaire node de l'image, sans conteneur jetable ni socket Docker ;
  • le user app a un home en /home/app — nécessaire à Node, npm et Claude Code, qui y stockent configuration, cache et historique.

Image de base FrankenPHP

Le Dockerfile fige le tag de l'image amont par une instruction FROM dunglas/frankenphp:1.12.7-php8.5-alpine — pas un ARG, donc hors du mécanisme de bump automatique. La version de FrankenPHP est épinglée au patch : la 1.13 impose une migration de Mercure (cf. Référence du Dockerfile — Image de base).

Les montées de version de cette image sont portées par Renovate (cf. Configurer Renovate) : correctifs groupés et automergés, mineures et majeures en MR isolée sans automerge.

Aspect Comportement
Détection fetch_frankenphp_drift() (castor/image.php) interroge https://hub.docker.com/v2/repositories/dunglas/frankenphp/tags/?page_size=100&name=php8. puis appelle ToolsUpgrader::selectFrankenphpCandidate().
Critère Le tag courant et les candidats doivent suivre le format flottant <franken-major>-php<php-major>.<php-minor>, suffixe -alpine optionnel (regex ^(\d+)-php(\d+)\.(\d+)(?:-alpine)?$). Tuple (franken-major, php-major, php-minor) strictement supérieur au courant ; une « régression PHP » (bump franken-major qui dégraderait la version PHP) est écartée.
Tag épinglé (état actuel) 1.12.7-php8.5-alpine ne matche pas ce format : selectFrankenphpCandidate() retourne null, aucun drift n'est signalé.
image:upgrade-tools Avec le tag épinglé : muet sur FrankenPHP. Avec un tag flottant : warning non bloquant, la modification de la ligne FROM restant manuelle.
image:check-tools Avec le tag épinglé : FrankenPHP ne compte pas dans l'exit 2.
Docker Hub indisponible fetch_frankenphp_drift() retourne null silencieusement : c'est un check d'information, pas un test de santé.

Surveiller l'image de base couvre indirectement les paquets apk et install-php-extensions livrés par elle.

Autocomplétion Castor

L'autocomplétion de la commande castor est activée system-wide dans le stage frankenphp_dev, via /etc/profile.d/castor-completion.sh. Tout shell de login bash ouvert dans le conteneur en bénéficie — aucune action du développeur.

Aspect Valeur
Mécanisme Sourcing de /usr/share/bash-completion/bash_completion (paquet bash-completion) puis eval "$(castor completion bash)", dans cet ordre — le script Symfony Console s'appuie sur _get_comp_words_by_ref fourni par le framework.
Fichier /etc/profile.d/castor-completion.sh. Alpine ne garantit pas de /etc/bash.bashrc : profile.d est le point d'entrée portable.
Portée System-wide, indépendante du home de app, survit aux recréations de conteneur.
Shell couvert bash uniquement (shell de connexion du user app).

castor completion émet un script de complétion statique, indépendant du CWD et de la présence d'un castor.php : l'eval à chaque session est sans effet de bord.

Sur la machine hôte, l'autocomplétion n'est pas activée automatiquement — on ne modifie pas le shell du développeur sans son consentement. Pour l'activer : Activer l'autocomplétion Castor sur l'hôte.

Mise à jour des versions

Trois cibles, toutes documentées dans les Commandes Castor.

Cible Effet Contexte
castor image:check-tools Alias lisible de image:upgrade-tools --check : affiche le tableau ARG / Actuel / Dernier / Δ et sort en exit 2 si une version d'outil ou l'image de base a bougé. Ne modifie rien. Hôte
castor image:upgrade-tools Résout les dernières versions (GitHub pour Castor, GitLab pour glab, npm pour Claude Code, APKINDEX Alpine pour Node), recalcule les SHA-256 concernés, puis réécrit les ARG du Dockerfile et les tableaux de versions de cette page. Interactif par défaut, --apply pour appliquer directement. Hôte
castor image:refresh Agit sur les deux images : docker pull de la base publiée, retrait d'une éventuelle surcouche jb-<hash>-uid héritée de l'ancien mode d'ouverture de l'IDE, puis reconstruction de la surcouche locale par-dessus la base à jour (up -d --build --wait php). La cible va au bout : aucun geste manuel dans l'IDE. Déroulé étape par étape : castor image:refresh. Hôte

L'image de base n'est jamais retirée : DevImage::resolveImageToRemove() (castor/src/Image/DevImage.php) rend null dès que l'image résolue est celle qu'on vient de tirer.

image:upgrade-tools et image:refresh sont hôte-only

Les deux appellent assert_outside_container(). Pour image:upgrade-tools, la raison est concrète : deux des hôtes qu'elle interroge sont absents de l'allowlist du proxy sortant — hub.docker.com, pour le drift de l'image de base, et dl-cdn.alpinelinux.org, dont l'APKINDEX donne la version de Node. Depuis le conteneur, curl échouerait et le message d'erreur masquerait la vraie cause.

Le téléchargement des binaires pour le calcul du SHA-256 n'est plus, lui, un motif : GitHub redirige ses assets de release vers release-assets.githubusercontent.com, ouvert dans la baseline pour le binaire Tailwind. C'est le seul hôte d'assets autorisé — GitHub en a servi d'autres selon les périodes, et aucun n'est ajouté sans avoir été mesuré nécessaire.

Après un bump :

# HÔTE
castor image:upgrade-tools      # met à jour Dockerfile + cette page
castor docker:build             # reconstruit l'image locale
git add Dockerfile docs/reference/image-dev.md

Un ARG de version documenté ici qui ne matcherait plus le motif attendu produit un warning Aucune correspondance dans la doc pour <ARG> : c'est le signal d'un drift de format à corriger dans cette page, pas d'un échec du bump.

Voir aussi