Comment configurer Traefik en 2026
Traefik 3.7, installation, labels Docker, ACME DNS et middlewares : le tutoriel complet pour une configuration propre en 2026.
Traefik 3.7 est sorti le 5 mai 2026, et la 3.7.17 tourne depuis le 29 octobre. Si tu es encore sur une configuration v2 recopiée d'un tutoriel de 2024, tu cumules trois problèmes : un support sécurité qui vient de s'éteindre (2.11, le 7 septembre 2026), des labels qui ne correspondent plus à rien et des fichiers statiques mélangés avec du dynamique. Voici comment je monte une instance propre en 2026, de zéro à un HTTPS qui renouvelle ses certificats sans que tu y touches.
Le paysage des versions a changé
Traefik Labs a revu sa politique de support à partir de la 3.6 : chaque minor est maintenue 6 mois, et plusieurs minors cohabitent. Avant, seule la dernière version recevait des correctifs, ce qui poussait à migrer tous les trois mois.
C'est la bonne nouvelle de 2026. La mauvaise, c'est que la 2.11 est en fin de support sécurité depuis le 7 septembre 2026.
| Version | Sortie | Support actif | Support sécurité |
|---|---|---|---|
| 3.7 | 5 mai 2026 | Oui | Oui |
| 3.6 | 7 novembre 2025 | Terminé (7 mai 2026) | Terminé (16 août 2026) |
| 2.11 | 12 février 2024 | Terminé (29 avril 2025) | Terminé (7 septembre 2026) |
Concrètement : si ton reverse proxy expose des domaines clients, la seule ligne défendable aujourd'hui est la 3.7. Le tableau officiel est sur la page des releases.
Installer : binaire ou conteneur, pas les deux
Deux méthodes tiennent la route. Le binaire avec systemd quand Traefik sert de porte d'entrée à la machine elle-même. Le conteneur quand le reste de la stack est déjà en Docker.
Je prends le conteneur pour la suite, parce que c'est le cas le plus fréquent sur un VPS.
services:
traefik:
image: traefik:v3.7
container_name: traefik
restart: unless-stopped
security_opt:
- no-new-privileges:true
networks: [proxy]
ports:
- "80:80"
- "443:443"
volumes:
- /var/run/docker.sock:/var/run/docker.sock:ro
- ./dynamic:/etc/traefik/dynamic:ro
- ./acme:/acme
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"
- "--providers.docker=true"
- "--providers.docker.exposedbydefault=false"
- "--providers.docker.network=proxy"
- "--providers.file.directory=/etc/traefik/dynamic"
networks:
proxy:
name: proxy
Trois détails font la différence entre ce fichier et celui qui casse en production. Le socket Docker est monté en lecture seule, et le provider Docker est en exposedbydefault=false : un conteneur sans label n'est jamais publié par accident.
Le troisième, c'est la redirection HTTP→HTTPS portée par l'entrypoint et non par un routeur séparé. Tu économises un routeur et tu évites les boucles de redirection sur les healthchecks.
Le montage du socket reste le point sensible. Un accès en écriture au socket Docker équivaut à un accès root sur l'hôte.
Variante binaire avec systemd
Si Traefik est la seule chose qui tourne sur la machine, le binaire évite la couche Docker.
curl -fsSL https://github.com/traefik/traefik/releases/download/v3.7.17/traefik_v3.7.17_linux_amd64.tar.gz | tar xz
install -m 755 traefik /usr/local/bin/traefik
traefik versionLe service systemd lit ensuite /etc/traefik/traefik.yml et redémarre en trois secondes. Je garde cette option pour les machines à 2 Go de RAM, où le démon Docker coûte plus que le proxy lui-même.
La procédure officielle est sur la page d'installation Traefik.
Statique et dynamique : la règle qui évite 90 % des bugs
Presque tous les tickets « ma config Traefik est ignorée » viennent d'un fichier dynamique chargé comme du statique, ou l'inverse. La frontière est simple, et elle ne bouge pas depuis la v3.
| Ce qui va dans le statique | Ce qui va dans le dynamique |
|---|---|
| EntryPoints et leurs adresses | Routers (règles Host(), PathPrefix()) |
| Activation des providers | Services et load balancers |
| Logs, métriques, tracing | Middlewares (auth, headers, rate limit) |
| Résolveurs ACME | Certificats et options TLS |
Le statique se recharge uniquement au redémarrage de Traefik. Le dynamique se recharge à chaud, sans couper une seule connexion en cours.
Dans le docker-compose.yml ci-dessus, tout ce qui est en command: est statique, et tout ce qui est dans ./dynamic est dynamique. Si tu modifies un entrypoint, tu redémarres. Si tu ajoutes un middleware, tu attends deux secondes.
Publier un service avec quatre labels
Pas besoin de fichier YAML pour exposer une application. Quatre labels suffisent, et l'auto-découverte fait le reste.
services:
app:
image: ghcr.io/monorg/app:1.4.2
restart: unless-stopped
networks: [proxy]
labels:
- "traefik.enable=true"
- "traefik.http.routers.app.rule=Host(`app.example.com`)"
- "traefik.http.routers.app.entrypoints=websecure"
- "traefik.http.routers.app.tls.certresolver=le"
Le port est détecté automatiquement quand le conteneur n'en expose qu'un. Dès qu'il y en a plusieurs, Traefik prend le plus bas, ce qui n'est pas toujours celui que tu veux.
Dans ce cas, force-le : traefik.http.services.app.loadbalancer.server.port=3000. C'est le label que j'ajoute systématiquement sur les applications Node, parce qu'elles exposent souvent un port de debug en plus du port applicatif.
Autre piège : si le conteneur est branché sur deux réseaux, Traefik choisit au hasard. Ajoute traefik.docker.network=proxy pour figer le choix, sinon tu obtiens des 502 intermittents impossibles à reproduire.
TLS : ACME avec challenge DNS plutôt que HTTP
Le challenge HTTP-01 est le plus simple : il exige juste que le port 80 soit joignable. Le DNS-01 est plus robuste, parce qu'il fonctionne même quand le port 80 est fermé, et qu'il autorise les certificats wildcard.
certificatesResolvers:
le:
acme:
email: admin@example.com
storage: /acme/acme.json
caServer: https://acme-v02.api.letsencrypt.org/directory
dnsChallenge:
provider: ovh
resolvers:
- "1.1.1.1:53"
- "9.9.9.9:53"
Le fichier acme.json doit être en chmod 600, sinon Traefik refuse de démarrer avec une erreur explicite. Et il doit vivre sur un volume persistant : le perdre signifie redemander tous les certificats.
La 3.7 ajoute une option CertificateTimeout côté ACME. Utile quand ton provider DNS est lent à propager : tu allonges le délai au lieu de voir la demande échouer au bout de quelques minutes.
Si tu débutes sur les certificats, j'ai détaillé les coûts réels et les limites de renouvellement dans le vrai coût de Let's Encrypt. Et pour la partie performance pure — timeouts, ServersTransport, ordre des middlewares — le guide performance et scalabilité complète cet article sans le répéter.
Middlewares : l'ordre d'exécution n'est pas cosmétique
Un middleware de compression placé avant un middleware d'authentification compresse aussi les réponses 401. Ça ne casse rien, mais ça consomme du CPU pour des erreurs.
L'ordre se lit de gauche à droite dans le label, et c'est celui-là qui s'applique.
labels:
- "traefik.http.middlewares.sec.headers.stsSeconds=31536000"
- "traefik.http.middlewares.sec.headers.contentTypeNosniff=true"
- "traefik.http.middlewares.sec.headers.browserXssFilter=true"
- "traefik.http.middlewares.rl.ratelimit.average=50"
- "traefik.http.middlewares.rl.ratelimit.burst=100"
- "traefik.http.routers.app.middlewares=sec@docker,rl@docker"
Le suffixe @docker n'est pas décoratif. Depuis la v3, chaque provider a son espace de noms, et un middleware déclaré en fichier s'appelle avec @file.
Oublier le suffixe donne un message d'erreur clair dans les logs, mais seulement si tu as activé --log.level=INFO. En niveau WARN par défaut sur certaines images, l'erreur passe inaperçue.
Le dashboard : exposé, mais jamais nu
Le dashboard est pratique pour vérifier en un coup d'œil quels routeurs sont actifs. Il expose aussi toute ta topologie interne, y compris les noms de services et les règles de routage.
labels:
- "traefik.enable=true"
- "traefik.http.routers.dash.rule=Host(`traefik.example.com`)"
- "traefik.http.routers.dash.entrypoints=websecure"
- "traefik.http.routers.dash.tls.certresolver=le"
- "traefik.http.routers.dash.service=api@internal"
- "traefik.http.routers.dash.middlewares=auth@docker"
- "traefik.http.middlewares.auth.basicauth.users=admin:$$apr1$$..."
Le double $$ est obligatoire dans un compose : Docker interprète un $ simple comme une variable d'environnement et tronque le hash.
Alternative plus propre : ne pas exposer le dashboard du tout. Un tunnel SSH vers le port 8080 fait le même travail sans ajouter de surface d'attaque.
Ce que la 3.7 apporte vraiment
La grosse nouveauté est un provider ingress-nginx. Il lit les annotations NGINX existantes et les traduit en configuration dynamique Traefik.
Pour ceux qui migrent de l'ingress controller NGINX, archivé en mars 2026, c'est la voie la plus courte : tu changes une classe d'ingress et tes annotations continuent de fonctionner.
Le reste est plus discret mais utile au quotidien. La 3.7 apporte une configuration de précédence entre providers, les hosts wildcard dans les matchers Host() et HostSNI(), et un menu certificats dans l'interface web.
La précédence entre providers règle un vieux problème : quand un routeur venait d'un fichier et un autre de Docker avec la même règle, l'arbitrage était implicite. Maintenant tu le déclares. Le détail des changements est dans les notes de release 3.7.0.
Diagnostiquer en cinq commandes
Quand un domaine renvoie 404, la cause est presque toujours dans l'un de ces cinq contrôles.
docker logs traefik --tail 50: les erreurs de provider et de parsing de labels.curl -I https://app.example.com: vérifie le code et l'en-têteServer.curl -s http://127.0.0.1:8080/api/http/routers | jq '.[].name': la liste réelle des routeurs chargés.docker inspect app | jq '.[0].NetworkSettings.Networks': le réseau effectif du conteneur.openssl s_client -connect app.example.com:443 -servername app.example.com: le certificat réellement servi.
Le troisième est le plus sous-estimé. Si ton routeur n'apparaît pas dans l'API, le problème est en amont du routage : label mal orthographié, conteneur sur un autre réseau, ou traefik.enable absent.
Un 404 qui vient de Traefik lui-même contient la mention « router not found » dans le corps de la réponse. Un 404 qui vient de ton application n'a pas cette mention. Ce seul détail divise le temps de diagnostic par deux.
FAQ
Faut-il migrer de la 2.11 vers la 3.7 directement ?
Oui, la migration se fait en un saut. Les breaking changes concernent surtout les providers Kubernetes et la syntaxe des matchers, pas les configurations Docker classiques.
Traefik peut-il remplacer un load balancer matériel ?
Pour du HTTP avec quelques dizaines de milliers de requêtes par minute, oui. Au-delà, la question n'est plus le logiciel mais la sortie réseau de ta machine.
Comment éviter de redémarrer Traefik à chaque changement ?
Mets tout ce qui change souvent dans le provider fichier ou dans les labels Docker. Seuls les entrypoints et les providers exigent un redémarrage.
Le socket Docker en lecture seule suffit-il ?
Pour découvrir les conteneurs, oui. Si tu utilises le provider Swarm ou des fonctionnalités qui écrivent dans l'API Docker, non.
La checklist avant de mettre en prod
Version 3.7 épinglée, socket en :ro, exposedbydefault=false, redirection HTTP→HTTPS sur l'entrypoint, acme.json en 600 sur un volume persistant, dashboard derrière une authentification ou fermé, et --log.level=INFO activé le temps de la mise en route.
Sept lignes à vérifier, et tu évites les six erreurs qui reviennent dans tous les fils d'entraide. Installe la 3.7, garde ta configuration statique courte, et laisse le dynamique faire le travail.