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 :
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:checkutilise directement le binairenodede l'image, sans conteneur jetable ni socket Docker ;- le user
appa 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¶
- Worktrees et environnement de développement — la stack qui exécute cette image.
- Référence du Dockerfile multi-stage — stages, paquets par stage, ordre des layers.
- Garder mon image de dev à jour — la recette.
- Pourquoi une image Alpine multi-stage — le raisonnement derrière cette structure.