Vous hébergez plusieurs applications dans des conteneurs sur un seul VPS et vous voulez les exposer en HTTPS, chacune sur son sous-domaine, sans gérer les certificats à la main ? Caddy est un serveur web et reverse proxy qui obtient et renouvelle seul les certificats Let's Encrypt. Ce guide le déploie avec Docker Compose, écrit un Caddyfile multi-sous-domaines, relie les services par un réseau Docker partagé et ajoute en-têtes de sécurité et authentification basique.
Pourquoi Caddy pour un reverse proxy Docker
Un reverse proxy reçoit les requêtes du public sur les ports 80 et 443 et les transmet au bon service interne selon le nom de domaine. Il termine aussi le TLS : c'est lui qui présente le certificat. Caddy fait cela avec une configuration très courte, car le HTTPS est actif par défaut : dès qu'un bloc porte un nom de domaine public, Caddy demande et renouvelle le certificat via le protocole ACME, et redirige HTTP vers HTTPS.
Prérequis : un VPS Linux avec accès root (Ubuntu, Debian ou une autre distribution), Docker installé (voir installer Docker sur un VPS), et des enregistrements DNS de type A (et AAAA si vous avez de l'IPv6) qui pointent vers l'adresse IP publique du serveur pour chaque sous-domaine.
Vocabulaire : serveur web, domaine, hôte virtuel et pare-feu
Quelques notions reviennent tout au long de ce guide. Si l'une d'elles vous est déjà familière, passez à la section suivante.
- Serveur web : logiciel qui répond aux requêtes HTTP et HTTPS et renvoie des pages ou transmet les requêtes à une application.
- Domaine et sous-domaine : noms lisibles (exemple.fr, vault.exemple.fr) que le DNS relie à une adresse IP. Un enregistrement A relie un nom à une adresse IPv4, un enregistrement AAAA à une adresse IPv6.
- Adresse IP : identifiant numérique d'une machine sur le réseau. Le serveur qui héberge Caddy possède une adresse IP publique.
- Hôte virtuel (virtual host) : configuration qui permet à un même serveur de répondre à plusieurs noms de domaine. Chaque bloc du Caddyfile en est un.
- Alias : plusieurs noms de domaine pour un même site. Dans le Caddyfile, ils se listent séparés par des virgules avant l'accolade ouvrante.
- Pare-feu (firewall) : règles qui autorisent ou bloquent le trafic selon le port et la source.
- Log (journal) : trace écrite par un logiciel pour chacun de ses événements. C'est la première source d'information pour diagnostiquer un certificat qui ne s'émet pas.
- Paquet : unité logicielle installée par le gestionnaire de paquets de la distribution, comme apt sur Ubuntu et Debian.
Caddy, Nginx ou Traefik : comparatif
| Critère | Caddy | Nginx | Traefik |
|---|---|---|---|
| Certificats Let's Encrypt | Intégrés, automatiques | Via un outil externe comme Certbot | Intégrés (résolveur ACME à configurer) |
| Configuration | Caddyfile court | Fichiers de blocs server détaillés | Labels Docker ou fichiers dynamiques |
| Découverte des conteneurs | Manuelle (un bloc par service) | Manuelle | Automatique via le socket Docker |
| Courbe d'apprentissage | Faible | Moyenne | Plus élevée |
| Cas d'usage typique | Quelques services sur un VPS | Configurations fines, grand parc existant | Beaucoup de conteneurs changeants |
En pratique : Caddy convient très bien à un VPS qui héberge une poignée d'applications que vous déclarez vous-même. Si vous maîtrisez déjà Nginx, notre guide du reverse proxy Nginx reste valable, avec Certbot pour les certificats (voir Certbot et Let's Encrypt). Traefik prend l'avantage quand les conteneurs apparaissent et disparaissent souvent et que vous voulez que le routage suive sans toucher à un fichier. Il demande en échange d'exposer le socket Docker, ce qui mérite de la prudence.
Créer le réseau Docker partagé
Pour que Caddy joigne vos applications sans publier leurs ports sur l'hôte, tous les conteneurs concernés rejoignent un même réseau Docker. Sur ce type de réseau, Docker fournit la résolution DNS par nom de service : Caddy peut donc viser vaultwarden:80 plutôt qu'une adresse IP.
docker network create proxy
Le réseau est créé une fois, hors de tout fichier Compose, puis chaque projet le déclare comme external. Les applications et Caddy peuvent ainsi vivre dans des dossiers et des fichiers Compose séparés (voir Docker Compose sur un VPS Linux).
Le fichier Docker Compose de Caddy
Créez un dossier, par exemple /opt/caddy, avec ce compose.yaml :
services:
caddy:
image: caddy:2
container_name: caddy
restart: unless-stopped
ports:
- "80:80"
- "443:443"
- "443:443/udp"
volumes:
- ./Caddyfile:/etc/caddy/Caddyfile:ro
- caddy_data:/data
- caddy_config:/config
networks:
- proxy
volumes:
caddy_data:
caddy_config:
networks:
proxy:
external: true
Le port 80 sert à la validation HTTP-01 et à la redirection, le 443 en TCP au HTTPS, et le 443 en UDP à HTTP/3. Si votre pare-feu (firewall) filtre le trafic, autorisez ces ports (voir ouvrir des ports avec UFW). Le tag caddy:2 suit la branche 2.x ; pour des mises à jour maîtrisées, vous pouvez le remplacer par un tag de version précis.
Pourquoi les volumes /data et /config sont indispensables
La documentation officielle de l'image Docker est claire : /data et /config doivent être persistants.
/datacontient les certificats, les clés privées et le compte ACME. C'est l'état que Caddy ne peut pas reconstituer sans repasser par l'autorité de certification./configcontient la configuration JSON sauvegardée automatiquement par Caddy.
Sans ces volumes, chaque recréation du conteneur (mise à jour d'image, docker compose down, docker rm) efface les certificats. Au redémarrage, Caddy refait toutes les demandes. Or Let's Encrypt applique des limites de débit : d'après sa documentation, un même ensemble de noms ne peut obtenir que 5 certificats par période de 7 jours, et 5 échecs de validation par identifiant et par heure sont tolérés. Quand la limite est atteinte, vous restez sans certificat valide jusqu'à ce que la capacité se libère, et aucune dérogation n'existe pour la limite des certificats dupliqués.
Utilisez donc des volumes nommés (comme ci-dessus) ou des dossiers locaux, et incluez-les dans votre stratégie de sauvegarde. Les sauvegardes sont à mettre en place par vos soins : voir sauvegarder un VPS avec rsync. Ne supprimez jamais caddy_data par réflexe lors d'un nettoyage (attention à docker volume prune, voir nettoyer Docker).
Un Caddyfile pour plusieurs sous-domaines
Voici un Caddyfile, le fichier de configuration de Caddy, qui route trois services. Remplacez exemple.fr par votre domaine. Les noms de conteneurs et ports internes sont à adapter à vos fichiers Compose : vérifiez le port d'écoute réel de chaque application dans sa documentation.
{
email admin@exemple.fr
}
vault.exemple.fr {
reverse_proxy vaultwarden:80
}
photos.exemple.fr {
reverse_proxy immich-server:2283
}
n8n.exemple.fr {
reverse_proxy n8n:5678
}
Chaque bloc correspond à un hôte virtuel (virtual host), c'est-à-dire à un site : Caddy obtient un certificat pour chaque nom, sans autre directive. Le bloc d'options global en tête (entre accolades seules) accepte l'option email, utile pour recevoir les notifications de l'autorité de certification.
Lancez ensuite, en ligne de commande (avec sudo si vous n'êtes pas root) :
cd /opt/caddy
docker compose up -d
docker compose logs -f caddy
Dans les journaux, vous voyez les certificats être obtenus. Vérifiez le résultat depuis l'extérieur avec curl -I https://vault.exemple.fr ou inspectez la chaîne avec la méthode de vérifier un certificat TLS avec OpenSSL.
Tester avec l'environnement de test
Pour vos premiers essais, ou si vous modifiez beaucoup la configuration, pointez Caddy vers l'environnement de test de Let's Encrypt, dont les limites sont nettement plus larges :
{
email admin@exemple.fr
acme_ca https://acme-staging-v02.api.letsencrypt.org/directory
}
Les certificats de test ne sont pas reconnus par les navigateurs. Retirez la ligne acme_ca une fois le routage validé et rechargez la configuration.
Connecter Vaultwarden, Immich, n8n et les autres
Dans le fichier Compose de chaque application, retirez la section ports qui expose le service sur l'hôte et rattachez-le au réseau proxy. Exemple pour Vaultwarden :
services:
vaultwarden:
image: vaultwarden/server:latest
container_name: vaultwarden
restart: unless-stopped
volumes:
- ./data:/data
networks:
- proxy
networks:
proxy:
external: true
Le principe est identique pour Vaultwarden, Immich ou n8n : le conteneur rejoint le réseau, son nom devient l'hôte à utiliser dans reverse_proxy. Pour les applications composées de plusieurs conteneurs (Immich, par exemple), ne rattachez au réseau partagé que celui qui reçoit le trafic web, et laissez base de données et cache sur le réseau interne du projet.
Ne pas publier de port est aussi une question de sécurité : Docker gère ses propres règles réseau, et un port publié peut rester joignable même si votre pare-feu semble le bloquer. Un service uniquement présent sur le réseau Docker n'est atteignable que par Caddy.
Certaines applications demandent que vous leur indiquiez leur URL publique (variable de domaine ou d'URL externe) : renseignez-la en HTTPS, sinon les liens générés ou les WebSockets peuvent poser problème. Caddy gère les WebSockets nativement avec reverse_proxy.
Quelles applications peut-on router avec Caddy ?
Dans cette configuration, Caddy joue le rôle de reverse proxy HTTP : il route des requêtes web. Une application écrite en Python ou en PHP, une application Java déployée sur Tomcat, une API ou un tableau de bord passent donc derrière un bloc reverse_proxy, à condition d'écouter sur un port interne du réseau Docker.
En revanche, une base MySQL, un serveur FTP, un serveur SMTP ou un accès SSH ne parlent pas HTTP. Ne les placez pas derrière Caddy et ne publiez pas leurs ports pour les rendre joignables : gardez-les sur le réseau interne de leur projet, et n'ouvrez dans le pare-feu que les ports dont vous avez besoin.
Chaque conteneur consomme de la RAM. Plus vous ajoutez d'applications sur un même VPS, plus il faut surveiller la RAM et la charge du serveur, et dimensionner le serveur en conséquence.
Ajouter des en-têtes de sécurité
La directive header ajoute ou retire des en-têtes sur les réponses. Pour éviter de répéter le même bloc, définissez un extrait réutilisable avec (nom) et appelez-le avec import :
(securite) {
header {
Strict-Transport-Security "max-age=31536000; includeSubDomains"
X-Content-Type-Options "nosniff"
X-Frame-Options "SAMEORIGIN"
Referrer-Policy "strict-origin-when-cross-origin"
-Server
}
}
vault.exemple.fr {
import securite
reverse_proxy vaultwarden:80
}
- Strict-Transport-Security (HSTS) demande au navigateur de n'utiliser que HTTPS pour ce domaine. N'activez
includeSubDomainsque si tous vos sous-domaines sont servis en HTTPS. - X-Content-Type-Options empêche le navigateur de deviner le type d'un fichier.
- X-Frame-Options limite l'intégration de la page dans une iframe, contre le clickjacking.
- Referrer-Policy réduit les informations d'origine transmises aux autres sites.
-Serverretire l'en-têteServerde la réponse.
Testez avant de généraliser : certaines applications définissent déjà leurs propres en-têtes, et une règle trop stricte peut casser une interface. Une politique Content-Security-Policy doit être adaptée application par application, ne l'appliquez pas globalement sans essais.
Protéger un service par authentification basique
Pour un outil sans authentification intégrée (tableau de bord, interface d'administration), la directive basic_auth demande un identifiant et un mot de passe. Caddy n'accepte pas les mots de passe en clair : il faut fournir un hachage (bcrypt par défaut). Générez-le avec la commande intégrée :
docker compose exec caddy caddy hash-password
La commande demande le mot de passe puis affiche le hachage. Utilisez-le dans le Caddyfile :
outils.exemple.fr {
basic_auth {
admin $2a$14$REMPLACEZ_PAR_VOTRE_HACHAGE
}
reverse_proxy tableau-de-bord:3000
}
Ce mécanisme n'est sûr que sur HTTPS, ce qui est le cas ici. Il ne remplace pas un vrai SSO pour des équipes : voir par exemple Keycloak. Pensez aussi à limiter les tentatives répétées avec les outils décrits dans Fail2ban. Sachez que dans les versions antérieures à la 2.8.0, la directive s'appelait basicauth.
Recharger, valider et dépanner
Après chaque modification du Caddyfile, validez la syntaxe puis rechargez sans redémarrer le conteneur :
docker compose exec -w /etc/caddy caddy caddy validate --config /etc/caddy/Caddyfile
docker compose exec -w /etc/caddy caddy caddy reload --config /etc/caddy/Caddyfile
Si un certificat n'est pas émis, vérifiez dans l'ordre :
- Les enregistrements DNS pointent bien vers l'IP du VPS (et pas vers un ancien serveur).
- Les ports 80 et 443 sont joignables depuis Internet, pare-feu compris.
- Aucun autre processus (Nginx, Apache) n'occupe déjà ces ports sur l'hôte :
ss -tlnp | grep -E ':(80|443)'. - Vous n'êtes pas bloqué par une limite de débit : les messages d'erreur du journal le mentionnent.
Pour la mise à jour, récupérez la nouvelle image puis recréez le conteneur : grâce aux volumes, les certificats sont conservés. Ces deux commandes peuvent aussi être regroupées dans un script de mise à jour.
docker compose pull
docker compose up -d
Ports 80 et 443 déjà occupés : serveur web et panneau
Un port TCP ne peut être écouté que par un seul processus à la fois. Si un serveur web est déjà actif sur l'hôte, Caddy ne peut pas démarrer sur les ports 80 et 443, et l'erreur est visible dans les logs du conteneur. Sous Linux, les serveurs web courants sont Nginx et Apache. Sous Windows, le serveur web de référence est IIS (Internet Information Services). Un panneau d'administration comme Plesk gère aussi le serveur web de l'hôte.
Avant de déployer Caddy, décidez qui porte le trafic web et désactivez l'autre : deux serveurs web ne peuvent pas écouter sur les mêmes ports. Pour repérer le processus en cause, utilisez la commande ss -tlnp donnée plus haut.
Ce guide suppose un seul serveur. Un cluster de plusieurs machines, avec répartition de charge, demande une autre architecture.
Pour aller plus loin
Si vous partez de zéro, commencez par publier un service en HTTPS sur un VPS Linux pour comprendre la chaîne DNS, ports et certificats. Sur un VPS Linux ou un serveur dédié, Caddy en conteneur devient alors le point d'entrée unique de toutes vos applications : un seul endroit pour les certificats, les en-têtes et les règles d'accès.
FiveM
Minecraft
Rust
RedM
Hytale