"post-install-cmd": [
    "bin/console cache:clear --env=prod",
    "bin/console doctrine:migrations:migrate --no-interaction"
]

post-install-cmd s’exécute pendant composer install, qui dans le Dockerfile de production tourne au moment du build de l’image. Il n’y a pas de base de données disponible pendant un build Docker. La commande de migration échouait silencieusement, se connectait à rien, ou était ignorée par Doctrine faute de schéma à comparer. Dans tous les cas, elle ne migrait rien.

C’est une violation nette du Facteur XII : les processus d’administration — migrations, scripts ponctuels, commandes console — doivent s’exécuter dans le même environnement que l’application, contre les vraies données de production. Les faire tourner au build inverse la relation. L’image ne devrait pas savoir qu’il y a une base de données. La base devrait être là quand l’image en a besoin.

Le déplacement vers l’entrypoint

La commande de migration a quitté composer.json pour docker-entrypoint.sh. Le changement semble petit dans un diff. Les implications ne le sont pas.

L’entrypoint s’exécute quand le container démarre, pas quand l’image est construite. La base de données est accessible. L’entrypoint l’attend — jusqu’à 60 secondes, une tentative par seconde — avant de faire quoi que ce soit :

ATTEMPTS_LEFT_TO_REACH_DATABASE=60
until [ $ATTEMPTS_LEFT_TO_REACH_DATABASE -eq 0 ] || \
  DATABASE_ERROR=$(php bin/console dbal:run-sql -q "SELECT 1" 2>&1); do
    sleep 1
    ATTEMPTS_LEFT_TO_REACH_DATABASE=$((ATTEMPTS_LEFT_TO_REACH_DATABASE - 1))
done

if [ $ATTEMPTS_LEFT_TO_REACH_DATABASE -eq 0 ]; then
    echo "$DATABASE_ERROR"
    exit 1
fi

Si la base ne répond pas dans les 60 secondes, le container sort en erreur et Kubernetes le redémarre. Une fois la base prête, la migration tourne :

if [ "$( find ./migrations -iname '*.php' -print -quit )" ]; then
    php bin/console doctrine:migrations:migrate --no-interaction --all-or-nothing
fi

Deux changements par rapport à la commande d’origine : --all-or-nothing garantit que si une migration dans un batch échoue, le batch entier est annulé. Et le guard find passe la commande si aucun fichier de migration n’existe — utile pour les services qui n’utilisent pas les migrations Doctrine.

C’est franchement mieux. La base est là. La migration tourne dans le vrai environnement. Le flag --all-or-nothing apporte une atomicité que la version au build n’avait jamais eue.

Ce que ça ne résout pas

Deux pods qui redéploient simultanément exécutent tous les deux l’entrypoint. Tous les deux atteignent la base. Tous les deux trouvent des migrations en attente. Tous les deux appellent doctrine:migrations:migrate.

Doctrine a un mécanisme de verrouillage : une table doctrine_migration_versions qui enregistre quelles migrations ont tourné, et la commande la consulte avant d’appliquer quoi que ce soit. Dans les conditions normales c’est suffisant : le deuxième pod trouve la table à jour et sort proprement. Les cas de défaillance réels sont plus précis : une migration assez longue pour dépasser le timeout du verrou de base de données, ce qui laisse un deuxième runner démarrer la même migration avant que le premier ait terminé ; ou un pod qui se vautre à mi-migration avant d’avoir enregistré la version dans la table, laissant le schéma dans un état appliqué-mais-non-enregistré que le pod suivant va tenter d’appliquer à nouveau.

La position de l’équipe est explicite : un downtime léger au déploiement est acceptable. Les versions d’application ne sont pas nécessairement compatibles avec des versions de schéma plus anciennes, donc faire tourner N et N+1 simultanément contre la même base ne serait de toute façon pas sûr. La stratégie de déploiement est Recreate : tous les anciens pods sont terminés avant que les nouveaux ne démarrent. La migration tourne au premier démarrage, sans chevauchement entre les versions. Ça fonctionne.

Mais “ça fonctionne” et “c’est la bonne architecture” sont deux réponses différentes.

Ce que feraient les alternatives

Le Facteur XII dit que les processus d’administration doivent tourner dans des “processus ponctuels”. Un processus qui tourne une fois, dans un but précis, contre l’environnement de production. L’entrypoint n’est pas ponctuel — il tourne à chaque démarrage de container, y compris les redémarrages, les événements de scaling, et les déplacements de pods par Kubernetes.

Trois alternatives existent, chacune avec une réponse différente à la question de la propriété :

Un init container Kubernetes tourne avant le container principal, dans le même pod. Il peut exécuter la migration, sortir, et laisser le container principal démarrer seulement après son succès. La migration est isolée du runtime applicatif. Le problème : l’init container est une image supplémentaire à construire et maintenir, et il tourne à chaque démarrage de pod — une plateforme de 14 services démarrant simultanément a toujours une race potentielle.

Un Kubernetes Job tourne une fois, à la demande ou déclenché par le pipeline de déploiement. Il peut être configuré pour s’exécuter avant la mise à jour des pods — séquentiel, isolé, avec un signal clair de succès ou d’échec. La race condition disparaît. La complexité se déplace vers le processus de déploiement : le Job doit se terminer avant que le rollout du Deployment commence, et le pipeline CI doit coordonner les deux.

Un hook Helm est le même concept exprimé de façon déclarative dans le chart Helm. Un hook pre-upgrade exécute la migration avant la mise à jour des pods applicatifs. C’est la réponse la plus idiomatique pour Kubernetes. Ça signifie aussi que le chart Helm est désormais responsable de l’exécution des migrations — une décision qui appartient à qui possède le chart.

Cette dernière phrase explique pourquoi l’entrypoint n’a pas changé. Déplacer les migrations hors de l’application signifie décider que l’infrastructure de déploiement — pas l’application elle-même — est responsable du schéma. C’est une question de gouvernance autant que de technique, et les questions de gouvernance prennent plus de temps à résoudre que les changements de code.

La fin honnête

Le bloc de migration dans l’entrypoint, c’est deux lignes. Littéralement : le guard if [ "$( find ./migrations... )" ], et le php bin/console doctrine:migrations:migrate qui suit. Onze autres facteurs ont des résolutions nettes. Le cache est passé sur Redis. Les logs vont vers stdout. Le système de fichiers est un bucket S3. Le CI assemble les images de production depuis le même commit qu’il teste. Les secrets ne voyagent plus dans les layers d’image.

Le Facteur XII a une réponse. Ce n’est juste pas la réponse finale.

Les migrations tournent au démarrage, avec une vraie base de données, avec atomicité, avec une fenêtre de retry bornée. C’est mieux que de tourner au build contre rien. La question de savoir si elles finiront dans un Job ou un hook Helm est une conversation sur qui possède le schéma — une question à laquelle un kubectl apply ne peut pas répondre.

Pendant les quarante secondes suivantes — sur les soixante possibles — ce container était en train de poller la base de données.

Les requêtes qui atterrissaient dessus pendant cette fenêtre récoltaient des erreurs. Pas beaucoup — la fenêtre était courte — mais assez pour apparaître comme du bruit dans le monitoring. Le genre de bruit qu’on classe comme « problème réseau transitoire » et qu’on ne signale nulle part. Le déploiement a réussi. Le pod a fini par devenir prêt. Le mécanisme qui en était la cause était toujours là, attendant le prochain déploiement.

Le script d’entrypoint fait cinq choses avant que FrankenPHP démarre : copier un fichier de version, vérifier le répertoire vendor, attendre jusqu’à soixante secondes la base de données, jouer les migrations en attente, installer les assets et configurer les permissions filesystem. Sous Docker Compose, c’est invisible. Sur Kubernetes, l’écart devient du trafic en erreur.

L’écart entre démarré et prêt

Kubernetes décide d’envoyer du trafic à un pod en surveillant sa readiness probe. Un pod dont la readiness probe passe reçoit des requêtes. Un pod dont la readiness probe échoue est retiré de la rotation du load balancer jusqu’à ce qu’il récupère. C’est le mécanisme qui rend les rolling deploys sûrs : Kubernetes ne bascule pas vers un nouveau pod tant que ce pod n’indique pas qu’il est prêt.

Le compose.yaml définit un healthcheck sur chaque service :

healthcheck:
    test: [ "CMD", "php", "-v" ]
    interval: 30s
    timeout: 10s
    retries: 3
    start_period: 10s

php -v réussit dès que le binaire PHP est présent — ce qui est vrai depuis la première milliseconde de vie du container. Le start_period: 10s donne dix secondes avant que les vérifications commencent. Mais la boucle de polling de l’entrypoint tourne jusqu’à soixante secondes avant que FrankenPHP démarre. À la dixième seconde, le healthcheck passe. L’application attend toujours la base de données.

Le Dockerfile a un meilleur signal :

HEALTHCHECK --start-period=60s CMD curl -f http://localhost:2019/metrics || exit 1

Le port 2019 est le serveur de métriques intégré à Caddy, embarqué directement dans FrankenPHP. L’endpoint est compatible Prometheus et ne répond qu’une fois que la stack HTTP de Caddy est pleinement initialisée et que les workers PHP acceptent des connexions. php -v se termine en cinquante millisecondes quel que soit l’état de l’application — il vérifie le binaire, pas le serveur. :2019/metrics ne répond que quand le serveur sert vraiment. Ce n’est pas non plus un endpoint ajouté exprès pour la probe : chaque service de la plateforme l’a déjà scraped par Prometheus, donc le signal est actif indépendamment de toute configuration de healthcheck.

C’est plus proche. Mais sur Kubernetes, l’instruction HEALTHCHECK du Dockerfile est totalement ignorée. Kubernetes utilise sa propre configuration de probes. Sans définitions de probes explicites dans les manifests Kubernetes, il n’y a aucune vérification de readiness — et un pod est considéré prêt dès que son container démarre.

Ce qui signifie : le pod démarre, l’entrypoint commence à poller, Kubernetes route du trafic, l’application n’est pas encore en état de le traiter. Les requêtes arrivent sur un container qui n’est pas prêt à les gérer.

Trois signaux, trois questions

Kubernetes sépare le cycle de vie d’un container en trois questions distinctes, chacune avec son propre type de probe :

startupProbe — « L’application a-t-elle fini de démarrer ? » Se déclenche à répétition jusqu’à ce qu’elle passe, puis passe la main à la liveness. Empêche la liveness probe de tuer un container qui est légitimement long à initialiser. Pour un container dont l’entrypoint peut prendre soixante secondes, c’est l’outil adapté.

readinessProbe — « L’application est-elle prête à traiter des requêtes ? » Échoue et passe tout au long de la vie du container. Quand elle échoue, le pod est retiré du load balancer. C’est ce qui rend un rolling deploy sûr.

livenessProbe — « L’application est-elle toujours vivante ? » Si elle échoue, Kubernetes redémarre le container. Conçue pour détecter les processus bloqués, pas les démarrages lents.

La boucle de polling de soixante secondes appartient à la patience de la startupProbe, pas au code applicatif :

startupProbe:
    httpGet:
        path: /metrics
        port: 2019
    failureThreshold: 12    # 12 tentatives × 5s = 60s max
    periodSeconds: 5

Une fois la startupProbe passée, une readinessProbe sur le même endpoint prend le relais — indiquant à Kubernetes quand le pod peut recevoir du trafic — et une livenessProbe surveille les processus bloqués. Mais c’est la startupProbe qui absorbe le démarrage lent. La boucle de polling de l’entrypoint devient redondante : son rôle était de maintenir le container en vie pendant que la base de données devenait disponible. Sans elle, l’application tente de se connecter, échoue, et le container quitte — Kubernetes redémarre alors le pod, et la startupProbe maintient son cycle de tentatives jusqu’à ce que la base réponde et que l’application démarre proprement. La responsabilité du retry passe de l’intérieur de l’entrypoint à l’orchestrateur, ce qui est exactement là où elle devrait être.

Le problème des migrations

La boucle de polling est le problème le plus visible, mais les migrations en créent un plus subtil.

Avec un rolling deploy et deux replicas, Kubernetes démarre un nouveau pod pendant que l’ancien sert encore du trafic. Les deux pods jouent le même entrypoint. Les deux atteignent doctrine:migrations:migrate.

La table de migrations de Doctrine trace quelles migrations ont déjà été exécutées, donc une migration complétée ne se jouera pas deux fois. Mais si deux pods démarrent simultanément et voient tous les deux une migration en attente, les deux tentent de la jouer en même temps. Si c’est sûr ou non dépend de la migration : les changements de schéma additifs passent en général bien ; les destructifs moins. Et on ne choisit pas lesquels s’exécutent lors d’un déploiement qui n’a pas prévu de se coordonner. --all-or-nothing enveloppe les migrations dans une transaction et fait un rollback si l’une échoue — c’est une question d’atomicité au sein d’une seule exécution, pas de coordination entre processus.

L’approche plus propre sépare ces deux préoccupations en deux init containers : l’un qui attend la base de données, l’autre qui joue les migrations. Le container principal ne démarre qu’une fois les deux terminés :

initContainers:
    - name: wait-for-db
      image: authentication:latest
      command: ["php", "bin/console", "dbal:run-sql", "-q", "SELECT 1"]
    - name: migrate
      image: authentication:latest
      command: ["php", "bin/console", "doctrine:migrations:migrate", "--no-interaction", "--all-or-nothing"]

Les deux init containers réutilisent la même image que l’application. Ce n’est pas du gaspillage : ils ont besoin du même binaire PHP et du même câblage d’environnement pour atteindre la base de données et trouver les classes de migration. Une image dédiée plus légère réduirait le temps de démarrage, mais nécessiterait de maintenir une installation PHP séparée en synchronisation avec l’image principale.

Même avec des init containers, plusieurs pods démarrant simultanément — déploiement initial, après une défaillance de nœud, ou sous pression d’autoscaling — tenteront chacun de jouer les migrations. Le résoudre proprement — via un hook pre-upgrade Helm, une stratégie maxSurge: 0, ou un Job de migration séparé — est un sujet en soi. Ce qui compte ici, c’est que l’entrypoint est le mauvais endroit pour prendre cette décision : il ne peut pas se coordonner entre pods, et il lie l’exécution des migrations au démarrage de l’application d’une façon difficile à démêler plus tard. La question de quelle alternative convient à cette codebase — et pourquoi l’entrypoint n’a pas encore été remplacé — fait l’objet de l’article suivant dans cette série .

Le Facteur XII de la méthodologie twelve-factor — les processus d’administration tournent dans le même environnement que l’application — est respecté dans les deux cas. La question est de savoir si « même environnement » signifie « même script d’entrypoint » ou « même image, processus séparé ». Sur Kubernetes, le second est plus sûr.

La vraie responsabilité de l’entrypoint

Enlever l’attente de la base de données (maintenant une startupProbe ou un init container), les migrations (maintenant un init container ou un Job), et l’installation des assets (une opération de build-time qui appartient au Dockerfile), et l’entrypoint n’a plus qu’une seule responsabilité : démarrer l’application.

exec docker-php-entrypoint "$@"

Le Facteur IX de la twelve-factor app demande un démarrage rapide et un arrêt propre. Un container dont le démarrage prend soixante secondes parce qu’il attend des dépendances externes n’est pas rapide. Ça signifie des rolling deploys lents, une reprise après crash lente, et un scale-out horizontal qui crée une fenêtre de soixante secondes avant que chaque nouveau pod contribue.

Le démarrage rapide n’est pas juste un confort. C’est ce qui fait fonctionner le reste du modèle cloud. Quand un pod peut démarrer en secondes, l’orchestrateur peut scaler agressivement et récupérer vite. Quand ça prend une minute, on ajoute des marges partout — timeouts de probes plus longs, fenêtres de déploiement plus larges, politiques de scaling plus conservatrices — et le système devient rigide.

La taxe Docker Compose

L’entrypoint accumule ces responsabilités pour une raison. Sous Docker Compose, il n’y a pas de concept d’init container. Pas de startupProbe. Les services déclarent depends_on, mais sans conditions de santé, c’est juste de l’ordre de démarrage — pas de la readiness. L’entrypoint comble le vide.

Ce n’est pas un défaut de conception. C’est une adaptation raisonnable aux contraintes de Docker Compose. Le script fonctionne. Il gère les cas limites (le timeout de la base, les erreurs irrécupérables, le répertoire de migrations absent). Quelqu’un l’a testé.

Le problème, c’est l’hypothèse que le même script fonctionne aussi bien sur Kubernetes. Il tourne. L’application finit par démarrer. Mais il contourne le système de probes qui rend les déploiements Kubernetes fiables, et il place la responsabilité des migrations à un endroit où la coordination entre pods est difficile à raisonner.

Plusieurs des changements de cette série — stockage des médias , secrets dans les images , handlers de logs , dépendances de services , parité d’environnement CI , adaptateurs de cache — étaient des changements au code applicatif ou à la configuration. Celui-ci est différent. Il demande à l’infrastructure de comprendre ce que « prêt » signifie pour cette application, et il demande à l’entrypoint de céder des responsabilités qu’il détient actuellement.

C’est une conversation plus difficile. Mais la startupProbe attend.

stages:
  - build
  - provision
  - phpunit
  - phpmetrics
  - behat
  - deprovision
  - deploy

Avant que la première assertion s’exécute, quinze minutes s’étaient écoulées. Terraform avait cloné un dépôt d’infrastructure, s’était authentifié sur Azure, avait appliqué une configuration de VM. Ansible s’était connecté à la nouvelle VM, avait installé PHP, configuré l’application, câblé une base de données et une instance Redis. Ensuite les tests tournaient. Ensuite Terraform détruisait ce qu’Ansible avait construit.

Pour chaque pipeline. Depuis chaque branche. Pour chaque pull request, de l’ouverture au merge.

Ce que ces quinze minutes ne contenaient pas

Le stage provision mettait en place deux services : PostgreSQL et Redis. Trois services dont l’application dépendait en production étaient absents : RabbitMQ, MinIO et Varnish.

RabbitMQ traitait tout le travail asynchrone — 56 consumers sur 14 microservices. MinIO gérait le stockage de médias. Varnish était devant le cache HTTP. En CI, aucun d’eux n’existait. Les tests qui couvraient les files de messages ou le stockage de fichiers avaient deux options : ignorer ces chemins, ou les laisser non testés jusqu’au staging. Varnish est un cas à part : les tests tapent directement dans l’application et contournent intentionnellement la couche de cache, son absence en CI est donc un choix délibéré plutôt qu’un manque.

C’est le problème que le Facteur X décrit comme l’écart d’environnement. L’écart ici n’était pas une question de configuration — il était structurel. La VM était construite par Ansible depuis un script dans un dépôt séparé. Ce n’était pas une image de container. Elle n’était pas versionnée aux côtés de l’application. Si une branche modifiait la topologie de messages RabbitMQ, il n’y avait aucun moyen de tester cette modification en CI. Le changement de topologie et le code qui en dépendait ne se rencontreraient qu’en staging.

Le script de provisioning Ansible lui-même fait partie du problème :

launch_vm:
  stage: provision
  script:
    - git clone git@gitlab.internal/infra/ci-vm.git
    - cd ci-vm
    - az login --service-principal -u $ARM_CLIENT_ID ...
    - terraform apply -var "prefix=${CI_PIPELINE_ID}-vm" ...
    - sleep 45
    - ansible-playbook behat/test-env.yml ...

Le sleep 45 est là parce qu’Ansible a besoin que la VM finisse de booter avant de pouvoir s’y connecter. Ce n’est pas un oubli — c’est le délai minimum qu’une VM fraîchement provisionnée nécessite avant que SSH fonctionne. C’est inscrit dans le processus.

Ce qui l’a remplacé

Le nouveau pipeline n’a pas de stage provision. Il n’a pas de stage deprovision. L’environnement, ce sont les images, et les images existent avant que les tests commencent.

Chaque job de test déclare ses dépendances comme des services Docker :

services:
  - name: $REGISTRY_URL/platform/rabbitmq:$CI_COMMIT_REF_SLUG
    alias: rabbitmq
  - name: $REGISTRY_URL/platform/minio:$CI_COMMIT_REF_SLUG
    alias: minio
  - name: redis:7.4.1
    alias: redis
  - name: $ARTIFACTORY_URL/postgresql:13
    alias: postgresql

Les services démarrent en parallèle quand le job commence. Avant que le script de test tourne, un before_script attend qu’ils soient tous prêts :

before_script:
  - $CI_PROJECT_DIR/dockerize
      -wait tcp://postgresql:5432
      -wait tcp://rabbitmq:5672
      -wait tcp://minio:9000
      -wait tcp://redis:6379
      -timeout 120s

Du démarrage du pipeline à la première assertion : quatre-vingt-dix secondes — en supposant que les images sont déjà dans le cache du runner ; un cold pull rallonge les choses, mais devient négligeable une fois que le pipeline a tourné une fois sur une branche donnée.

Ce que signifie $CI_COMMIT_REF_SLUG

Le timing est le résultat visible. Ce qui le produit est plus intéressant encore : les noms des images.

$REGISTRY_URL/platform/rabbitmq:$CI_COMMIT_REF_SLUG n’est pas l’image officielle RabbitMQ de Docker Hub. C’est une image construite par le même pipeline, depuis la même branche, au même commit que le code testé. L’image RabbitMQ embarque la topologie : un definitions.json avec chaque exchange, chaque queue, chaque binding, chaque configuration de dead-letter — versionné dans git aux côtés de l’application qui en dépend.

Si une branche modifie la topologie de messages, le pipeline CI construit une nouvelle image RabbitMQ qui inclut ces modifications, puis exécute les tests contre elle. Le changement de topologie et le code qui en dépend sont testés ensemble, au même commit, avant que quoi que ce soit n’atteigne le staging.

La même logique s’applique à MinIO, décrite dans le premier article de cette série : l’image MinIO embarque des fixtures de test préchargées. L’environnement CI n’a pas besoin d’une étape de setup pour peupler le stockage. L’état est intégré à l’artefact.

Le runner de tests lui-même suit le même pattern. Chaque job utilise une variante debug de l’image applicative — construite depuis la même branche, au même commit — avec les dépendances de test incluses :

image: $REGISTRY_URL/platform/$service:$CI_COMMIT_REF_SLUG-debug

Tout l’environnement s’assemble depuis des artefacts construits au même point de l’historique git.

Ce que ça a demandé d’abandonner

Behat et la VM provisionnée étaient couplés. La suite de tests Behat tournait contre un serveur HTTP sur la VM ; supprimer la VM signifiait supprimer Behat.

Ça s’est révélé moins bloquant que ça n’en avait l’air. La suite Behat vivait dans un dépôt séparé, nécessitait la VM pour tourner, et avait accumulé une charge de maintenance significative. PHPUnit, tournant dans le container applicatif avec les services Docker, couvrait les mêmes scénarios par un chemin plus direct : tests fonctionnels qui exercent la couche HTTP, tests unitaires pour les composants individuels, suites organisées par domaine fonctionnel et générées dynamiquement en jobs CI parallèles.

La couche BDD a disparu. La couverture de tests est restée — et pouvait désormais tourner contre les vrais services.

Le Facteur X, appliqué

Le Facteur X se lit souvent comme “utilise la même base de données en local qu’en production.” C’est la version la plus simple. La version plus profonde concerne l’écart entre ce qu’on teste et ce qu’on livre.

L’écart dans l’ancien pipeline était large : une VM configurée manuellement, privée de services clés, reconstruite de zéro à chaque run. L’écart dans le nouveau pipeline est étroit : le CI assemble l’environnement depuis les mêmes images que la production, construites au même commit que le code sous test.

Les quinze minutes de Terraform et Ansible n’étaient pas seulement lentes. Elles construisaient quelque chose qui n’était pas ce que la production faisait tourner, à chaque fois, avant que le moindre test puisse commencer. Les quatre-vingt-dix secondes de docker pull construisent exactement ce que la production fait tourner — et les tests qui suivent testent ça, pas une approximation.

docker run --rm <image> php -r "var_dump(require '.env.local.php');"

La sortie montrait tout ce que composer dump-env prod avait compilé dans l’image au moment du build. Ce qui voulait dire tout ce qui se trouvait dans le fichier .env quand l’image avait été construite. Ce qui voulait dire, entre autres, ça :

INFLUXDB_INIT_ADMIN_TOKEN=<influxdb-admin-token>
GF_SECURITY_ADMIN_USER=admin
GF_SECURITY_ADMIN_PASSWORD=admin123
BLACKFIRE_CLIENT_ID=<blackfire-client-id>
BLACKFIRE_CLIENT_TOKEN=<blackfire-client-token>
BLACKFIRE_SERVER_ID=<blackfire-server-id>
BLACKFIRE_SERVER_TOKEN=<blackfire-server-token>
NGROK_AUTHTOKEN=replace-me-optionnal

Vingt-cinq variables au total. Chaque credential accumulé dans le .env racine sur trois ans, désormais permanent dans un layer d’image.

Comment dump-env fonctionne

composer dump-env prod est une optimisation Symfony légitime. Au lieu de parser les fichiers .env à chaque requête, le runtime charge un tableau PHP pré-compilé depuis .env.local.php. Plus rapide et plus simple.

Le problème, c’est ce qu’il lit. Le Dockerfile copie le dépôt dans l’image avec COPY . ./, .env inclus. Ensuite dump-env prod lit ce fichier et compile chaque variable dans .env.local.php. L’image est livrée avec une capture figée des credentials qui se trouvaient dans .env au moment du build.

Les layers Docker sont des archives immuables. Même si une étape ultérieure supprimait .env du système de fichiers du container, le layer qui le contient existerait toujours dans l’image. docker save <image> produit une archive tar de chaque layer ; extraire un fichier spécifique de n’importe quel point de l’historique de build est une opération simple. Les credentials sont invisibles à l’exécution. Ils ne sont pas partis.

Le Facteur V est explicite là-dessus : un artefact de build doit être agnostique à l’environnement, la config arrivant à l’étape de release depuis l’extérieur. Dès que des credentials sont compilés dedans, l’image n’est plus portable. On ne peut plus la promouvoir entre environnements. On builde deux fois en espérant que le deuxième se comporte comme le premier.

Comment vingt-cinq variables s’accumulent

Avant de voir comment on a réparé ça, il vaut la peine de comprendre comment on en est arrivé là.

Les tokens BLACKFIRE_* sont le cas facile à comprendre. Un membre de l’équipe configure le profiling, a besoin de partager la configuration, et le dépôt est déjà ouvert à tout le monde. Une ligne dans .env est la voie de moindre résistance. Les credentials InfluxDB et Grafana suivent la même logique — outillage partagé, dépôt partagé, un commit.

Puis il y a les variables qui révèlent une autre dérive. Dans certains .env de services :

APP__RATINGS__SERIALS='{"marque1":{"fr":"12345"},...}'  # ~40 lignes de JSON
APP__YOUTUBE__CREDENTIALS='{"marque1":{"client_id":"xxx","refresh_token":"yyy"},...}'

Des numéros de série pour la mesure d’audience. Des refresh tokens YouTube par marque. Ce ne sont pas des secrets au sens des tokens Blackfire. Ce sont des données métier — le genre de valeurs qui varient entre marques et environnements, que quelqu’un a décidé de versionner dans .env parce qu’elles se comportaient comme de la configuration et que .env était l’endroit où vivait la configuration.

Vingt-cinq variables, c’est la somme de décisions incrémentales, dont aucune ne semblait fausse isolément. Le problème est structurel : quand .env est la seule réponse disponible, tout finit par y ressembler.

Où les choses appartiennent vraiment

Vider le fichier exigeait de répondre à une question pour chaque variable : où est-ce que ça appartient vraiment ?

Les réponses ont révélé trois catégories que l’équipe n’avait jamais explicitement nommées :

La config statique vit dans le code. Règles métier, logique de routing, fichiers de paramètres Symfony — tout ce qui ne varie pas entre les déploiements. Un changement exige un rebuild. Les blocs JSON de numéros de série se sont révélés ne pas être de la config statique du tout : ils étaient interrogés depuis un service Config dédié à l’exécution. Ils n’avaient rien à faire dans un fichier.

La config environnementale varie entre les déploiements : hostnames, chaînes de connexion, credentials de services tiers. C’est ce que le Facteur III désigne par “config dans les variables d’environnement” — de vraies variables au niveau OS, injectées à l’exécution, jamais des fichiers qui voyagent avec le code. Dans Kubernetes, c’est un ConfigMap pour les valeurs non sensibles et un Kubernetes Secret pour les credentials. Le choix retenu pour les secrets a été SOPS — les credentials sont chiffrés et committés dans git, plutôt que stockés dans un coffre-fort externe comme Azure Key Vault ou HashiCorp Vault. Un coffre-fort échange la simplicité contre l’auditabilité : rotation automatique, logs d’audit centralisés, accès via workload identity sans clé à protéger. SOPS échange ces capacités contre un modèle opérationnel plus simple — pas de service externe à interroger au déploiement, les secrets transitent par le processus de review normal du code, l’historique git fait office de piste d’audit. Les contreparties acceptées sont la rotation manuelle et la responsabilité de protéger la clé de déchiffrement elle-même. Pour la taille de l’équipe, le compromis était délibéré.

La config dynamique change sans déploiement : paramètres éditoriaux, seuils par marque, configuration de modération de contenu. Elle appartient à une base de données, gérée via le service Config de l’application. Une partie de ce qui s’était accumulé dans les .env de services était cette catégorie depuis le début, passant pour des valeurs par défaut statiques parce qu’elle changeait assez rarement pour que personne ne le remarque.

Une fois les catégories nommées, les variables se sont triées. Le .env racine est arrivé à quatre lignes :

DOMAIN=platform.127.0.0.1.sslip.io
XDEBUG_MODE=off
SERVER_NAME=:80
APP_ENV=dev

Des valeurs par défaut sûres. Rien de sensible. dump-env prod compile maintenant des chaînes vides ; les vraies valeurs arrivent à l’exécution depuis Kubernetes.

L’image PostgreSQL

L’image PostgreSQL utilisée en CI a un mot de passe codé en dur :

FROM postgres:15
ENV POSTGRES_PASSWORD=admin123

Ça ressemble au même problème. Ce n’en est pas un, parce que le modèle de menace est différent. La base CI est éphémère — elle existe le temps d’un run de pipeline, ne contient pas de vraies données, tourne dans un réseau isolé. Un mot de passe codé en dur sur une base de test jetable est un risque acceptable, pas une entorse à la règle.

En production, la question ne se pose pas : la plateforme utilise Azure Flexible Server, un service PostgreSQL managé. Il n’y a pas d’image Docker. Les credentials arrivent via injection dans les charts Helm, sans jamais toucher un layer.

Ce qui survit au build maintenant

L’image qui part en production contient maintenant une garantie : var_dump(require '.env.local.php') ne retourne que des chaînes vides et des valeurs par défaut sûres. Les credentials ne sont pas là parce qu’ils n’y ont jamais été mis — ils arrivent à l’exécution, depuis l’extérieur.

C’est la frontière de responsabilité que dump-env avait silencieusement effacée : l’image est l’application, le runtime est l’environnement. Ils ne devraient pas connaître les secrets de l’autre.

À l’époque, Kubernetes n’existait pas encore. Les options pour faire tourner plusieurs services sur une machine se résumaient à du scripting bash, des configurations Nginx écrites à la main, et beaucoup de café. Les tutoriels “homelab pour les humains” brillaient par leur absence.

Ce tuto, c’est ce que j’aurais voulu trouver à l’époque. Ça tourne depuis plusieurs années maintenant. Pas sans évoluer : des services ajoutés, d’autres abandonnés, des choix revisités. Mais la base est là, stable, et c’est bien ça le succès en self-hosting.

Le setup : dix services web auto-hébergés sur une machine locale, accessibles depuis un navigateur via des URLs lisibles, sans toucher à la configuration DNS, sans louer un VPS, sans certificat TLS à gérer. L’ingrédient qui rend ça possible : sslip.io , un service DNS public qui encode l’IP directement dans le nom de domaine. service.192.168.1.10.sslip.io résout vers 192.168.1.10, sans rien configurer, depuis n’importe quelle machine du réseau local.

Ce tutoriel s’adresse à quelqu’un qui connaît Docker mais qui part de zéro sur l’orchestration de services self-hosted.

Table des matières

1. Philosophie et choix d’architecture
2. Les briques fondamentales
3. Mise en place pas à pas
4. Ajouter un nouveau service
5. Patterns et conventions
6. Pièges courants
7. Conclusion
8. Références

1. Philosophie et choix d’architecture

Objectif

Faire tourner plusieurs services web sur une machine locale, accessibles depuis un navigateur via des URLs lisibles, sans toucher à la configuration DNS, sans louer un VPS, sans certificat TLS à gérer.

Pourquoi Docker Compose et pas autre chose ?

Docker Compose est le bon niveau de complexité pour un homelab personnel. Kubernetes est trop lourd pour une seule machine. Docker Swarm est en déclin. Compose est simple, lisible, versionnable, et suffisant pour des dizaines de services.

Pourquoi Traefik et pas Nginx Proxy Manager ?

Nginx Proxy Manager (NPM) est une interface graphique pour configurer Nginx comme reverse proxy. Les routes sont stockées dans une base de données et configurées via une UI.

Traefik lit automatiquement les labels Docker des containers et génère sa configuration à la volée. Quand on démarre un container avec les bons labels, Traefik le découvre et crée la route immédiatement, sans redémarrage, sans UI à ouvrir.

Ce comportement “configuration as code” a deux avantages majeurs :

• La configuration d’un service est dans son compose.yaml, au même endroit que tout le reste.
• Ajouter un service ne nécessite pas de toucher à Traefik.

Pourquoi Dockge et pas Portainer ?

Portainer est un outil de gestion Docker complet : images, volumes, réseaux, containers individuels… puissant mais complexe.

Dockge est focalisé sur une seule chose : gérer des stacks Docker Compose. Son UI est minimaliste et intuitive. Pour un homelab où tout est géré en Compose, c’est suffisant et bien plus agréable à utiliser.

Pourquoi sslip.io ?

Les services web ont besoin d’un nom d’hôte (ex: dozzle.monserveur.local) pour que Traefik puisse les router correctement. Les options habituelles :

• Modifier /etc/hosts sur chaque machine : fastidieux, non partageable.
• Configurer un vrai DNS local (Pi-hole, AdGuard) : nécessite une infrastructure supplémentaire.
• Acheter un domaine et configurer les DNS : coûte de l’argent et du temps.

sslip.io est un service DNS public qui résout automatiquement <anything>.<IP>.sslip.io vers <IP>. Exemple : dozzle.192.168.1.10.sslip.io résout vers 192.168.1.10. Il n’y a rien à configurer, le DNS fonctionne partout sans toucher à quoi que ce soit.

2. Les briques fondamentales

Le réseau Docker partagé

Tous les services et Traefik doivent partager le même réseau Docker pour que Traefik puisse communiquer avec eux. Ce réseau s’appelle traefik et est créé une seule fois :

docker network create traefik

C’est un réseau externe (créé hors de tout Compose). Chaque compose.yaml le déclare comme externe :

networks:
    traefik:
        external: true

Pourquoi externe plutôt qu’interne à un Compose ? Parce que plusieurs stacks indépendants doivent tous y être connectés. Un réseau interne à un Compose n’est accessible qu’aux services de ce Compose.

Traefik : le reverse proxy

Traefik écoute sur le port 80 et route les requêtes HTTP vers le bon container selon le Host header.

Sa configuration principale est dans stacks/traefik/docker/traefik/traefik.yaml :

api:
    dashboard: true
    insecure: true

entryPoints:
    web:
        address: :80
    ping:
        address: :8082

providers:
    docker:
        endpoint: unix:///var/run/docker.sock
        exposedByDefault: false

log:
    level: INFO

global:
    sendAnonymousUsage: false

exposedByDefault: false est important : Traefik ignore tous les containers par défaut. Un container doit explicitement s’exposer avec le label traefik.enable: true. Cela évite d’exposer accidentellement des services.

L’entrypoint ping sur le port 8082 est dédié aux health checks. Le séparer de l’entrypoint web évite que les checks apparaissent dans les logs d’accès.

Pour accéder au daemon Docker, Traefik monte le socket :

volumes:
    - /var/run/docker.sock:/var/run/docker.sock

Dockge : le gestionnaire de stacks

Dockge tourne lui-même dans un container (le compose.yaml à la racine du repo). Il a besoin de deux choses :

1. Accès au socket Docker pour piloter les autres containers.
2. Accès aux dossiers des stacks pour lire et modifier les compose.yaml.

Le point critique est le montage des stacks. Dockge lance les stacks en passant des chemins absolus au daemon Docker. Ces chemins doivent être identiques dans le container Dockge et sur le host. La solution :

volumes:
    - ${PWD}/stacks:${PWD}/stacks
environment:
    DOCKGE_STACKS_DIR: ${PWD}/stacks

${PWD} est une variable shell résolue au moment du docker compose up. Elle vaut le répertoire courant. Si on lance Dockge depuis /home/user/homelab, le dossier stacks sera monté à /home/user/homelab/stacks des deux côtés. C’est la seule façon d’éviter que Docker crée des répertoires fantômes au mauvais endroit.

Conséquence pratique : toujours lancer docker compose up -d depuis la racine du repo.

La donnée persistante de Dockge (configuration, historique) est dans un volume nommé créé à l’avance :

docker volume create homelab_dockge_data

Un volume nommé survit à un docker compose down -v. Un volume anonyme serait détruit avec la stack.

3. Mise en place pas à pas

Étape 1 : cloner et configurer

git clone <repo> homelab
cd homelab

Trouver l’IP locale de la machine :

hostname -I | awk '{print $1}'
# ex: 192.168.1.10

Créer et éditer le .env racine :

cp .env.example .env
# Éditer .env :
# IP=192.168.1.10
# DOMAIN=sslip.io
# COMPOSE_PROJECT_NAME=dockge  ← important, voir section conventions

Étape 2 : prérequis Docker

docker network create traefik
docker volume create homelab_dockge_data

Étape 3 : démarrer Dockge

echo "STACKS_DIR=$(pwd)/stacks" >> .env
docker compose up -d

Dockge est accessible sur http://<IP>:5001. Il est exposé directement sur le port 5001, pas via Traefik (Traefik n’est pas encore démarré à ce stade). Créer un compte admin à la première ouverture.

Étape 4 : configurer les stacks

Pour chaque dossier dans stacks/, copier le .env.example :

for stack in stacks/*/; do
    cp "${stack}.env.example" "${stack}.env"
done

Puis éditer chaque .env pour renseigner IP et DOMAIN avec les mêmes valeurs qu’à l’étape 1. La valeur COMPOSE_PROJECT_NAME est pré-remplie avec le nom du dossier, ne pas la changer (voir section conventions).

Pour filebrowser, renseigner aussi FILEBROWSER_ROOT avec le chemin local à exposer.

Étape 5 : lancer les stacks depuis Dockge

Depuis l’interface Dockge (http://<IP>:5001), dans cet ordre :

1. Traefik en premier

Traefik doit être actif avant les autres services. Sans Traefik, les routes n’existent pas et les services sont inaccessibles via leur URL.

Après démarrage, vérifier que Traefik est healthy :

docker ps --filter name=traefik

2. Les autres stacks dans n’importe quel ordre

Chaque stack se déclare automatiquement auprès de Traefik via ses labels Docker. Traefik découvre les nouveaux containers en temps réel.

3. Homepage en dernier

Homepage lit les labels Docker de tous les containers au démarrage pour construire le dashboard. Le démarrer en dernier garantit qu’il découvre tous les services actifs dès le premier lancement.

4. Ajouter un nouveau service

Voici le template de compose.yaml pour tout nouveau service :

services:
    monservice:
        image: editeur/monservice:latest
        restart: unless-stopped
        healthcheck:
            test: ["CMD-SHELL", "wget -qO- http://127.0.0.1:<PORT>/ || exit 1"]
            interval: 30s
            timeout: 10s
            retries: 3
            start_period: 10s
        labels:
            # Homepage - apparition automatique dans le dashboard
            homepage.group: outils
            homepage.name: Mon Service
            homepage.icon: https://cdn.jsdelivr.net/gh/selfhst/icons/webp/monservice.webp
            homepage.href: http://${COMPOSE_PROJECT_NAME}.${IP}.${DOMAIN}

            # Traefik - routage HTTP
            traefik.enable: true
            traefik.http.routers.monservice.entrypoints: web
            traefik.http.routers.monservice.rule: Host(`${COMPOSE_PROJECT_NAME}.${IP}.${DOMAIN}`)
            traefik.http.services.monservice.loadbalancer.server.port: <PORT>
        networks:
            - traefik

networks:
    traefik:
        external: true

Et le .env.example associé :

COMPOSE_PROJECT_NAME=monservice
IP=127.0.0.1
DOMAIN=sslip.io

Le nom du dossier détermine le sous-domaine. Si le dossier s’appelle monservice, le service sera accessible sur monservice.<IP>.<DOMAIN>. C’est tout.

Pour trouver des services à ajouter, selfh.st est une excellente ressource : c’est un catalogue de logiciels self-hosted organisé par catégorie (media, sécurité, productivité, monitoring…), avec pour chacun une description, une capture d’écran et le lien GitHub. Le site publie aussi une newsletter hebdomadaire sur les nouvelles releases.

Checklist pour un nouveau service

• Créer stacks/<nom-du-sous-domaine>/compose.yaml
• Créer stacks/<nom-du-sous-domaine>/.env.example avec COMPOSE_PROJECT_NAME=<nom>
• Copier .env.example en .env et renseigner IP/DOMAIN
• Vérifier le port dans les labels Traefik
• Choisir le groupe Homepage : infra, observabilité, ou outils
• Trouver l’icône sur selfhst/icons
• Ajouter les données persistantes dans un volume si nécessaire
• Lancer depuis Dockge et vérifier que le container est healthy

5. Patterns et conventions

La variable ${COMPOSE_PROJECT_NAME}

Docker Compose valorise automatiquement COMPOSE_PROJECT_NAME avec le nom du dossier du stack. On l’utilise pour construire dynamiquement les URLs :

traefik.http.routers.dozzle.rule: Host(`${COMPOSE_PROJECT_NAME}.${IP}.${DOMAIN}`)
homepage.href: http://${COMPOSE_PROJECT_NAME}.${IP}.${DOMAIN}

Avantage : pas de variable *_HOST à maintenir dans chaque .env. Renommer le dossier change automatiquement le sous-domaine.

Attention : dans le .env, il faut définir COMPOSE_PROJECT_NAME explicitement avec le nom du dossier du stack. Si on ne le définit pas, Docker Compose utilise le nom du répertoire courant au moment du lancement, ce qui peut donner des valeurs inattendues selon d’où on lance la commande.

Les groupes Homepage

Les services sont organisés en trois groupes dans le dashboard :

Ce découpage est celui de ce homelab, pas une convention imposée. Homepage accepte n’importe quelle valeur dans homepage.group : on peut créer autant de groupes que nécessaire et les nommer comme on veut (media, domotique, dev…). Le dashboard se réorganise automatiquement.

Health checks

Tous les services ont un health check. C’est crucial car Traefik ignore silencieusement les containers unhealthy : un service avec un health check défaillant n’apparaît pas dans le routage, même avec traefik.enable: true.

Trois cas particuliers rencontrés en pratique :

1. localhost ne résout pas toujours en 127.0.0.1

Dans certaines images minimalistes, localhost n’est pas résolu. Utiliser 127.0.0.1 explicitement :

test: ["CMD-SHELL", "wget -qO- http://127.0.0.1:8080/ || exit 1"]

2. Images sans shell (scratch-based)

Les images basées sur scratch (ex: Dozzle) ne contiennent pas /bin/sh. CMD-SHELL échoue. Utiliser le binaire embarqué :

test: ["CMD", "/dozzle", "healthcheck"]

3. Images sans wget ni curl

Certaines images Node.js ou JVM n’ont ni wget ni curl. Solutions possibles :

• Si Node.js est disponible : node -e "require('http').get('http://localhost:PORT', r => process.exit(r.statusCode < 400 ? 0 : 1)).on('error', () => process.exit(1))"
• Si curl est disponible : curl -fs http://127.0.0.1:PORT/
• Si le binaire de l’app expose une sous-commande healthcheck : l’utiliser directement.

Persistance des données

Pour les services qui ont des données (configuration, base utilisateurs, base de données) :

volumes:
    - ./docker/data:/chemin/dans/container

Le dossier ./docker/ est dans le dossier du stack et peut être versionné, à l’exception des données runtime qui vont dans .gitignore.

Règle : ajouter stacks/<service>/docker/ dans .gitignore si le dossier contient des données qui ne doivent pas être committées (base SQLite, uploads…).

Organisation des labels Traefik

Par convention, le nom utilisé dans les labels Traefik (traefik.http.routers.<nom>) correspond au nom du service Docker dans le compose.yaml. En pratique on les aligne avec le nom du dossier :

stacks/it-tools/    →    service: ittools    →    traefik.http.routers.ittools.*

Ce n’est pas une contrainte technique de Traefik, juste une convention de lisibilité.

6. Pièges courants

Dockge : Stop puis Start, pas Restart

Quand on modifie un compose.yaml depuis l’IDE et qu’on veut appliquer les changements, il faut faire Stop + Start depuis Dockge, pas “Restart”. Le Restart redémarre le container existant sans relire le compose.yaml. Le Stop + Start recrée le container avec la nouvelle configuration.

Labels modifiés : redémarrer Homepage

Homepage lit les labels Docker au démarrage. Si on change le homepage.group ou homepage.name d’un service, Homepage ne le voit pas tant qu’il n’est pas redémarré.

Le container démarre mais n’est pas routable

Vérifier dans l’ordre :

1. docker ps : le container est-il healthy ? Traefik ignore les containers unhealthy.
2. Le container est-il sur le réseau traefik ?

docker inspect <container> --format '{{json .NetworkSettings.Networks}}'

3. Le label traefik.enable: true est-il présent ?
4. La règle Host(...) correspond-elle à l’URL testée ?

Montage de fichiers inexistants sous Docker Desktop / WSL

Quand Docker Desktop (WSL) monte un fichier qui n’existe pas encore sur le host, il crée un répertoire à la place. Ce répertoire fantôme bloque ensuite le montage du vrai fichier. Symptôme : le container refuse de démarrer avec une erreur de montage.

Solution : s’assurer que le fichier existe sur le host avant de démarrer le container, ou utiliser un montage de répertoire plutôt que de fichier.

Watchtower : API Docker trop ancienne

Sur certaines configurations, Watchtower tente de communiquer avec le daemon en commençant la négociation à l’API v1.25 (son minimum historique). Les versions récentes de Docker refusent cette version. Symptôme : le container redémarre en boucle avec client version 1.25 is too old. Minimum supported API version is 1.40.

Fix dans le compose.yaml de Watchtower :

environment:
    DOCKER_API_VERSION: "1.40"

1.40 est la valeur à mettre, quelle que soit ta version de Docker. Ce n’est pas ta version exacte, c’est le minimum que le daemon accepte, indiqué dans le message d’erreur. Pour vérifier la version d’API réelle de ton daemon :

docker version --format '{{.Server.APIVersion}}'

${PWD} dans le compose de Dockge

${PWD} n’est pas une variable .env, c’est une variable shell résolue au moment du docker compose up. Elle vaut le répertoire courant du terminal. Lancer docker compose up -d depuis n’importe quel autre répertoire donnera une mauvaise valeur et cassera les montages de volumes des stacks.

Ce homelab est conçu pour tourner sur une machine Linux ou WSL. Toutes les commandes sont testées sur Ubuntu/WSL2 avec Docker Desktop.

Conclusion

J’ai bien conscience que ce tuto ne couvre pas tout. On aurait pu ajouter de l’authentification devant chaque service, faire tourner l’ensemble en HTTPS, mettre en place un socket proxy pour limiter l’exposition du daemon Docker, ou épingler précisément chaque version d’image. Mais chacun de ces points aurait considérablement allongé l’article et la complexité de mise en place. L’objectif était de démarrer avec quelque chose de fonctionnel et maintenable, pas de construire une forteresse dès le premier jour.

Le homelab parfait n’existe pas. Celui qui tourne, si.

guillaumedelre/homelab

Homelab Docker Compose avec Traefik — stacks indépendants, dashboard auto-configuré, et zéro configuration DNS grâce à sslip.io.

Références

Puis en mars 2025, Let’s Encrypt a révoqué le certificat. Le wildcard cert pour traefik.me est parti et il ne reviendra pas.

Ce que traefik.me vendait vraiment

traefik.me est un résolveur DNS wildcard. Tapez anything.traefik.me et ça résout vers 127.0.0.1. Tapez anything.10.0.0.1.traefik.me et ça résout vers 10.0.0.1. Aucun compte, aucune configuration, aucune infrastructure à maintenir. La partie DNS fonctionne toujours bien, soit dit en passant.

Le certificat était le bonus: un wildcard cert pour *.traefik.me que pyrou, le mainteneur, avait généré avec Let’s Encrypt et distribué sur https://traefik.me/cert.pem et https://traefik.me/privkey.pem. C’était pratique précisément parce que c’était partagé: télécharger, déposer dans Traefik, terminé.

Partager une clé privée, c’est ce qui l’a tué.

Les Baseline Requirements du CA/Browser Forum, section 9.6.3, exigent que les souscripteurs “maintiennent le contrôle exclusif” de leur clé privée. La distribuer à quiconque visite une URL, c’est exactement le contraire du contrôle exclusif. Let’s Encrypt a envoyé une notification, bloqué toute future émission pour le domaine, et révoqué le certificat existant. Pyrou a confirmé la situation et recommandé mkcert comme alternative. Le projet survivra uniquement en tant que résolveur DNS.

Le cert avait déjà été révoqué deux fois avant 2025. La troisième était la dernière.

sslip.io fait la même chose, différemment

sslip.io est aussi un résolveur DNS wildcard, avec une différence: l’IP est encodée dans le hostname plutôt que résolue depuis un fallback. 10-0-0-1.sslip.io résout vers 10.0.0.1. myapp.192-168-1-10.sslip.io résout vers 192.168.1.10. IPv6 fonctionne aussi.

L’infrastructure derrière sslip.io est aussi plus visible: trois serveurs de noms à Singapour, aux États-Unis et en Pologne, traitant plus de 10 000 requêtes par seconde, avec un monitoring public. Environ 1 000 étoiles GitHub et une maintenance active sous licence Apache 2.0.

En mettant de côté l’histoire des certificats, la comparaison est assez directe:

Le seul avantage restant de traefik.me est le fallback vers 127.0.0.1: des URLs sans segment IP. Ça compte si on tient vraiment à myapp.traefik.me plutôt que myapp.127-0-0-1.sslip.io. La question est de savoir si cette différence vaut l’incertitude sur l’infrastructure.

mkcert comble le vide

mkcert crée une autorité de certification locale, l’installe dans le trust store système et dans les navigateurs qu’il trouve, puis émet des certificats signés par cette CA. Les navigateurs voient une chaîne de confiance valide. Aucun avertissement, aucun clic, aucun “continuer quand même”.

mkcert -install

C’est la configuration unique. Ensuite, générer un certificat se fait en une commande:

mkcert "*.127-0-0-1.sslip.io"
# produit _wildcard.127-0-0-1.sslip.io.pem
#         _wildcard.127-0-0-1.sslip.io-key.pem

La limitation: la CA de mkcert est locale. Les autres machines du réseau ne lui feront pas confiance par défaut. Pour un setup solo, c’est très bien. Pour un environnement d’équipe partagé, il faudrait distribuer la CA root, ce qui est essentiellement le même problème opérationnel que traefik.me tentait d’éviter, juste à plus petite échelle.

La configuration Traefik

Le setup est le même quelle que soit la solution DNS choisie. Traefik a besoin du certificat monté en volume et d’un file provider statique pointant vers un fichier de configuration TLS.

# traefik/config/tls.yml
tls:
  certificates:
    - certFile: /certs/cert.pem
      keyFile: /certs/key.pem
  stores:
    default:
      defaultCertificate:
        certFile: /certs/cert.pem
        keyFile: /certs/key.pem

La bonne pratique: faire tourner Traefik dans son propre projet Compose, séparé des services qu’il route. Chaque projet de service se connecte à Traefik via un réseau externe partagé. On démarre et arrête les services indépendamment sans toucher au reverse proxy.

On commence par créer le réseau externe une seule fois:

docker network create traefik-public

traefik/compose.yml - Traefik seul, propriétaire du réseau:

services:
  traefik:
    image: traefik:v3
    ports:
      - "80:80"
      - "443:443"
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock
      - ./config:/etc/traefik/config
      - ./certs:/certs
    command:
      - --entrypoints.web.address=:80
      - --entrypoints.websecure.address=:443
      - --providers.docker=true
      - --providers.docker.network=traefik-public
      - --providers.file.directory=/etc/traefik/config
    networks:
      - traefik-public

networks:
  traefik-public:
    external: true

On copie la sortie de mkcert dans ./certs/, on renomme en cert.pem et key.pem, puis:

docker compose -f traefik/compose.yml up -d

Traefik est lancé, il écoute sur le port 80 et 443, et surveille Docker pour les nouveaux containers. Aucune route n’est encore configurée.

whoami/compose.yml - un service qui rejoint le même réseau:

services:
  whoami:
    image: traefik/whoami
    labels:
      - "traefik.enable=true"
      - "traefik.http.routers.whoami.rule=Host(`whoami.127-0-0-1.sslip.io`)"
      - "traefik.http.routers.whoami.tls=true"
      - "traefik.http.routers.whoami.entrypoints=websecure"
    networks:
      - traefik-public

networks:
  traefik-public:
    external: true

docker compose -f whoami/compose.yml up -d

Traefik détecte le nouveau container via le Docker provider, lit ses labels, et ajoute la route. https://whoami.127-0-0-1.sslip.io répond immédiatement. Arrêter whoami et la route disparaît. Traefik continue de tourner sans s’en apercevoir.

La déclaration external: true est la ligne qui porte tout le poids. Sans elle, Compose crée un réseau limité au périmètre du projet: Traefik et whoami se retrouvent sur des réseaux différents et ne peuvent pas communiquer, même s’ils tournent tous les deux. Le réseau externe est le bus partagé auquel chaque projet de service doit explicitement adhérer.

Si on préfère les URLs traefik.me, il suffit de remplacer la commande mkcert et le label de host:

mkcert "*.traefik.me"

- "traefik.http.routers.whoami.rule=Host(`whoami.traefik.me`)"

Le fallback DNS vers 127.0.0.1 gère le reste.

Ce que l’histoire traefik.me enseigne vraiment

Le modèle de distribution de certificats a toujours été fragile. Une “paire clé publique-clé privée” est une contradiction dans les termes. Chaque révocation était un avertissement que la suivante pourrait être définitive. Finalement, ça l’a été.

La leçon ne se limite pas à traefik.me. Tout service qui apporte de la commodité en supprimant discrètement une frontière de sécurité finira par se heurter à cette frontière. mkcert est le bon outil pour ce problème parce qu’il opère entièrement dans votre propre domaine de confiance: on génère la CA, on l’installe, on émet les certificats. Rien ne dépend de la volonté continue d’un tiers de contourner les règles d’émission de certificats.

sslip.io résout proprement la partie DNS. mkcert résout proprement la partie TLS. Ils se combinent bien. Le setup traefik.me était plus simple, pendant un temps. Jusqu’à ce que ce ne soit plus le cas.

Les années Vagrant

Le setup avait du sens à l’époque. Une VM par projet, provisionnée avec des scripts shell ou Ansible, partagée via un Vagrantfile versionné. L’onboarding était théoriquement vagrant up et c’est terminé.

En pratique, c’était vagrant up, attendre quatre minutes, regarder la provision échouer sur un package qui avait changé son URL de téléchargement, corriger, reprovisionner, attendre à nouveau. Les Vagrantfiles accumulaient de la configuration au fil du temps : des contournements pour des machines spécifiques, du pinning de version d’OS, des ajustements mémoire pour le membre de l’équipe dont le laptop n’avait que 8 Go. Les fichiers devenaient des documents historiques que personne ne voulait toucher.

La VM elle-même était l’autre problème. Le boot prenait du temps. Faire tourner la VM consommait de la mémoire et du CPU qui auraient pu aller à l’application. La synchronisation des fichiers entre host et guest ajoutait une latence qui faisait paraître les applications PHP plus lentes qu’elles n’avaient le droit d’être. L’overhead était significatif pour ce qui était finalement juste “faire tourner un serveur web”.

On vivait avec parce que tout le monde le faisait. Vagrant était le standard pour le développement PHP local, et l’alternative (chaque développeur gérant son propre stack LAMP) était clairement pire.

Le projet qui a changé le modèle

Le changement n’était pas une décision qu’on a prise. C’était un projet qui est arrivé déjà conteneurisé.

Un nouveau projet client avait un docker-compose.yml à la racine, un Dockerfile, et un README qui disait docker compose up. On l’a lancé. Les conteneurs ont démarré en secondes. PHP-FPM, nginx, PostgreSQL, Redis : tout tournait, tout était en réseau, pas d’étape de provision. Arrêter les conteneurs, les redémarrer, même état.

Le contraste avec notre setup Vagrant était immédiat. Pas plus rapide d’un pourcentage : plus rapide d’un ordre de grandeur différent. Et le fichier Compose était réellement lisible : chaque service, son image, ses volumes, ses variables d’environnement, ses dépendances. Comparé à un script de provision qui SSH-ait dans une VM et lançait apt-get, c’était lisible.

On a tout migré. Pas progressivement, tout à la fois, sur un sprint. Chaque projet a reçu un docker-compose.yml. Chaque Vagrantfile a été supprimé. La transition a été les trois semaines de travail d’infrastructure les plus douloureuses dont je me souvienne, et aussi les plus clairement valables.

Ce que docker-compose a vraiment changé

Au-delà de la vitesse, Compose a changé le modèle mental. Vagrant abstrayait une machine. Compose abstrayait un ensemble de processus. La distinction compte : avec Compose, on peut arrêter la base de données sans arrêter le serveur d’application, scaler un service worker indépendamment, échanger l’image PostgreSQL contre une version plus récente sans toucher à quoi que ce soit d’autre.

La déclaration services a aussi entièrement remplacé le problème de provision des VMs. Si un nouveau développeur rejoint l’équipe, il ne lance pas un script de provision qui peut ou ne pas fonctionner sur sa version d’OS. Il lance docker compose up et obtient exactement les mêmes images que tout le monde.

Le CI/CD est devenu plus simple aussi. Le même docker-compose.yml qui tournait en local pouvait tourner dans le pipeline. La parité d’environnement que Vagrant promettait mais livrait rarement était réellement réelle avec Compose.

La dépréciation silencieuse

Pendant des années, la commande était docker-compose : un binaire séparé, installé indépendamment de Docker lui-même, écrit en Python, versionné indépendamment. On l’utilisait, ça marchait, personne n’y pensait vraiment.

À un moment, un collègue a mentionné que Docker avait intégré Compose directement dans le CLI docker. La nouvelle commande était docker compose, sans tiret, réécriture en Go, intégré avec Docker Desktop. L’ancien binaire docker-compose était déprécié.

On avait utilisé v1 pendant deux ans après que v2 était sortie. Nos scripts CI, nos Makefiles, notre documentation disaient tous docker-compose. Rien n’avait cassé parce que Docker avait maintenu l’ancien binaire longtemps. Mais l’écosystème avait évolué silencieusement, et on l’avait raté.

La migration était triviale : un tiret retiré de chaque script, quelques alias mis à jour. La leçon était moins triviale. Les outils d’infrastructure évoluent sans cérémonie. L’annonce avait eu lieu, les articles de blog avaient été écrits, les notices de dépréciation étaient là. On ne faisait juste pas attention.

La vraie rétrospective

En regardant en arrière à travers Vagrant → docker-compose → docker compose, le pattern concerne moins les outils que les defaults.

Vagrant defaultait à “ça marche sur ma VM”. L’overhead de partager cette VM était permanent.

Compose defaultait à “ça marche dans ces conteneurs”. Les images sont les artefacts ; la machine host est hors sujet.

Le tiret entre docker et compose a toujours été cosmétique. Ce qui comptait, c’était le passage des machines provisionnées aux services déclaratifs. Ce passage a eu lieu le jour où on a lancé un projet que quelqu’un d’autre avait conteneurisé et où on a réalisé qu’on ne voulait jamais revenir en arrière.

Un Dream Cheeky Thunder a atterri sur un bureau peu après. Quatre missiles en mousse, un câble USB, et un consensus d’équipe très clair : le brancher au cluster, le câbler au pipeline de build, et laisser le CI décider qui mérite une volée.

Le lanceur devait répondre à des appels HTTP depuis n’importe où sur le réseau. Sans driver, sans GUI, sans visée manuelle. Juste un endpoint qui le fait tirer dans la direction du bureau du coupable.

Voilà l’histoire de dream-cheeky-thunder.

Pas de SDK, pas de docs, pas de problème

Dream Cheeky n’a jamais publié de spec de protocole. Le lanceur parle USB HID brut, et le seul point de départ était un script Python vendorisé de 2012 qui traînait dans des fils de forum. Vendor ID 0x2123, product ID 0x1010, et une poignée d’octets de contrôle que quelqu’un avait rétro-ingénié des années auparavant.

C’était suffisant. Le protocole est simple : envoyer une séquence d’octets pour bouger les moteurs, en envoyer une autre pour tirer. La partie délicate : le lanceur n’a aucun retour de position. Pas d’encodeurs, pas de fins de course en dehors des butées physiques aux extrémités. On le pilote à l’aveugle.

Du USB au HTTP

Le pipeline CI devait déclencher le lanceur par le réseau. Un script local ne suffisait pas — le lanceur devait être accessible depuis n’importe quelle machine du cluster, y compris le serveur de build. Donc : une API REST.

FastAPI était le choix évident. Le flux de ciblage côté CI se résume à trois appels HTTP :

curl -X POST http://localhost:8000/park      # reset vers une position connue
curl -X POST http://localhost:8000/yaw/20    # rotation vers le bureau du coupable
curl -X POST "http://localhost:8000/fire?shots=2"

L’appel /park est plus important qu’il n’y paraît. Puisque le lanceur n’a pas de retour de position, le serveur estime l’angle courant en suivant le temps de rotation des moteurs. Cette estimation dérive. Un choc sur le hardware, une commande interrompue, ou simplement l’imprécision du tracking temporel — tout s’accumule. Le parking pousse les deux moteurs contre les butées physiques en balayage complet, ce qui garantit l’alignement quelle que soit la représentation interne du serveur. Sans ça, la visée est une approximation.

La référence complète de l’API est dans le repo. Il y a aussi une UI web si vous préférez cliquer plutôt que curl.

Docker ne connaît pas l’USB

Faire tourner ça dans un conteneur Docker sur le cluster, c’est là que les choses ont commencé à devenir intéressantes : les conteneurs ne voient pas les périphériques USB par défaut.

Le mount devices dans compose.yaml expose le bus USB au conteneur :

devices:
  - /dev/bus/usb:/dev/bus/usb

Pas suffisant. Première exécution : USBError: [Errno 13] Access denied. Le nœud de device est bien là dans le conteneur, mais il hérite des permissions du host, et sur le host seul root peut l’ouvrir par défaut.

La solution : une règle udev. Déposer un fichier dans /etc/udev/rules.d/, et le kernel applique le bon groupe et les bonnes permissions quand le device se branche. Après ça, l’utilisateur du conteneur peut l’ouvrir sans privilèges élevés. La règle est fournie avec le projet, les instructions d’installation sont dans la doc.

WSL2 a rendu ça intéressant

La moitié de l’équipe tourne sous Windows avec Docker Desktop sur WSL2. C’est là que ça devient créatif.

WSL2 n’a pas accès aux périphériques USB par défaut : le kernel Windows les détient, et le mount devices seul ne fait rien parce que WSL2 ne voit simplement pas le hardware. La solution est usbipd-win, qui transfère le périphérique USB de Windows vers le kernel WSL2 par IP. Une fois ça fait, le chemin Linux fonctionne à l’identique : règle udev, mount devices, terminé.

L’attachement ne survit pas aux redémarrages, cependant. usbipd v4+ a ajouté un mécanisme de policy qui automatise la reconnexion, ce qui a mis fin au mystère du “ça marchait hier” qui nous agaçait depuis des jours.

Ce qui nous a vraiment surpris

Le positionnement temporel fonctionne suffisamment bien. Sans encodeurs, on s’attendait à ce que le tracking d’angle soit quasi-inutilisable. En pratique, le parking avant chaque séquence le maintenait assez précis pour viser un bureau spécifique de manière fiable. Pas au millimètre, mais la précision missile en mousse, ça convient.

Le mount devices est nécessaire mais pas suffisant. L’erreur de permission était déroutante précisément parce que le device était clairement visible dans le conteneur. La règle udev est la partie que la plupart des tutoriels passent discrètement sous silence.

La règle café n’a plus jamais été la même après ça. Une fois le lanceur câblé au pipeline, les builds cassés sont devenus beaucoup plus motivants à corriger.

guillaumedelre/dream-cheeky-thunder

FastAPI + Docker + PyUSB — contrôle HTTP pour le lance-missiles USB Dream Cheeky Thunder. Pull requests bienvenus, surtout si vous avez une meilleure approche de calibration d'angle.