À 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 on migre vers le cloud. La connaissance institutionnelle ne suit pas. L’accès SSH est parti ou peu pratique. Et pour la première fois, on se retrouve à fixer quatorze conteneurs FrankenPHP sans la moindre idée de ce qu’ils font réellement.

C’est le moment où on a besoin de métriques. Pas éventuellement. Avant que la migration soit terminée.

Le problème à le faire correctement

La bonne façon d’instrumenter un service PHP pour Prometheus : ajouter une bibliothèque client, écrire des compteurs et histogrammes autour de ce qui importe, exposer une route /metrics, mettre à jour la config de scrape. Pour un seul service, c’est un après-midi raisonnable. Pour quatorze services en pleine migration, c’est un projet de plusieurs sprints qui entre en compétition avec tout le reste qui doit bouger.

Le calcul est gênant. On a besoin de métriques pour avoir confiance que la migration se passe bien. Mais ajouter des métriques à tout avant la migration signifie que la migration prend plus longtemps. Et plus elle prend longtemps, plus on a besoin de métriques pour savoir où on en est.

Il fallait bien que quelque chose cède.

Ce que FrankenPHP embarque sans l’annoncer

FrankenPHP n’est pas un runtime PHP qui utilise Caddy comme serveur web. La relation est inversée : Caddy est le serveur, et PHP est un module Caddy. Chaque requête HTTP passe par Caddy avant d’atteindre le code applicatif.

Caddy embarque un endpoint compatible Prometheus intégré. Pas de plugin, pas de binaire supplémentaire. Activer l’admin API et il est là.

CADDY_GLOBAL_OPTIONS est une variable d’environnement FrankenPHP qui injecte des directives directement dans le bloc de configuration global de Caddy. Deux lignes suffisent :

environment:
    CADDY_GLOBAL_OPTIONS: |
        admin 0.0.0.0:2019
        metrics

admin 0.0.0.0:2019 lie l’admin API à toutes les interfaces réseau — le défaut est localhost uniquement, inaccessible depuis un conteneur Prometheus sur le même réseau. metrics active l’endpoint.

Après ça, chaque conteneur répond à GET :2019/metrics avec un payload Prometheus complet. Comptes de requêtes labellisés par code de statut, histogrammes de latence, connexions actives. Aucune route ajoutée à l’application. Aucun composer require. Aucun changement au Dockerfile.

Une variable d’environnement, ajoutée à chaque définition de service dans un seul commit. Quatorze cibles de scrape, toutes produisant des données.

Une image utilisable dans Grafana

La config de scrape Prometheus liste chaque service par son nom de conteneur :

scrape_configs:
    - job_name: caddy
      metrics_path: /metrics
      static_configs:
          - targets:
              - authentication:2019
              - content:2019
              - media:2019
              # les 14 services

Grafana se pose au-dessus de Prometheus. Le dashboard communautaire Caddy donne les taux de requêtes, les taux d’erreur et les percentiles de latence par service, par endpoint, par code de statut. En moins d’une journée après que la migration a atterri dans le nouvel environnement, il y avait quelque chose de significatif à regarder.

La couche données suit la même logique : des exporters pour PostgreSQL, Redis et RabbitMQ scrappent au niveau infrastructure sans toucher le code applicatif. Des dashboards communautaires existent pour tous.

Ce que cette baseline couvre réellement

Les métriques HTTP de Caddy sont des métriques de serveur web, pas des métriques applicatives. Elles répondent à : est-ce que ce service reçoit du trafic, est-ce qu’il retourne des erreurs, à quelle vitesse répond-il. Le genre de questions qu’on pose quand quelque chose est cassé et qu’on doit trier dans le noir.

Elles ne répondent pas à : combien d’éléments ont été traités aujourd’hui, quel job en arrière-plan est bloqué, quel est l’impact business de ce pic de latence. Pour ça, il faut de l’instrumentation applicative, et ce travail existe encore quand on a des choses spécifiques à mesurer.

Mais dans un contexte de migration, cette distinction compte moins qu’elle n’en a l’air. Les choses qui cassent pendant une migration cloud sont principalement des problèmes d’infrastructure : un service qui ne peut pas atteindre sa base de données, une limite mémoire définie trop bas, un consumer de queue qui a arrêté de traiter les messages. Ce sont exactement les choses que la baseline couvre.

Avoir l’instrumentation parfaite pour les événements au niveau business peut attendre que la plateforme soit stable. Avoir assez de visibilité pour savoir si la migration a réussi ne peut pas.

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.