FR

Applications

Caddy en reverse proxy avec HTTPS automatique

Installer Caddy sur Debian ou Ubuntu depuis son dépôt officiel, publier une application en HTTPS automatique, protéger une interface d'administration, mettre à jour et sauvegarder.

8 min de lecture, mis à jour le 18 novembre 2026

Sur cette page

Vos valeurs

Renseignez-les une fois, les commandes du guide se mettent à jour.

Ce guide vous explique comment placer Caddy devant une application hébergée sur votre serveur. Caddy reçoit les visiteurs sur les ports 80 et 443, obtient et renouvelle seul le certificat TLS, puis transmet les requêtes à l’application, qui reste accessible uniquement en local.

À la fin du guide, votre application répond sur https://app.votre-domaine.com, le trafic HTTP est redirigé vers HTTPS et vous savez protéger une interface d’administration, mettre à jour Caddy et sauvegarder ses données.

Commander un serveur

Ce guide s’applique aux serveurs que vous administrez vous-même :

Prérequis

  • Un serveur sous Debian 12 ou 13, ou Ubuntu 22.04 ou 24.04
  • Un accès SSH avec un utilisateur disposant de sudo
  • Un nom de domaine dont vous gérez la zone DNS
  • Une application qui écoute en local, par exemple sur 127.0.0.1:3000
  • Aucun autre logiciel qui occupe les ports 80 et 443, comme Nginx ou Apache

Ports utilisés

Port Sens Rôle À ouvrir
80/tcp Entrant Validation HTTP-01 et redirection vers HTTPS Oui
443/tcp Entrant HTTPS (HTTP/1.1 et HTTP/2) et validation TLS-ALPN-01 Oui
443/udp Entrant HTTP/3 Recommandé
2019/tcp Local API d’administration de Caddy, sur localhost Non
3000/tcp Local Application d’exemple Non

Étape 1 : faire pointer le domaine vers le serveur

Créez un enregistrement A pour app.votre-domaine.com vers VOTRE_IP_SERVEUR. Si votre domaine est géré chez HostMyServers, suivez le guide Créer un enregistrement A.

Vérifiez ensuite le résultat depuis le serveur :

Terminal
sudo apt update
sudo apt install -y bind9-dnsutils
dig +short A app.votre-domaine.com
dig +short AAAA app.votre-domaine.com

La première commande doit renvoyer l’adresse de votre serveur. Si la seconde renvoie une adresse IPv6, elle doit aussi correspondre à ce serveur : l’autorité de certification peut l’utiliser pour valider le domaine. Dans le cas contraire, supprimez cet enregistrement AAAA.

Étape 2 : installer Caddy depuis le dépôt officiel

Ajoutez le dépôt stable publié par le projet Caddy, puis installez le paquet :

Terminal
sudo apt install -y debian-keyring debian-archive-keyring apt-transport-https curl gnupg
curl -1sLf 'https://dl.cloudsmith.io/public/caddy/stable/gpg.key' | sudo gpg --dearmor -o /usr/share/keyrings/caddy-stable-archive-keyring.gpg
curl -1sLf 'https://dl.cloudsmith.io/public/caddy/stable/debian.deb.txt' | sudo tee /etc/apt/sources.list.d/caddy-stable.list
sudo chmod o+r /usr/share/keyrings/caddy-stable-archive-keyring.gpg
sudo chmod o+r /etc/apt/sources.list.d/caddy-stable.list
sudo apt update
sudo apt install -y caddy

Le paquet crée l’utilisateur système caddy et démarre le service du même nom. Contrôlez l’installation :

Terminal
caddy version
systemctl status caddy --no-pager

Étape 3 : ouvrir le pare-feu

Si vous utilisez UFW, autorisez les ports web :

Terminal
sudo ufw allow 80/tcp
sudo ufw allow 443/tcp
sudo ufw allow 443/udp
sudo ufw status

Vérifiez que l’application répond bien en local :

Terminal
curl -I http://127.0.0.1:3000

Si elle tourne dans Docker, publiez son port sur la boucle locale uniquement, avec 127.0.0.1:3000:3000. Un port publié sous la forme 3000:3000 reste joignable depuis Internet, car Docker insère ses propres règles de pare-feu et UFW ne les filtre pas.

Étape 4 : écrire le Caddyfile

Conservez le fichier fourni, puis ouvrez-le :

Terminal
sudo cp /etc/caddy/Caddyfile /etc/caddy/Caddyfile.orig
sudo nano /etc/caddy/Caddyfile

Remplacez son contenu par :

caddyfile
{
	email admin@votre-domaine.com
}

app.votre-domaine.com {
	encode zstd gzip
	reverse_proxy 127.0.0.1:3000
}
Élément Rôle
email Adresse associée au compte ACME, utile en cas de problème de certificat
app.votre-domaine.com Nom public : sa présence active le HTTPS automatique
encode zstd gzip Compression des réponses
reverse_proxy Transmission des requêtes à l’application

Caddy gère seul la redirection de HTTP vers HTTPS et le passage des WebSockets. Il renseigne aussi les en-têtes X-Forwarded-For, X-Forwarded-Proto et X-Forwarded-Host, et transmet le Host d’origine à une application en HTTP.

Étape 5 : valider et appliquer la configuration

Terminal
sudo caddy fmt --overwrite /etc/caddy/Caddyfile
sudo -u caddy caddy validate --config /etc/caddy/Caddyfile --adapter caddyfile
sudo systemctl reload caddy

Le rechargement ne coupe pas les connexions en cours. Si la nouvelle configuration est refusée, Caddy continue avec la précédente.

Vérifier le résultat

Consultez les journaux, puis testez les deux protocoles :

Terminal
sudo journalctl -u caddy --no-pager -n 50
curl -I http://app.votre-domaine.com
curl -I https://app.votre-domaine.com

La requête HTTP doit renvoyer une redirection 308 vers HTTPS, et la requête HTTPS la réponse de votre application. Les journaux doivent contenir certificate obtained successfully.

Contrôlez ensuite l’émetteur et les dates du certificat, ainsi que les ports en écoute :

Terminal
echo | openssl s_client -connect app.votre-domaine.com:443 -servername app.votre-domaine.com 2>/dev/null | openssl x509 -noout -issuer -dates
sudo ss -tulpn | grep caddy

Le port 2019 doit apparaître uniquement sur 127.0.0.1. Depuis votre poste, l’adresse http://VOTRE_IP_SERVEUR:3000 ne doit pas répondre.

Publier plusieurs sites

Pour garder un fichier par site, créez un dossier dédié :

Terminal
sudo mkdir -p /etc/caddy/sites
sudo nano /etc/caddy/sites/app.caddy

Placez le bloc du site dans /etc/caddy/sites/app.caddy :

caddyfile
app.votre-domaine.com {
	encode zstd gzip
	reverse_proxy 127.0.0.1:3000
}

Le fichier /etc/caddy/Caddyfile ne contient plus que les options globales et l’import :

caddyfile
{
	email admin@votre-domaine.com
}

import sites/*.caddy

Validez et rechargez à nouveau comme à l’étape 5.

Protéger une interface d’administration

Une interface d’administration ne doit pas être ouverte à tous. L’exemple suivant cumule deux protections : seule votre adresse IP est acceptée, puis un mot de passe est demandé.

Générez d’abord l’empreinte du mot de passe. La commande le demande deux fois et affiche le résultat :

Terminal
caddy hash-password

Ajoutez ensuite ce site en remplaçant BCRYPT_HASH par l’empreinte obtenue :

caddyfile
admin.votre-domaine.com {
	@allowed client_ip VOTRE_IP

	handle @allowed {
		basic_auth {
			admin BCRYPT_HASH
		}
		reverse_proxy 127.0.0.1:9000
	}

	handle {
		abort
	}
}

Les connexions venant d’une autre adresse sont coupées sans réponse. Si votre adresse IP change souvent, réservez plutôt cette interface à un réseau privé, avec WireGuard ou Tailscale.

Réglages courants

Répartir la charge entre plusieurs instances

caddyfile
app.votre-domaine.com {
	reverse_proxy 127.0.0.1:3001 127.0.0.1:3002 {
		lb_policy round_robin
		health_uri /health
		health_interval 10s
	}
}

L’URL /health doit exister dans votre application et répondre avec un code 2xx. Une instance qui échoue à ce contrôle est écartée jusqu’à son rétablissement.

Joindre une application en HTTPS

caddyfile
app.votre-domaine.com {
	reverse_proxy https://127.0.0.1:8443 {
		header_up Host {host}
		transport http {
			tls_server_name backend.votre-domaine.com
		}
	}
}

Caddy vérifie le certificat de l’application. tls_server_name doit correspondre à un nom présent dans ce certificat. Depuis Caddy 2.11, le Host envoyé à une cible HTTPS est par défaut celui de la cible : header_up Host {host} conserve le nom public pour les applications qui en ont besoin.

Écrire les accès dans un fichier

caddyfile
app.votre-domaine.com {
	log {
		output file /var/log/caddy/app.log
	}
	reverse_proxy 127.0.0.1:3000
}

Le paquet crée /var/log/caddy pour l’utilisateur caddy. Gardez vos journaux dans ce dossier pour éviter les erreurs de droits.

Placer Caddy derrière un autre proxy

Si un autre proxy reçoit les visiteurs avant Caddy, déclarez son adresse dans les options globales. Sans cela, Caddy ne tient pas compte de l’adresse client que ce proxy lui transmet.

caddyfile
{
	email admin@votre-domaine.com
	servers {
		trusted_proxies static 203.0.113.10/32
	}
}

Mettre à jour Caddy

Caddy étant installé par paquet, mettez-le à jour avec APT :

Terminal
sudo apt update
sudo apt install --only-upgrade caddy
caddy version
systemctl status caddy --no-pager

N’utilisez pas caddy upgrade sur cette installation : cette commande expérimentale remplace directement le binaire géré par le paquet.

Sauvegarder et restaurer

Deux emplacements sont à conserver :

Chemin Contenu
/etc/caddy/ Caddyfile et fichiers importés
/var/lib/caddy/.local/share/caddy/ Certificats, clés privées et comptes ACME
Terminal
sudo tar -czf /root/caddy-$(date +%F).tar.gz /etc/caddy /var/lib/caddy/.local/share/caddy
sudo chmod 600 /root/caddy-$(date +%F).tar.gz

Cette archive contient des clés privées : copiez-la hors du serveur dans un emplacement chiffré. Le dossier de données n’est pas un cache. Le conserver évite de redemander tous les certificats et de heurter les limites de l’autorité de certification.

Pour restaurer l’archive sur un serveur où Caddy est installé, en remplaçant AAAA-MM-JJ par sa date :

Terminal
sudo systemctl stop caddy
sudo tar -xzf /root/caddy-AAAA-MM-JJ.tar.gz -C /
sudo chown -R caddy:caddy /var/lib/caddy
sudo systemctl start caddy

En cas de problème

listen tcp :80: bind: address already in use

Un autre service occupe le port 80 ou 443 :

Terminal
sudo ss -ltnp | grep -E ':(80|443) '

Arrêtez et désactivez ce service s’il n’est plus utile, par exemple avec sudo systemctl disable --now nginx.

urn:ietf:params:acme:error:dns ou NXDOMAIN

Le nom n’existe pas encore dans le DNS, ou la propagation n’est pas terminée. Vérifiez-le avec dig +short A app.votre-domaine.com. Caddy réessaie seul : inutile de le redémarrer en boucle.

urn:ietf:params:acme:error:unauthorized ou urn:ietf:params:acme:error:connection

L’autorité de certification n’a pas pu joindre ce serveur. Vérifiez les enregistrements A et AAAA, puis les règles du pare-feu pour les ports 80 et 443. Si tout est correct sur le serveur et que le port reste injoignable depuis l’extérieur, contactez le support depuis votre espace client.

urn:ietf:params:acme:error:caa

Un enregistrement CAA du domaine interdit l’autorité utilisée. Ajoutez-y l’autorité concernée, letsencrypt.org pour Let’s Encrypt, ou supprimez cette restriction.

urn:ietf:params:acme:error:rateLimited

Trop de demandes ont été envoyées pour ce domaine. Attendez la fin de la période indiquée dans le message. Pour vos essais, utilisez l’environnement de test de Let’s Encrypt, dont les certificats ne sont pas reconnus par les navigateurs, et retirez cette ligne ensuite :

caddyfile
{
	acme_ca https://acme-staging-v02.api.letsencrypt.org/directory
}

tlsv1 alert internal error dans le navigateur ou avec curl

Caddy n’a pas encore de certificat pour ce nom. Cherchez la cause dans les journaux :

Terminal
sudo journalctl -u caddy --no-pager -n 100 | grep -iE 'error|acme|challenge'

Erreur 502 et connect: connection refused

Caddy ne parvient pas à joindre l’application. Vérifiez qu’elle fonctionne et qu’elle écoute sur l’adresse indiquée dans reverse_proxy :

Terminal
curl -I http://127.0.0.1:3000
sudo ss -ltnp | grep 3000

Boucle de redirections

L’application force HTTPS sans reconnaître l’en-tête X-Forwarded-Proto. Activez l’option « trust proxy » ou son équivalent dans l’application. Si le domaine passe aussi par le proxy de Cloudflare, réglez le mode SSL/TLS sur Full (strict) : le mode Flexible provoque ce type de boucle.

localhost:2019 et connection refused au rechargement

Le service est arrêté ou l’API d’administration a été désactivée. Consultez son état, corrigez l’erreur signalée, puis démarrez-le :

Terminal
systemctl status caddy --no-pager
sudo systemctl start caddy

open /var/log/...: permission denied

Caddy fonctionne avec l’utilisateur caddy et ne peut pas écrire partout. Écrivez les journaux dans /var/log/caddy/.

Références