À 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.