Installer Traefik v3 : binaire, Docker et package manager

Ce guide vous accompagne dans l'installation de Traefik v3.7.6 sur Linux. Vous apprendrez à déployer Traefik via binaire, Docker ou package manager, puis à configurer les options de base (entrypoints, providers, dashboard). À la fin, vous aurez un Traefik fonctionnel prêt à router du trafic vers vos services.

Temps estimé : 15-20 minutes selon la méthode choisie.

Prérequis

Vérifiez ces points avant de commencer : un manque à ce stade se manifeste bien plus tard, sous la forme d'une erreur qui ne le désigne pas.

Système

Traefik est un binaire Go statique sans dépendance externe, ce qui explique des besoins matériels modestes. La consommation réelle dépend surtout du nombre de routes et du volume de journaux conservés, pas du trafic lui-même.

Critère	Minimum	Recommandé
Linux	Kernel 3.10+	Kernel 5.x+
RAM	128 Mo	256 Mo+
Espace disque	50 Mo	100 Mo (avec logs)
Architecture	amd64, arm64	amd64

Traefik fonctionne également sur Windows et macOS, mais ce guide se concentre sur Linux.

Ports réseau

Traefik utilise plusieurs ports selon votre configuration :

Port	Usage	Configuration
80	HTTP (entrypoint web)	Ouvert vers Internet
443	HTTPS (entrypoint websecure)	Ouvert vers Internet
8080	Dashboard et API	Interne uniquement

Vérifiez que ces ports sont disponibles :

# Vérifier les ports utilisés
ss -tlnp | grep -E ':80|:443|:8080'

Si un port est déjà utilisé, vous devrez arrêter le service concerné ou changer le port Traefik.

Connaissances recommandées

Avant de commencer, assurez-vous de comprendre :

Les concepts de base de Traefik (voir Introduction à Traefik)
La ligne de commande Linux
Les bases de Docker (pour la méthode Docker)

Méthode 1 : Installation binaire

Cette méthode vous donne un contrôle total sur Traefik. Idéale pour les serveurs bare-metal ou les VMs sans Docker.

Télécharger le binaire

Récupérez la dernière version depuis GitHub :

Téléchargez l'archive et le fichier de sommes de contrôle publié par le projet, puis vérifiez l'empreinte avant toute extraction : c'est la seule façon de détecter une archive tronquée ou substituée.

# Définir la version (vérifiez la dernière sur github.com/traefik/traefik/releases)
TRAEFIK_VERSION="v3.7.6"

# Télécharger le binaire pour Linux amd64
wget https://github.com/traefik/traefik/releases/download/${TRAEFIK_VERSION}/traefik_${TRAEFIK_VERSION}_linux_amd64.tar.gz

# Vérifier le checksum avant d'extraire quoi que ce soit
wget https://github.com/traefik/traefik/releases/download/${TRAEFIK_VERSION}/traefik_${TRAEFIK_VERSION}_checksums.txt
sha256sum -c traefik_${TRAEFIK_VERSION}_checksums.txt --ignore-missing

L'option --ignore-missing limite le contrôle aux fichiers réellement téléchargés, le fichier de sommes couvrant toutes les architectures. Sans OK en sortie, n'allez pas plus loin.

Résultat attendu :

traefik_v3.7.6_linux_amd64.tar.gz: OK

Installer le binaire

Extrayez et placez le binaire dans le PATH système :

# Extraire l'archive
tar xzf traefik_${TRAEFIK_VERSION}_linux_amd64.tar.gz

# Déplacer vers /usr/local/bin
sudo mv traefik /usr/local/bin/

# Vérifier l'installation
traefik version

Résultat attendu :

Version:      3.7.6
Codename:     langres
Go version:   go1.25.11
Built:        2026-06-30T12:14:07Z
OS/Arch:      linux/amd64

Créer la structure de répertoires

Le compte traefik est créé sans shell de connexion (/sbin/nologin) et sans répertoire personnel : il ne sert qu'à faire tourner le service, ce qui limite les dégâts en cas de compromission du processus.

# Créer les répertoires de configuration
sudo mkdir -p /etc/traefik/conf.d
sudo mkdir -p /var/log/traefik

# Créer un utilisateur dédié (sécurité)
sudo useradd -r -s /sbin/nologin traefik

# Attribuer les permissions
sudo chown -R traefik:traefik /etc/traefik
sudo chown -R traefik:traefik /var/log/traefik

Créer le fichier de configuration

Créez /etc/traefik/traefik.yaml avec la configuration minimale :

# Configuration statique de Traefik

# Points d'entrée réseau
entryPoints:
  web:
    address: ":80"
  websecure:
    address: ":443"

# Dashboard et API (attention : sécuriser en production !)
api:
  dashboard: true
  insecure: true  # À désactiver en production

# Providers de configuration dynamique
providers:
  file:
    directory: /etc/traefik/conf.d
    watch: true

# Logging
log:
  level: INFO
  filePath: /var/log/traefik/traefik.log

accessLog:
  filePath: /var/log/traefik/access.log

Créer le service systemd

Deux directives portent l'essentiel du durcissement. ProtectSystem=strict monte tout le système de fichiers en lecture seule, d'où la nécessité de lister explicitement les répertoires inscriptibles dans ReadWritePaths. AmbientCapabilities=CAP_NET_BIND_SERVICE autorise l'écoute sur les ports 80 et 443 sans lancer le processus en root : sans cette ligne, le service échoue au démarrage avec une erreur de permission.

Créez /etc/systemd/system/traefik.service :

[Unit]
Description=Traefik Reverse Proxy
Documentation=https://doc.traefik.io/traefik/
After=network-online.target
Wants=network-online.target

[Service]
Type=notify
User=traefik
Group=traefik
ExecStart=/usr/local/bin/traefik --configFile=/etc/traefik/traefik.yaml
ExecReload=/bin/kill -USR1 $MAINPID
Restart=on-failure
RestartSec=5
LimitNOFILE=65536

# Sécurité
NoNewPrivileges=true
ProtectSystem=strict
ProtectHome=true
ReadWritePaths=/var/log/traefik /etc/traefik
PrivateTmp=true

# Capability pour les ports < 1024
AmbientCapabilities=CAP_NET_BIND_SERVICE

[Install]
WantedBy=multi-user.target

Démarrer et vérifier

# Recharger systemd
sudo systemctl daemon-reload

# Activer le démarrage automatique
sudo systemctl enable traefik

# Démarrer le service
sudo systemctl start traefik

# Vérifier le statut
sudo systemctl status traefik

Résultat attendu :

● traefik.service - Traefik Reverse Proxy
     Loaded: loaded (/etc/systemd/system/traefik.service; enabled)
     Active: active (running) since ...

Testez l'accès au dashboard :

curl -s http://localhost:8080/api/overview | jq

Méthode 2 : Installation avec Docker

C'est la méthode la plus courante car Traefik est conçu pour les environnements conteneurisés. Le provider Docker lit directement la liste des conteneurs par la socket de l'hôte et construit les routes à partir de leurs labels, sans qu'aucun fichier de configuration ne soit à modifier lors d'un déploiement. En contrepartie, monter cette socket dans un conteneur revient à lui donner un accès privilégié à l'hôte : le montage en lecture seule et le durcissement du service sont ici des minimums.

Créer la structure de répertoires

Le fichier acme.json stockera les certificats et les clés privées obtenus auprès de Let's Encrypt. Traefik refuse de démarrer si ses permissions sont plus larges que 600, d'où le chmod dès la création.
Fenêtre de terminal
```
# Créer le répertoire du projet
mkdir -p ~/traefik-lab
cd ~/traefik-lab

# Créer les sous-répertoires
mkdir -p config/dynamic

# Créer le fichier pour les certificats ACME (Let's Encrypt)
touch acme.json
chmod 600 acme.json
```

Créer la configuration statique

Créez config/traefik.yaml :

# Configuration statique de Traefik

# Points d'entrée
entryPoints:
  web:
    address: ":80"
  websecure:
    address: ":443"

# API et Dashboard
api:
  dashboard: true
  insecure: true  # Pour les tests uniquement

# Provider Docker
providers:
  docker:
    endpoint: "unix:///var/run/docker.sock"
    exposedByDefault: false  # Expose uniquement les conteneurs avec label traefik.enable=true
    watch: true
  file:
    directory: /etc/traefik/dynamic
    watch: true

# Logging
log:
  level: INFO

accessLog: {}

Créer le fichier docker-compose.yml

Les deux fichiers de configuration sont montés en lecture seule, ce qui empêche le conteneur de modifier ce qui le pilote ; acme.json fait exception puisque Traefik doit y écrire les certificats. Sur un environnement de production, remplacez le tag v3.7.6 par le digest @sha256: de l'image, seul identifiant qui ne peut pas être réattribué à un autre contenu.

services:
  traefik:
    image: traefik:v3.7.6
    container_name: traefik
    restart: unless-stopped
    security_opt:
      - no-new-privileges:true
    ports:
      - "80:80"
      - "443:443"
      - "8080:8080"
    volumes:
      # Socket Docker (lecture seule)
      - /var/run/docker.sock:/var/run/docker.sock:ro
      # Configuration statique
      - ./config/traefik.yaml:/etc/traefik/traefik.yaml:ro
      # Configuration dynamique
      - ./config/dynamic:/etc/traefik/dynamic:ro
      # Certificats ACME
      - ./acme.json:/acme.json
    networks:
      - traefik-public

networks:
  traefik-public:
    name: traefik-public
    driver: bridge

Lancer Traefik

# Créer le réseau (si pas créé automatiquement)
docker network create traefik-public 2>/dev/null || true

# Lancer Traefik
docker compose up -d

# Vérifier le statut
docker compose ps

Résultat attendu :

NAME      IMAGE          COMMAND                  SERVICE   STATUS    PORTS
traefik   traefik:v3.7.6   "/entrypoint.sh trae…"   traefik   running   0.0.0.0:80->80/tcp, ...

Vérifier l'installation

# Vérifier les logs
docker compose logs traefik | tail -20

# Tester l'API
curl -s http://localhost:8080/api/overview | jq

# Accéder au dashboard
echo "Dashboard : http://localhost:8080/dashboard/"

Résultat attendu pour l'API :

{
  "http": {
    "routers": { "total": 0 },
    "services": { "total": 0 },
    "middlewares": { "total": 0 }
  },
  "tcp": { ... },
  "udp": { ... }
}

Tester avec un service whoami

Pour valider que Traefik route correctement le trafic, ajoutons un service de test. L'image whoami renvoie les en-têtes de la requête reçue, ce qui permet de vérifier d'un coup d'oeil que le trafic est bien passé par le proxy. Les quatre labels sont le minimum vital : activer l'exposition, définir la règle de correspondance, choisir l'entrypoint et indiquer le port d'écoute interne du conteneur. Comme pour l'image de Traefik, épinglez cette image par digest hors contexte de test.

# Ajoutez à docker-compose.yml
  whoami:
    image: traefik/whoami:v1.11.0
    container_name: whoami
    labels:
      - "traefik.enable=true"
      - "traefik.http.routers.whoami.rule=Host(`whoami.localhost`)"
      - "traefik.http.routers.whoami.entrypoints=web"
      - "traefik.http.services.whoami.loadbalancer.server.port=80"
    networks:
      - traefik-public

Redémarrez et testez :

docker compose up -d
curl -H "Host: whoami.localhost" http://localhost

Résultat attendu :

Hostname: whoami
IP: 172.18.0.3
RemoteAddr: 172.18.0.2:54312
GET / HTTP/1.1
Host: whoami.localhost
...

Méthode 3 : Package manager (optionnel)

Certaines distributions proposent Traefik dans leurs dépôts, mais les versions sont souvent anciennes. Le décalage est problématique sur un composant exposé en frontal : un retard de plusieurs versions mineures signifie autant de correctifs de sécurité manquants. Sur Linux, préférez le binaire ou l'image officielle, cette section n'existe que pour les cas où la politique interne impose de passer par le gestionnaire de paquets.

Debian/Ubuntu (via dépôt tiers)

Traefik n'est pas dans les dépôts officiels Debian/Ubuntu. Utilisez le binaire ou Docker.

RHEL/Rocky/Alma (via binaire)

Même recommandation : utilisez le binaire téléchargé manuellement.

Homebrew (macOS pour développement)

Sur macOS, Homebrew reste pratique pour disposer de la commande traefik en local, le temps de mettre au point une configuration. Vérifiez la version obtenue, elle ne correspond pas nécessairement à celle déployée sur vos serveurs.

brew install traefik
traefik version

Structure des fichiers de configuration

Traefik distingue deux configurations qu'il ne faut jamais confondre. La configuration statique est lue une seule fois au démarrage : elle définit les ports d'écoute, les sources de configuration et les résolveurs de certificats, et toute modification impose un redémarrage. La configuration dynamique décrit les routes et est rechargée à chaud, sans coupure de service. Confondre les deux est l'erreur la plus fréquente en début de parcours, une option placée au mauvais endroit étant simplement ignorée.

Vue d'ensemble

L'arborescence ci-dessous matérialise cette séparation : un fichier unique pour le statique, un répertoire surveillé pour le dynamique. Le découpage du répertoire conf.d/ en plusieurs fichiers n'a aucune incidence technique, Traefik fusionne leur contenu.

/etc/traefik/
├── traefik.yaml          # Configuration statique (démarrage)
└── conf.d/               # Configuration dynamique (hot-reload)
    ├── routers.yaml
    ├── services.yaml
    └── middlewares.yaml

Configuration statique complète

Voici un exemple de traefik.yaml avec les options principales :

# =============================================================================
# ENTRYPOINTS - Ports d'écoute
# =============================================================================
entryPoints:
  web:
    address: ":80"
    http:
      redirections:
        entryPoint:
          to: websecure
          scheme: https

  websecure:
    address: ":443"
    http:
      tls:
        certResolver: letsencrypt

  metrics:
    address: ":8082"

# =============================================================================
# PROVIDERS - Sources de configuration dynamique
# =============================================================================
providers:
  docker:
    endpoint: "unix:///var/run/docker.sock"
    exposedByDefault: false
    network: traefik-public

  file:
    directory: /etc/traefik/conf.d
    watch: true

# =============================================================================
# API ET DASHBOARD
# =============================================================================
api:
  dashboard: true
  # insecure: false  # En production, désactiver et sécuriser

# =============================================================================
# CERTIFICATS ACME (Let's Encrypt)
# =============================================================================
certificatesResolvers:
  letsencrypt:
    acme:
      email: admin@example.com
      storage: /etc/traefik/acme.json
      httpChallenge:
        entryPoint: web

# =============================================================================
# LOGGING
# =============================================================================
log:
  level: INFO
  filePath: /var/log/traefik/traefik.log
  format: json

accessLog:
  filePath: /var/log/traefik/access.log
  format: json
  filters:
    statusCodes:
      - "400-599"
  fields:
    headers:
      names:
        User-Agent: keep
        Authorization: drop

# =============================================================================
# METRIQUES (Prometheus)
# =============================================================================
metrics:
  prometheus:
    entryPoint: metrics
    addServicesLabels: true
    addRoutersLabels: true

Formats de configuration supportés

Traefik accepte plusieurs formats pour la configuration statique, tous strictement équivalents en termes de fonctionnalités. Le choix se fait selon le contexte de déploiement : un fichier YAML ou TOML se versionne et se relit facilement, tandis que les arguments CLI et les variables d'environnement conviennent aux orchestrateurs où la configuration est injectée au lancement. Le nom des options suit toujours la même hiérarchie, seule la notation change.

entryPoints:
  web:
    address: ":80"
  websecure:
    address: ":443"

api:
  dashboard: true

providers:
  docker:
    exposedByDefault: false

[entryPoints]
  [entryPoints.web]
    address = ":80"
  [entryPoints.websecure]
    address = ":443"

[api]
  dashboard = true

[providers]
  [providers.docker]
    exposedByDefault = false

traefik \
  --entrypoints.web.address=:80 \
  --entrypoints.websecure.address=:443 \
  --api.dashboard=true \
  --providers.docker.exposedByDefault=false

export TRAEFIK_ENTRYPOINTS_WEB_ADDRESS=":80"
export TRAEFIK_ENTRYPOINTS_WEBSECURE_ADDRESS=":443"
export TRAEFIK_API_DASHBOARD="true"
export TRAEFIK_PROVIDERS_DOCKER_EXPOSEDBYDEFAULT="false"

traefik

Accéder au Dashboard

Le dashboard Traefik affiche en temps réel :

Les routers actifs et leurs règles
Les services backend et leur état
Les middlewares configurés
Les entrypoints et le trafic

Accès local (mode insecure)

Le mode insecure publie le dashboard et l'API d'administration sur le port 8080 sans aucune authentification. Réservez-le à une machine de développement et ne laissez jamais ce port joignable depuis l'extérieur : l'API expose l'intégralité de la configuration, noms d'hôtes et adresses internes compris.

# Accès direct
http://localhost:8080/dashboard/

# Via curl
curl http://localhost:8080/api/overview

Sécuriser l'accès (production)

En production, on désactive le mode insecure et on expose le dashboard comme n'importe quel autre service : par un router déclaré en configuration dynamique, protégé par un middleware d'authentification et servi en HTTPS. Le service interne à cibler s'appelle api@internal, c'est le nom réservé que Traefik donne à sa propre API.

Créez un fichier de configuration dynamique pour sécuriser le dashboard :

http:
  routers:
    dashboard:
      rule: "Host(`traefik.example.com`) && (PathPrefix(`/dashboard`) || PathPrefix(`/api`))"
      service: api@internal
      entryPoints:
        - websecure
      middlewares:
        - dashboard-auth
      tls:
        certResolver: letsencrypt

  middlewares:
    dashboard-auth:
      basicAuth:
        users:
          # admin:password (généré avec htpasswd -nb admin password)
          - "admin:$apr1$ruca84Hq$mbjdMZBAG.KWn7vfN/SNK/"

Générez le hash du mot de passe :

# Installer htpasswd si nécessaire
sudo apt install apache2-utils  # Debian/Ubuntu
# ou
sudo dnf install httpd-tools    # RHEL/Rocky

# Générer le hash
htpasswd -nb admin VotreMotDePasse

Valider l'installation

Un service démarré ne prouve pas qu'il fonctionne : Traefik se lance sans erreur même quand aucun provider ne lui remonte de configuration. Trois contrôles se complètent, la lecture des journaux au démarrage, l'interrogation de l'API pour compter les routes chargées, puis un appel réel à travers le proxy. Menez-les dans cet ordre, une erreur de configuration apparaissant toujours en premier dans les journaux.

Vérifier les logs

Au démarrage, Traefik indique la version lancée et les providers activés. Les messages de niveau ERROR répétés en boucle signalent presque toujours un fichier de configuration dynamique invalide, que le proxy relit à chaque modification détectée.

# Binaire avec systemd
sudo journalctl -u traefik -f

# Docker
docker compose logs -f traefik

# Rechercher des erreurs
docker compose logs traefik 2>&1 | grep -i error

Tester avec curl

Ces requêtes interrogent l'API d'administration et renvoient du JSON, que jq met en forme. Un compteur de routers à zéro alors que des conteneurs tournent oriente vers le label traefik.enable=true manquant, conséquence directe du réglage exposedByDefault: false.

# API overview
curl -s http://localhost:8080/api/overview | jq

# Liste des routers HTTP
curl -s http://localhost:8080/api/http/routers | jq

# Liste des services
curl -s http://localhost:8080/api/http/services | jq

# Santé du service
curl -s http://localhost:8080/ping

Endpoints API utiles

Ces routes sont servies par l'API interne, donc soumises à la même protection que le dashboard. Une exception mérite d'être connue : /ping n'est disponible que si l'option ping figure dans la configuration statique, sans quoi la requête renvoie une erreur alors même que Traefik fonctionne. C'est cet endpoint que vous brancherez sur une sonde de disponibilité.

Endpoint	Description
`/api/overview`	Vue d'ensemble des ressources
`/api/http/routers`	Liste des routers HTTP
`/api/http/services`	Liste des services HTTP
`/api/http/middlewares`	Liste des middlewares
`/api/entrypoints`	Configuration des entrypoints
`/ping`	Health check simple

Dépannage

Les incidents rencontrés à l'installation se répartissent en quatre familles : un port occupé, un accès refusé à la socket Docker, un dashboard injoignable et une configuration invalide. Les trois premières se diagnostiquent depuis le système hôte, la dernière depuis les journaux de Traefik.

Port déjà utilisé

Sur un serveur qui a déjà hébergé un site, un serveur web occupe souvent le port 80. Traefik s'arrête immédiatement dans ce cas, sans démarrer partiellement.

Symptôme : Erreur "bind: address already in use"

# Identifier le processus utilisant le port
sudo ss -tlnp | grep :80
# ou
sudo lsof -i :80

# Arrêter le service concurrent
sudo systemctl stop nginx  # ou apache2

Permissions Docker socket

La socket appartient au groupe docker et n'est lisible que par ses membres. Ajouter le compte de service à ce groupe résout le problème mais lui confère de fait des privilèges équivalents à root sur l'hôte, d'où la seconde solution proposée.

Symptôme : Erreur "permission denied" sur /var/run/docker.sock

# Vérifier les permissions
ls -la /var/run/docker.sock

# Solution 1 : Ajouter l'utilisateur au groupe docker
sudo usermod -aG docker traefik
sudo systemctl restart traefik

# Solution 2 : Utiliser un proxy socket sécurisé (recommandé en production)
# Voir : https://github.com/Tecnativa/docker-socket-proxy

Dashboard inaccessible

Trois causes se succèdent dans l'ordre où le trafic les rencontre : l'API n'est pas activée, le port n'est pas publié par le conteneur, ou le pare-feu de l'hôte bloque la connexion. Vérifiez-les dans cet ordre plutôt qu'au hasard.

Symptôme : "Connection refused" sur le port 8080

Vérifiez que l'API est activée :
```
api:
  dashboard: true
  insecure: true
```
Vérifiez que le port est exposé (Docker) :
```
ports:
  - "8080:8080"
```

Vérifiez le pare-feu :

sudo ufw status
sudo firewall-cmd --list-all

Erreurs de configuration

Lancer Traefik au premier plan avec le niveau de journalisation DEBUG affiche l'erreur exacte, souvent tronquée dans le journal du service. Beaucoup de messages proviennent d'options héritées de la version 2, dont plusieurs noms ont changé en v3.

Symptôme : Traefik ne démarre pas

# Valider la syntaxe YAML
yamllint /etc/traefik/traefik.yaml

# Tester la configuration sans démarrer
traefik --configFile=/etc/traefik/traefik.yaml --log.level=DEBUG 2>&1 | head -50

Erreur courante	Solution
`yaml: unmarshal errors`	Vérifier l'indentation YAML
`field not found`	Vérifier le nom des options (v3 vs v2)
`invalid port`	Format correct : `":80"` avec les guillemets

À retenir

3 méthodes d'installation : binaire (contrôle total), Docker (recommandé), package manager (versions souvent anciennes)
Configuration statique : définit entrypoints, providers et options de démarrage, ne change qu'au redémarrage
Configuration dynamique : définit routers, services et middlewares, hot-reload en temps réel
exposedByDefault: false : bonne pratique de sécurité qui force l'ajout explicite de traefik.enable=true
Dashboard : toujours sécuriser avec authentification en production
Réseau traefik-public : réseau Docker dédié pour la communication entre Traefik et les services
Logs : activer les access logs en JSON pour faciliter l'analyse

Prochaines étapes

Traefik avec Docker Exposer vos conteneurs automatiquement

Les middlewares Traefik Transformations et sécurité