Déployer vos applications avec Traefik sur un VPS

Pourquoi placer Traefik en frontal de votre VPS ?

Ce que Traefik apporte concrètement sur un VPS

• Découverte automatique des conteneurs Docker via le provider Docker (les routes apparaissent sans redémarrage)
• Certificats SSL Let's Encrypt générés et renouvelés automatiquement (challenges HTTP-01, TLS-ALPN-01 ou DNS-01), renouvelés par défaut 30 jours avant leur expiration
• Routage par domaine, par chemin ou par en-tête, géré entièrement via les labels Docker
• Dashboard web intégré pour visualiser routers, services et middlewares en temps réel
• Middlewares prêts à l'emploi : redirection HTTPS, basic auth, rate limiting, headers de sécurité, compression
• Load balancing automatique quand vous scalez un service à plusieurs réplicas
• HTTP/3 (QUIC) activable sur un entrypoint en une option
• D'autres providers que Docker (Swarm, Kubernetes, Nomad, fichiers) si votre infrastructure grandit

Prérequis

Déployer Traefik avec Docker Compose

1. 01

   Créer le réseau et l'arborescence

   Créez un réseau Docker partagé que Traefik et vos applications utiliseront, puis un dossier dédié contenant le fichier acme.json (le stockage des certificats et de leurs clés privées) :

   docker network create proxy
   mkdir -p /opt/traefik && cd /opt/traefik
   touch acme.json && chmod 600 acme.json

   Créez le fichier avant le premier démarrage : si le chemin monté n'existe pas, Docker crée un dossier à sa place et Traefik ne peut plus y écrire. Les droits 600 sont exigés : Traefik refuse un fichier lisible par d'autres utilisateurs.

2. 02

   Configurer les entrypoints et le résolveur ACME

   Placez ce fichier dans /opt/traefik/docker-compose.yml. Il déclare deux entrypoints (web sur :80, websecure sur :443), un certificateResolver Let's Encrypt validé par le challenge HTTP, la découverte des conteneurs par le socket Docker monté en lecture seule, et le dashboard :

   services:
     traefik:
       image: traefik:v3.7
       container_name: traefik
       restart: unless-stopped
       ports:
         - "80:80"
         - "443:443"
         - "443:443/udp"
       command:
         - "--providers.docker=true"
         - "--providers.docker.exposedbydefault=false"
         - "--providers.docker.network=proxy"
         - "--entrypoints.web.address=:80"
         - "--entrypoints.web.http.redirections.entrypoint.to=websecure"
         - "--entrypoints.web.http.redirections.entrypoint.scheme=https"
         - "--entrypoints.websecure.address=:443"
         - "--entrypoints.websecure.http3=true"
         - "[email protected]"
         - "--certificatesresolvers.letsencrypt.acme.storage=/acme.json"
         - "--certificatesresolvers.letsencrypt.acme.httpchallenge.entrypoint=web"
         - "--api.dashboard=true"
       volumes:
         - "/var/run/docker.sock:/var/run/docker.sock:ro"
         - "./acme.json:/acme.json"
       networks:
         - proxy
       labels:
         - "traefik.enable=true"
         - "traefik.http.routers.dashboard.rule=Host(`traefik.example.com`)"
         - "traefik.http.routers.dashboard.entrypoints=websecure"
         - "traefik.http.routers.dashboard.tls.certresolver=letsencrypt"
         - "traefik.http.routers.dashboard.service=api@internal"
         - "traefik.http.routers.dashboard.middlewares=dashboard-auth"
         - "traefik.http.middlewares.dashboard-auth.basicauth.users=admin:$$2y$$05$$REMPLACER_PAR_LE_HASH"
   
   networks:
     proxy:
       external: true

   L'option exposedbydefault=false est essentielle : sans elle, chaque conteneur du VPS serait publié, y compris votre base de données. Épinglez la branche (v3.7) plutôt que latest, et suivez les releases avant de changer de version mineure.

3. 03

   Forcer la redirection HTTP vers HTTPS

   La redirection se déclare directement sur l'entrypoint web, avec les deux options --entrypoints.web.http.redirections.entrypoint.to=websecure et ...entrypoint.scheme=https déjà présentes dans le fichier ci-dessus. C'est plus simple et plus sûr qu'un router « catch-all » avec middleware : tout trafic en clair est basculé en HTTPS par une redirection permanente, sans label à répéter sur chaque service, et le challenge HTTP de Let's Encrypt continue de passer sur le port 80.

4. 04

   Sécuriser le dashboard

   Le dashboard est exposé sur traefik.example.com, derrière le middleware basicauth nommé dashboard-auth. Générez un hash bcrypt (paquet apache2-utils sous Debian/Ubuntu) en doublant les $, comme l'exige une valeur de label dans un fichier Compose :

   apt install -y apache2-utils
   htpasswd -nB admin | sed -e 's/\$/\$\$/g'

   Collez le résultat à la place de admin:$$2y$$05$$REMPLACER_PAR_LE_HASH. Un hash collé avec des $ simples est interprété par Compose comme des variables et casse l'authentification. Ne laissez jamais le flag --api.insecure=true en production : il publie le dashboard sans authentification.

5. 05

   Lancer Traefik

   Démarrez la stack et suivez les logs :

   cd /opt/traefik
   docker compose up -d
   docker compose logs -f traefik

   Vous devez voir le provider Docker démarrer, puis le router dashboard s'attacher, sans erreur ACME. Pendant vos essais, ajoutez temporairement --certificatesresolvers.letsencrypt.acme.caserver=https://acme-staging-v02.api.letsencrypt.org/directory : le serveur staging de Let's Encrypt délivre des certificats non reconnus par les navigateurs, mais vous protège du rate limit de production si une configuration échoue en boucle. Retirez l'option et videz acme.json avant le passage en production.

6. 06

   Connecter une application

   Chaque application vit dans son propre docker-compose.yml, rattachée au réseau proxy et décrite par ses labels :

   services:
     app:
       image: ghcr.io/example/app:1.0.0
       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=letsencrypt"
         - "traefik.http.services.app.loadbalancer.server.port=3000"
   
   networks:
     proxy:
       external: true

   Au docker compose up -d, Traefik détecte le conteneur, obtient le certificat et active la route en quelques secondes, sans toucher à sa propre configuration. Le label loadbalancer.server.port indique le port interne de l'application ; il devient indispensable dès que l'image en expose plusieurs. Le nom du router (app ici) doit être unique sur tout le VPS.

7. 07

   Vérifier le certificat et la redirection

   Contrôlez depuis une machine extérieure au VPS :

   curl -I http://app.example.com
   curl -I https://app.example.com
   dig +short app.example.com

   La première requête doit renvoyer une redirection permanente vers https://, la deuxième un 200 (ou le code de votre application) servi avec un certificat Let's Encrypt valide, et dig doit afficher l'IP du VPS. Le dashboard liste aussi chaque router avec son résolveur de certificat. Un port 80 qui refuse la connexion pointe presque toujours vers le pare-feu.

Middlewares utiles en production

Cinq middlewares à connaître

• BasicAuth sur un outil d'administration (Adminer, Flower…) : traefik.http.middlewares.adminauth.basicauth.users=admin:$$2y$$05$$..., puis traefik.http.routers.monadmin.middlewares=adminauth. Même règle de $ doublés que pour le dashboard.
• Rate limit devant une API ou un formulaire : traefik.http.middlewares.ratelimit.ratelimit.average=100, ...ratelimit.period=1s et ...ratelimit.burst=200 autorisent 100 requêtes par seconde en moyenne, avec des rafales jusqu'à 200. Sans average, la limite est désactivée.
• Headers de sécurité : le middleware headers pose HSTS (stsSeconds=31536000, stsIncludeSubdomains=true), X-Frame-Options: DENY (frameDeny=true) et X-Content-Type-Options: nosniff (contentTypeNosniff=true), sans fichier de configuration séparé.
• Redirection www vers le domaine nu : redirectregex avec regex=^https://www\.(.+), replacement=https://$${1} et permanent=true. Pensez à déclarer les deux hôtes dans la règle du router pour que le certificat couvre www.
• Compression : traefik.http.middlewares.compress.compress=true active gzip, Brotli et Zstandard selon ce qu'accepte le navigateur, sans réglage côté application.

Activer HTTP/3 (QUIC)

Venir de Traefik v2 : ce qui casse

Changements cassants de la v3

• Swarm : l'option swarmMode du provider Docker n'existe plus et bloque le démarrage. Docker Swarm a désormais son propre provider (--providers.swarm).
• Règles de routage : Headers et HeadersRegexp deviennent Header et HeaderRegexp, HostHeader disparaît au profit de Host, et la plupart des matchers n'acceptent plus qu'une valeur.
• Chemins : Path et PathPrefix ne lisent plus d'expression régulière ni de placeholder comme {id} ; une telle route ne correspond plus à rien. Passez à PathRegexp, qui suit la syntaxe regexp de Go, comme HostRegexp.
• Middlewares renommés ou allégés : IPWhiteList devient IPAllowList (mêmes options) ; le middleware headers perd sslRedirect, sslTemporaryRedirect, sslHost, sslForceHost et featurePolicy.
• Content-Type : Traefik ne devine plus le type d'une réponse que le backend n'a pas typée ; ajoutez le middleware ContentType si une application en dépend.
• Providers et observabilité retirés : Marathon, Rancher v1, Traefik Pilot et les métriques InfluxDB v1 empêchent le démarrage ; le tracing passe uniquement par OpenTelemetry (plus d'export direct vers Jaeger, Zipkin ou Datadog).

Traefik v3, Nginx ou Caddy devant vos conteneurs

Faites défiler le tableau

Dépannage : les erreurs les plus fréquentes

Symptômes et corrections

• Certificat non obtenu, erreur ACME unauthorized ou 403 dans les logs : Let's Encrypt n'atteint pas votre domaine. Vérifiez depuis l'extérieur que le port 80 répond (curl -I http://app.example.com) et que le DNS pointe sur le VPS (dig +short app.example.com). Derrière un CDN en mode proxy, préférez le dnsChallenge.
• permissions 644 for /acme.json are too open, please use 600 : le résolveur refuse le fichier. Corrigez avec chmod 600 /opt/traefik/acme.json puis redémarrez Traefik ; ce contrôle protège les clés privées qui y sont stockées.
• Route visible dans le dashboard mais 502 Bad Gateway : le conteneur n'est pas sur le réseau proxy, ou le port interne est faux. Vérifiez avec docker inspect <conteneur> (section Networks), ajoutez le réseau ou le label loadbalancer.server.port, puis recréez le conteneur. Sur un conteneur relié à plusieurs réseaux, le label traefik.docker.network=proxy lève l'ambiguïté.
• Labels ignorés, route absente du dashboard : il manque traefik.enable=true (obligatoire avec exposedbydefault=false), ou deux services déclarent le même nom de router. Les logs de Traefik signalent alors le conflit.
• BasicAuth qui refuse un bon mot de passe : les $ du hash ne sont pas doublés dans le docker-compose.yml. Dans un fichier Compose, chaque $ devient $$ ; dans un fichier de configuration dynamique YAML ou TOML, le hash se colle tel quel.

Prochaine étape : durcir la stack