Traefik en reverse proxy avec Docker
Déployer Traefik avec Docker Compose sur Debian ou Ubuntu : HTTPS automatique avec Let's Encrypt, publication par labels, tableau de bord protégé, mises à jour et sauvegarde.
Sur cette page
Vos valeurs
Renseignez-les une fois, les commandes du guide se mettent à jour.
Ce guide vous explique comment placer Traefik devant vos conteneurs Docker. Traefik reçoit les visiteurs sur les ports 80 et 443, obtient et renouvelle les certificats Let’s Encrypt, puis transmet chaque requête au bon conteneur d’après ses labels.
À la fin du guide, une application de test répond sur https://app.votre-domaine.com. Le tableau de bord de Traefik est disponible sur https://traefik.votre-domaine.com, uniquement depuis votre adresse IP et avec un mot de passe. Vous saurez aussi mettre à jour et sauvegarder l’installation.
Les versions indiquées sont les dernières versions stables au moment de la rédaction, en novembre 2026 : Traefik v3.7.19 et whoami v1.12.0.
Commander un serveur
Ce guide s’applique aux serveurs que vous administrez vous-même :
Prérequis
- Un serveur sous Debian 12 ou 13, ou Ubuntu 22.04 ou 24.04
- Un accès SSH avec un utilisateur disposant de
sudoet membre du groupedocker - Docker Engine et Docker Compose, installés avec le guide Installer Docker Engine et Docker Compose
- Un nom de domaine dont vous gérez la zone DNS
- Aucun autre logiciel sur les ports 80 et 443, comme Nginx, Apache, Caddy ou Nginx Proxy Manager
- Une adresse IP fixe sur votre poste pour accéder au tableau de bord, ou un VPN
Ports utilisés
| Port | Sens | Rôle | À ouvrir |
|---|---|---|---|
| 80/tcp | Entrant | Validation HTTP-01 et redirection vers HTTPS | Oui |
| 443/tcp | Entrant | Sites en HTTPS et tableau de bord | Oui |
| 8080/tcp | Aucun | API non sécurisée de Traefik, désactivée ici | Non |
| 2375/tcp | Réseau Docker interne | Proxy du socket Docker, jamais publié sur le serveur | Non |
Étape 1 : faire pointer les noms vers le serveur
Créez deux enregistrements A vers VOTRE_IP_SERVEUR : app.votre-domaine.com et traefik.votre-domaine.com. Si votre domaine est géré chez HostMyServers, suivez le guide Créer un enregistrement A.
Vérifiez ensuite le résultat depuis le serveur :
sudo apt update
sudo apt install -y bind9-dnsutils
dig +short A app.votre-domaine.com
dig +short A traefik.votre-domaine.com
dig +short AAAA traefik.votre-domaine.comLes deux premières commandes doivent renvoyer l’adresse de votre serveur. La dernière doit rester vide : le tableau de bord est filtré par adresse IPv4, et une connexion en IPv6 serait refusée.
Étape 2 : préparer les dossiers et le réseau
Créez le dossier du projet et le fichier qui contiendra les certificats. Traefik refuse ce fichier si d’autres utilisateurs que son propriétaire peuvent le lire.
sudo install -d -o "$USER" -g "$USER" /opt/traefik /opt/traefik/letsencrypt
cd /opt/traefik
touch letsencrypt/acme.json
chmod 600 letsencrypt/acme.jsonCréez ensuite le réseau Docker partagé entre Traefik et les applications à publier :
docker network create proxyÉtape 3 : créer le mot de passe du tableau de bord
Installez htpasswd, puis générez l’empreinte du compte admin. La commande demande le mot de passe deux fois :
sudo apt install -y apache2-utils
htpasswd -nB admin > /opt/traefik/dashboard.htpasswd
chmod 600 /opt/traefik/dashboard.htpasswdLe fichier contient une empreinte bcrypt, et non le mot de passe en clair. Le placer dans un fichier évite de devoir doubler les caractères $ dans les labels Docker Compose.
Étape 4 : écrire le fichier Compose
Créez le fichier :
nano /opt/traefik/compose.yamlCollez ce contenu, en remplaçant le domaine, l’adresse e-mail et VOTRE_IP :
services:
socket-proxy:
image: tecnativa/docker-socket-proxy:3.4
container_name: traefik-socket-proxy
restart: unless-stopped
environment:
CONTAINERS: "1"
volumes:
- /var/run/docker.sock:/var/run/docker.sock:ro
networks:
- socket
traefik:
image: traefik:v3.7.19
container_name: traefik
restart: unless-stopped
depends_on:
- socket-proxy
security_opt:
- no-new-privileges:true
ports:
- "80:80"
- "443:443"
command:
- "--entrypoints.web.address=:80"
- "--entrypoints.web.http.redirections.entrypoint.to=websecure"
- "--entrypoints.web.http.redirections.entrypoint.scheme=https"
- "--entrypoints.web.http.redirections.entrypoint.permanent=true"
- "--entrypoints.websecure.address=:443"
- "--entrypoints.websecure.http.tls=true"
- "--entrypoints.websecure.http.tls.certresolver=le"
- "--providers.docker=true"
- "--providers.docker.endpoint=tcp://socket-proxy:2375"
- "--providers.docker.exposedbydefault=false"
- "--providers.docker.network=proxy"
- "--api.dashboard=true"
- "--api.insecure=false"
- "--certificatesresolvers.le.acme.email=admin@votre-domaine.com"
- "--certificatesresolvers.le.acme.storage=/letsencrypt/acme.json"
- "--certificatesresolvers.le.acme.httpchallenge.entrypoint=web"
- "--log.level=INFO"
- "--accesslog=true"
volumes:
- ./letsencrypt:/letsencrypt
- ./dashboard.htpasswd:/etc/traefik/dashboard.htpasswd:ro
networks:
- proxy
- socket
labels:
- "traefik.enable=true"
- "traefik.http.routers.dashboard.rule=Host(`traefik.votre-domaine.com`)"
- "traefik.http.routers.dashboard.entrypoints=websecure"
- "traefik.http.routers.dashboard.service=api@internal"
- "traefik.http.routers.dashboard.middlewares=dashboard-ip,dashboard-auth"
- "traefik.http.middlewares.dashboard-ip.ipallowlist.sourcerange=VOTRE_IP/32"
- "traefik.http.middlewares.dashboard-auth.basicauth.usersfile=/etc/traefik/dashboard.htpasswd"
networks:
proxy:
external: true
socket:
internal: true| Élément | Rôle |
|---|---|
socket-proxy |
Filtre l’accès à l’API Docker : Traefik peut lire les conteneurs, mais ni les créer ni les modifier |
CONTAINERS: "1" |
Autorise la lecture des conteneurs, les requêtes d’écriture restant bloquées par défaut |
socket |
Réseau interne, sans accès à Internet, réservé à Traefik et au proxy |
exposedbydefault=false |
Seuls les conteneurs portant traefik.enable=true sont publiés |
network=proxy |
Traefik joint les applications par ce réseau |
httpchallenge |
Let’s Encrypt valide chaque nom sur le port 80 |
certresolver=le |
Tous les sites du point d’entrée HTTPS reçoivent un certificat |
api@internal |
Service interne qui fournit le tableau de bord |
dashboard-ip puis dashboard-auth |
Filtre l’adresse IP, puis demande le mot de passe |
Traefik ne monte pas le socket Docker directement : si le conteneur exposé à Internet était compromis, l’attaquant n’obtiendrait pas le contrôle de Docker. C’est l’une des protections recommandées par la documentation de Traefik.
Étape 5 : démarrer Traefik
Validez le fichier, puis lancez les conteneurs :
cd /opt/traefik
docker compose config --quiet
docker compose up -d
docker compose psLes deux services doivent être à l’état running. Suivez le démarrage dans les journaux, puis quittez avec Ctrl+C :
docker compose logs -f traefikÉtape 6 : vérifier le pare-feu
Docker publie les ports 80 et 443 avec ses propres règles, appliquées avant celles d’UFW. Ces deux ports sont donc joignables même sans ufw allow, et UFW ne peut pas les restreindre. Le guide Configurer le pare-feu UFW détaille ce fonctionnement.
Deux règles en découlent :
- Ne publiez pas les ports de vos applications : elles restent sur le réseau
proxy, sans sectionports. - Si vous utilisez le firewall intégré de votre instance, autorisez aussi les ports 80 et 443 depuis votre espace client.
Étape 7 : publier une application
Créez une application de test dans son propre dossier :
sudo install -d -o "$USER" -g "$USER" /opt/whoami
nano /opt/whoami/compose.yamlservices:
whoami:
image: traefik/whoami:v1.12.0
restart: unless-stopped
networks:
- proxy
labels:
- "traefik.enable=true"
- "traefik.http.routers.whoami.rule=Host(`app.votre-domaine.com`)"
- "traefik.http.routers.whoami.entrypoints=websecure"
- "traefik.http.services.whoami.loadbalancer.server.port=80"
networks:
proxy:
external: trueDémarrez-la :
cd /opt/whoami
docker compose up -dTraefik détecte le conteneur seul, sans redémarrage. Le label loadbalancer.server.port indique le port d’écoute à l’intérieur du conteneur. Pour vos applications, reprenez ces quatre labels en changeant le nom du routeur, le domaine et le port.
Vérifier le résultat
Testez les deux protocoles, puis contrôlez le certificat :
curl -I http://app.votre-domaine.com
curl -I https://app.votre-domaine.com
echo | openssl s_client -connect app.votre-domaine.com:443 -servername app.votre-domaine.com 2>/dev/null | openssl x509 -noout -issuer -datesLa requête HTTP doit renvoyer une redirection 308 vers HTTPS, et la requête HTTPS un code 200. L’émetteur du certificat doit être Let’s Encrypt. Le premier certificat peut demander quelques instants.
Contrôlez ensuite que le proxy du socket bloque bien ce qui n’est pas autorisé :
cd /opt/traefik
docker compose exec traefik wget -S -O- http://socket-proxy:2375/images/jsonLa réponse attendue est 403 Forbidden.
Depuis votre poste, testez le tableau de bord. Le premier appel doit renvoyer 401, le second la version de Traefik, et le troisième ne doit pas répondre :
curl -I https://traefik.votre-domaine.com/dashboard/
curl -u admin https://traefik.votre-domaine.com/api/version
curl -m 5 http://VOTRE_IP_SERVEUR:8080Ouvrez enfin https://traefik.votre-domaine.com/dashboard/ dans votre navigateur. La barre oblique finale est nécessaire. Depuis une autre adresse IP, la même page doit renvoyer 403.
Gérer l’accès au tableau de bord
Pour changer le mot de passe, régénérez le fichier puis redémarrez Traefik :
cd /opt/traefik
htpasswd -nB admin > dashboard.htpasswd
docker compose restart traefikSi votre adresse IP change, modifiez le label dashboard-ip dans compose.yaml, puis exécutez docker compose up -d. Si elle change souvent, réservez plutôt le tableau de bord à un réseau privé, avec WireGuard ou Tailscale.
Réglages courants
Répondre sur plusieurs noms
- "traefik.http.routers.whoami.rule=Host(`app.votre-domaine.com`) || Host(`www.votre-domaine.com`)"Chaque nom doit pointer vers le serveur pour que le certificat soit délivré.
Protéger une application avec les mêmes règles
Les middlewares déclarés sur le conteneur Traefik sont réutilisables par les autres conteneurs, avec le suffixe @docker :
- "traefik.http.routers.whoami.middlewares=dashboard-ip@docker,dashboard-auth@docker"Mettre à jour
Consultez d’abord les notes de version et, pour un changement de version mineure ou majeure, le guide de migration. Sauvegardez ensuite l’installation, modifiez le tag traefik:v3.7.19 dans compose.yaml, puis exécutez :
cd /opt/traefik
docker compose pull
docker compose up -d
docker compose exec traefik traefik version
docker compose logs --tail 50 traefikL’image tecnativa/docker-socket-proxy:3.4 reste sur la branche HAProxy 3.4 et son éditeur la reconstruit chaque semaine : docker compose pull récupère ces mises à jour. Procédez de la même façon dans /opt/whoami et dans les dossiers de vos applications.
Sauvegarder et restaurer
Le dossier /opt/traefik contient tout ce qu’il faut conserver :
| Chemin | Contenu |
|---|---|
compose.yaml |
Configuration de Traefik et du proxy du socket |
dashboard.htpasswd |
Empreinte du mot de passe du tableau de bord |
letsencrypt/acme.json |
Certificats, clés privées et compte ACME |
sudo tar -czf /root/traefik-$(date +%F).tar.gz -C /opt traefik
sudo chmod 600 /root/traefik-$(date +%F).tar.gzCette archive contient des clés privées : copiez-la hors du serveur dans un emplacement chiffré. Sauvegardez aussi les fichiers Compose et les données de vos applications.
Pour restaurer l’archive, en remplaçant AAAA-MM-JJ par sa date, créez le réseau s’il n’existe pas encore sur ce serveur :
cd /opt/traefik 2>/dev/null && docker compose down
sudo tar -xzf /root/traefik-AAAA-MM-JJ.tar.gz -C /opt
docker network create proxy
cd /opt/traefik
docker compose up -dEn cas de problème
Commencez par consulter les journaux :
cd /opt/traefik
docker compose logs --tail 100 traefik
docker compose logs --tail 50 socket-proxyport is already allocated ou address already in use
Un autre service occupe le port 80 ou 443 :
sudo ss -ltnp | grep -E ':(80|443) '
docker ps --format '{{.Names}} {{.Ports}}'Arrêtez ce service s’il n’est plus utile, par exemple avec sudo systemctl disable --now nginx.
permissions 644 for /letsencrypt/acme.json are too open, please use 600
Corrigez les droits, puis redémarrez Traefik :
chmod 600 /opt/traefik/letsencrypt/acme.json
cd /opt/traefik
docker compose restart traefikFailed to retrieve information of the docker client and server host
Traefik n’arrive pas à joindre le proxy du socket. Vérifiez que socket-proxy fonctionne et que les deux services partagent le réseau socket. Selon la cause indiquée dans ses journaux :
- Si le serveur n’a pas d’IPv6 et que le proxy ne démarre pas, ajoutez
DISABLE_IPV6: "1"à ses variables d’environnement. - Si
CONTAINERSest absent, Traefik reçoit403 Forbiddenen listant les conteneurs. - Si le proxy n’a pas le droit d’ouvrir le socket, son éditeur indique que
privileged: truepeut être nécessaire avec certains profils SELinux ou AppArmor. N’ajoutez cette option qu’en dernier recours.
404 page not found
Aucun routeur ne correspond à la requête. Vérifiez que le conteneur est démarré, qu’il porte traefik.enable=true, que le nom dans Host() est exact et qu’il est bien relié au réseau proxy :
docker network inspect proxy --format '{{range .Containers}}{{.Name}} {{end}}'Bad Gateway ou Gateway Timeout
Traefik trouve le routeur mais ne joint pas l’application. Contrôlez le port indiqué dans loadbalancer.server.port, puis testez depuis Traefik :
cd /opt/traefik
docker compose exec traefik wget -qO- http://whoami:80L’application doit écouter sur 0.0.0.0 dans son conteneur. Si elle écoute seulement sur 127.0.0.1, Traefik ne peut pas l’atteindre.
Le navigateur affiche TRAEFIK DEFAULT CERT
Traefik n’a pas encore de certificat valide pour ce nom et présente son certificat par défaut. Cherchez la cause dans les journaux :
cd /opt/traefik
docker compose logs traefik | grep -iE 'acme|certificate'Unable to obtain ACME certificate for domains
Le message contient la raison du refus :
urn:ietf:params:acme:error:dns: le nom n’existe pas encore dans le DNS ou n’est pas propagé.urn:ietf:params:acme:error:unauthorizedouconnection: Let’s Encrypt ne joint pas le port 80. Vérifiez les enregistrements A et AAAA, puis le firewall de votre instance. Si tout est correct, contactez le support depuis votre espace client.urn:ietf:params:acme:error:caa: un enregistrement CAA interdit Let’s Encrypt.urn:ietf:params:acme:error:rateLimited: trop de demandes ont été envoyées. Attendez la fin de la période indiquée.
Pour vos essais, ajoutez temporairement l’environnement de test de Let’s Encrypt, dont les certificats ne sont pas reconnus par les navigateurs :
- "--certificatesresolvers.le.acme.caserver=https://acme-staging-v02.api.letsencrypt.org/directory"Avant de revenir en production, retirez cette ligne et videz acme.json avec truncate -s 0 /opt/traefik/letsencrypt/acme.json, sans modifier ses droits. Exécutez ensuite docker compose up -d.
403 Forbidden sur le tableau de bord
Votre adresse IP n’est pas celle du label dashboard-ip. Le journal d’accès indique l’adresse vue par Traefik, en début de ligne :
cd /opt/traefik
docker compose logs --no-log-prefix traefik | grep 'dashboard@docker' | tail -n 5Si cette adresse est celle d’une passerelle Docker, la connexion est sans doute arrivée en IPv6 : supprimez l’enregistrement AAAA du nom.
is a directory pour dashboard.htpasswd
Le fichier n’existait pas au premier démarrage et Docker a créé un dossier à sa place. Supprimez-le, recréez le fichier, puis relancez le conteneur :
cd /opt/traefik
docker compose down
sudo rmdir dashboard.htpasswd
htpasswd -nB admin > dashboard.htpasswd
chmod 600 dashboard.htpasswd
docker compose up -d