Installer Traefik v3 : binaire, Docker et package manager

Ce guide vous accompagne dans l'installation de Traefik v3.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.

Quelle méthode choisir ?

• Docker : recommandé pour les environnements conteneurisés (la plus courante)
• Binaire : pour un contrôle total ou des serveurs sans Docker
• Package manager : pour une gestion simplifiée des mises à jour

Prérequis

Systè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

Glissez pour voir

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

Glissez pour voir

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.

1. Télécharger le binaire

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

   # Définir la version (vérifiez la dernière sur github.com/traefik/traefik/releases)
   TRAEFIK_VERSION="v3.6.7"
   
   # 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 (optionnel mais recommandé)
   wget https://github.com/traefik/traefik/releases/download/${TRAEFIK_VERSION}/traefik_${TRAEFIK_VERSION}_checksums.txt
   sha256sum -c traefik_${TRAEFIK_VERSION}_checksums.txt --ignore-missing

   Résultat attendu :

   traefik_v3.6.7_linux_amd64.tar.gz: OK

2. 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.6.7
   Codename:     comte
   Go version:   go1.23.6
   Built:        2026-01-14T13:21:13Z
   OS/Arch:      linux/amd64

3. Créer la structure de répertoires

   # 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

4. Créer le fichier de configuration

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

   /etc/traefik/traefik.yaml

   # 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

5. Créer le service systemd

   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

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

1. Créer la structure de répertoires

   # 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

2. Créer la configuration statique

   Créez config/traefik.yaml :

   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: {}

   exposedByDefault

   Mettre exposedByDefault: false est une bonne pratique de sécurité. Seuls les conteneurs avec le label traefik.enable=true seront exposés.

3. Créer le fichier docker-compose.yml

   docker-compose.yml

   services:
     traefik:
       image: traefik:v3.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

4. 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.6   "/entrypoint.sh trae…"   traefik   running   0.0.0.0:80->80/tcp, ...

5. 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 :

# Ajoutez à docker-compose.yml
  whoami:
    image: traefik/whoami
    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.

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)

brew install traefik
traefik version

Structure des fichiers de configuration

Vue d'ensemble

/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 :

/etc/traefik/traefik.yaml

# =============================================================================
# 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 :

YAML

traefik.yaml

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

api:
  dashboard: true

providers:
  docker:
    exposedByDefault: false

TOML

traefik.toml

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

[api]
  dashboard = true

[providers]
  [providers.docker]
    exposedByDefault = false

CLI

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

Env vars

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

traefik

Ordre de priorité

Les sources de configuration sont évaluées dans cet ordre (la première gagne) :

1. Arguments CLI
2. Variables d'environnement
3. Fichier de configuration

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)

Si api.insecure: true est configuré :

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

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

Sécuriser l'accès (production)

Ne jamais exposer le dashboard sans authentification

En production, toujours sécuriser le dashboard avec au minimum une authentification BasicAuth ou ForwardAuth.

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

/etc/traefik/conf.d/dashboard.yaml

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

Vérifier les logs

# 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

# 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

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

Glissez pour voir

Dépannage

Port déjà utilisé

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

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

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

1. Vérifiez que l'API est activée :

   api:
     dashboard: true
     insecure: true

2. Vérifiez que le port est exposé (Docker) :

   ports:
     - "8080:8080"

3. Vérifiez le pare-feu :

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

Erreurs de configuration

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

Glissez pour voir

À retenir

1. 3 méthodes d'installation : binaire (contrôle total), Docker (recommandé), package manager (versions souvent anciennes)

2. Configuration statique : définit entrypoints, providers et options de démarrage, ne change qu'au redémarrage

3. Configuration dynamique : définit routers, services et middlewares, hot-reload en temps réel

4. exposedByDefault: false : bonne pratique de sécurité qui force l'ajout explicite de traefik.enable=true

5. Dashboard : toujours sécuriser avec authentification en production

6. Réseau traefik-public : réseau Docker dédié pour la communication entre Traefik et les services

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

×

📖 Voir la documentation →