Guide

Caddy, un serveur HTTP avec des certificats TLS intégrés

Caddy est un serveur HTTP en Go qui obtient et renouvelle seul ses certificats TLS. Caddyfile, HTTPS automatique, TLS à la demande et comparaison avec nginx.

L'équipe CodeWorlds18 min de lecture ·

Pratique HTML et CSS dans des leçons interactives avec un éditeur de code.

Crée un compte gratuit→
Dans cet article9

Caddy est un serveur HTTP écrit en Go qui obtient et renouvelle seul ses certificats TLS. Deux lignes de configuration suffisent pour obtenir un HTTPS fonctionnel avec renouvellement en arrière-plan. La version actuelle est la 2.11.4, la licence est unique et permissive, et le projet se finance par le sponsoring plutôt qu'en vendant des fonctionnalités verrouillées.

Ce que Caddy fait différemment de nginx

Dans une configuration nginx typique, le certificat est une préoccupation distincte du serveur. Certbot ou acme.sh dialogue avec l'autorité de certification, écrit des fichiers quelque part dans un répertoire système, puis exécute un hook qui demande au serveur de recharger sa configuration. Le renouvellement est géré par un timer systemd ou une entrée cron. Cela fait trois éléments indépendants, chacun capable de tomber en panne seul : certbot peut récupérer un certificat mais échouer à recharger le serveur, le timer peut cesser de fonctionner après une mise à jour du système, et le serveur peut tourner pendant trois semaines avec un fichier expiré parce que personne n'a lu les logs.

Caddy fait entrer tout cela dans le processus du serveur. La gestion des certificats est assurée par CertMagic, une bibliothèque extraite du même projet. Quand Caddy charge une configuration et y voit un nom de domaine public, il ouvre lui-même une session ACME, termine lui-même le challenge, écrit lui-même le certificat dans le stockage configuré et surveille l'échéance du renouvellement dans une boucle qui tourne dans le même processus. Il n'y a ni cron, ni hook de rechargement, ni question de savoir si le timer a vraiment démarré.

Cette commodité a un prix concret qu'il vaut mieux connaître d'avance. Le processus du serveur détient désormais la clé du compte ACME et les clés privées des certificats, donc il a besoin d'un répertoire de données accessible en écriture et durable. Le serveur a besoin d'un accès réseau à l'autorité de certification, ce qui dans les environnements isolés exige une réponse séparée. Si les certificats arrivent de toute façon d'ailleurs, par exemple d'une PKI d'entreprise ou d'une terminaison TLS sur un load balancer cloud, l'automatisation de Caddy commence à gêner et doit être désactivée explicitement.

La deuxième différence concerne les valeurs par défaut. Nginx écoute par défaut sur le port 80 sans chiffrement. Caddy sert tout en HTTPS par défaut, redirige le trafic du port 80 vers le 443, et même pour l'adresse localhost il émet un certificat depuis sa propre autorité de certification de confiance locale, en installant cette racine dans le magasin de confiance du système. Pour certaines équipes, cela fait gagner une semaine de travail, pour d'autres c'est une surprise au premier lancement dans un conteneur.

Version, licence et modèle de financement

La version actuelle est la 2.11.4. Le tag v2.11.4 du dépôt porte la date du 1er juin 2026 d'après le proxy de modules Go, tandis que la release GitHub elle-même a été publiée le 3 juin 2026. Cet écart de deux jours est la distance normale entre le tag et la construction des artefacts, mais si tu automatises les vérifications de version, sache que deux sources indiquent deux dates.

Le dépôt caddyserver/caddy a été créé en janvier 2015, compte environ 75,1 mille étoiles, 4897 forks et 272 issues ouvertes. Le dernier changement sur la branche principale date du 19 août 2026 et le dépôt n'est pas archivé. Pour un logiciel d'infrastructure, c'est un rythme sain.

La licence est un cas propre, ce qui lors d'un audit de dépendances arrive moins souvent qu'il ne devrait. J'ai vérifié trois endroits et tous disent la même chose. La racine du dépôt contient un fichier LICENSE avec le texte complet de l'Apache License 2.0. L'API GitHub indique l'identifiant apache-2.0 pour ce dépôt. L'archive du module téléchargée depuis proxy.golang.org pour la version v2.11.4 contient un fichier LICENSE de 11358 octets, le même texte Apache. J'ai en plus vérifié ce qu'il est facile d'oublier : le binaire précompilé de la page des releases. L'archive caddy_2.11.4_linux_amd64.tar.gz contient exactement trois entrées, LICENSE, README.md et l'exécutable caddy. Il n'y a pas de trou comme dans certains projets où le dépôt a une licence mais pas le paquet distribué. Les releases sont signées, avec des fichiers .sig et .pem à côté de chaque artefact, plus un inventaire des composants au format SBOM.

L'argent vient du sponsoring, et c'est à la fois la force et la faiblesse du projet. La page de sponsoring dit sans détour que Caddy n'a aucune fonctionnalité derrière un paywall, et que chaque palier achète du support et de la priorité plutôt qu'un accès au code. Les prix sont indiqués par mois : Indie 25 dollars, Indie Pro 50 dollars, Startup 99 dollars, Startup Pro 249 dollars, Business 999 dollars, Business+ 2999 dollars. Il existe aussi un palier intitulé Enterprise+ pour lequel je n'ai trouvé aucun montant affiché, donc je n'en inventerai pas. La même page se compare aux concurrents en citant des prix pour Traefik et NGINX Plus, mais ce sont les chiffres marketing de Caddy lui-même et je ne les ai pas vérifiés auprès de ces éditeurs, donc considère-les comme l'affirmation de quelqu'un d'autre.

Le risque de ce modèle est réel. Le développement dépend d'une poignée de mainteneurs et de sponsors qui continuent de payer. Tu n'achètes pas un contrat de support avec le logiciel, tu l'achètes séparément, et tant que tu ne l'as pas fait, tu n'as aucun délai de réponse en cas d'incident. La licence Apache 2.0 accorde une protection sur les brevets et une pleine liberté d'usage commercial, donc juridiquement tu es en sécurité, mais le droit ne remplace pas la maintenance.

Le Caddyfile, ou la configuration en quelques lignes

Caddy lit nativement du JSON, et le Caddyfile est un adaptateur de configuration qui traduit un format convivial en ce JSON. La configuration de production sensée la plus courte tient en deux lignes.

CADDYFILE
example.com

reverse_proxy localhost:8080

C'est tout. La première ligne est l'adresse du site servi et en même temps le signal pour Caddy qu'il doit obtenir un certificat pour example.com. La seconde transmet le trafic à une application qui écoute en local. La redirection HTTP vers HTTPS, les en-têtes X-Forwarded-*, la vérification de santé des upstreams et le renouvellement des certificats fonctionnent sans autre entrée.

Une configuration réaliste grossit, mais elle n'explose pas.

CADDYFILE
example.com {
	encode zstd gzip

	handle_path /api/* {
		reverse_proxy localhost:3000 localhost:3001 {
			lb_policy least_conn
			health_uri /healthz
		}
	}

	handle {
		root * /srv/www
		try_files {path} /index.html
		file_server
	}

	header {
		Strict-Transport-Security "max-age=31536000; includeSubDomains"
		X-Content-Type-Options nosniff
	}

	log {
		output file /var/log/caddy/example.log
		format json
	}
}

Une chose dans ce fichier heurte l'intuition de quiconque vient de nginx. L'ordre des directives dans le fichier n'a pas d'importance. Caddy les trie selon sa propre liste fixe, donc encode s'exécutera toujours à un point précis de la chaîne de handlers quel que soit l'endroit où tu l'as écrit. Si tu as besoin d'un ordre littéral, utilise la directive route, qui traite son contenu comme une unité non réordonnée. L'ordre global peut aussi être surchargé avec l'option order dans le bloc global. Les blocs handle sont mutuellement exclusifs, ce qui signifie que seul le premier qui correspond s'exécute, et c'est ainsi qu'ils diffèrent de route.

Trois commandes couvrent le travail quotidien avec le fichier. caddy fmt --overwrite remet l'indentation en ordre, caddy validate --config Caddyfile vérifie si la configuration peut être chargée, et caddy adapt --config Caddyfile --pretty affiche le JSON obtenu. La dernière est le meilleur outil d'apprentissage, car elle montre ce que le Caddyfile cache réellement. Note que l'adaptation est un contrôle plus faible que la validation : un fichier peut se convertir correctement en JSON et échouer quand même au chargement, parce que le fichier de certificat référencé n'existe pas.

Comment fonctionne le HTTPS automatique

L'automatisation s'active quand Caddy connaît un nom d'hôte ou une adresse IP qu'il doit servir. Il l'apprend de plusieurs sources : une adresse de site dans le Caddyfile, un matcher d'hôte de premier niveau dans la configuration JSON, les options de ligne de commande --domain ou --from, et enfin le chargeur de certificats automate.

Ce qui la désactive est tout aussi important. Un préfixe http:// sur l'adresse du site, aucun nom dans la configuration, une écoute exclusive sur le port HTTP, des certificats chargés manuellement, et une désactivation explicite via l'option globale. L'option auto_https accepte quatre valeurs : off, disable_redirects, ignore_loaded_certs et disable_certs. Savoir les distinguer peut être décisif, car derrière un load balancer on veut généralement désactiver seulement la redirection, pas toute la mécanique.

Pour les noms DNS publics, le certificat vient d'une autorité ACME publique, par défaut Let's Encrypt ou ZeroSSL, avec repli automatique sur la seconde quand la première échoue. Cela a une conséquence pratique que la documentation signale directement : Let's Encrypt peut t'envoyer un email au sujet d'une expiration prochaine alors que Caddy a renouvelé le certificat chez ZeroSSL. Pour localhost, les adresses IP et les noms internes, Caddy émet un certificat depuis sa propre autorité et essaie d'installer cette racine dans le magasin de confiance du système, ce pour quoi il peut demander un mot de passe. Les noms qui se terminent par .ts.net sont délégués à une instance Tailscale exécutée localement au lieu d'ACME.

CADDYFILE
{
	email admin@example.com
	acme_ca https://acme-staging-v02.api.letsencrypt.org/directory
	key_type p256
	renewal_window_ratio 0.33
	storage file_system /var/lib/caddy
	admin localhost:2019
	servers {
		protocols h1 h2 h3
		trusted_proxies static private_ranges
		trusted_proxies_strict
	}
}

L'option storage mérite l'attention car elle est responsable de la panne de production la plus courante. Le répertoire de données doit être accessible en écriture et durable, sinon chaque redémarrage de conteneur signifie un nouveau compte ACME et une nouvelle demande de certificat, et les limites de débit de Let's Encrypt sont strictes. La même option résout le problème du cluster : plusieurs instances Caddy qui pointent vers le même stockage coordonnent entre elles l'émission des certificats, en partageant clés et agrafes OCSP, sans négociation supplémentaire. Il existe des modules de stockage adossés à des bases de données externes, dont certains pour PostgreSQL et Redis, mais ce sont des plugins hors de la release standard.

Les certificats wildcard ne fonctionnent que lorsque l'astérisque se trouve dans le label le plus à gauche du nom. *.example.com convient, alors que sub.*.example.com ou foo*.example.com ne conviennent pas, et c'est une restriction de l'infrastructure à clé publique plutôt que de Caddy. Le challenge DNS, nécessaire pour les certificats wildcard et pour les serveurs sans port 80 public, exige un module pour ton fournisseur DNS précis, et le binaire standard n'en livre aucun.

TLS à la demande et domaines des clients

C'est la fonctionnalité pour laquelle beaucoup d'entreprises choisissent Caddy plutôt que n'importe quoi d'autre. Le mode normal récupère les certificats au chargement de la configuration, donc chaque nom doit être connu d'avance. Le TLS à la demande inverse cet ordre : le certificat est créé lors de la première poignée de main TLS pour un nom que le serveur ne connaît pas encore. La poignée de main est retenue quelques secondes, le certificat atterrit dans un cache, et les connexions suivantes sont rapides.

Le cas d'usage est évident pour tout produit avec des domaines appartenant aux clients. Le client fait pointer un enregistrement CNAME vers ton infrastructure et le certificat apparaît tout seul, sans entrée de configuration et sans rechargement du serveur. Des services de tunnel comme Portless ou Cloudflare résolvent un problème similaire, sauf que là le certificat fait partie de l'offre du fournisseur et tu le paies par abonnement.

Le mécanisme doit être restreint, sinon n'importe qui qui fait pointer un domaine arbitraire vers ton adresse IP force le serveur à tenter une émission et épuise les limites de l'autorité. Caddy l'exige explicitement et refuse de fonctionner à la demande sans restrictions. La restriction principale est l'endpoint ask.

CADDYFILE
{
	on_demand_tls {
		ask http://localhost:9000/tls-permission
	}
}

https:// {
	tls {
		on_demand
	}
	reverse_proxy localhost:8080
}

Le contrat de cet endpoint est simple et bien documenté. Caddy envoie une requête HTTP à l'adresse indiquée, en ajoutant une query string ?domain= avec le nom de domaine de la poignée de main. Un code de statut 2xx signifie la permission d'émettre le certificat, tout autre code interrompt la poignée de main avec une erreur. L'endpoint doit répondre vite, car il bloque la connexion du client, donc interroger une base de données à chaque requête sans cache est une mauvaise idée. Les restrictions sont globales et ne peuvent pas être définies par site.

API d'administration, xcaddy et limites de l'écosystème

Caddy expose une interface d'administration sur localhost:2019. L'adresse peut être changée avec l'option admin ou la variable d'environnement CADDY_ADMIN. Via cette interface, tu remplaces toute la configuration ou des fragments, sans redémarrer le processus et sans couper les connexions.

Bash
# inspect the active configuration as JSON
curl -s localhost:2019/config/ | jq

# convert the Caddyfile to JSON and push it into the running process
caddy adapt --config Caddyfile --pretty > caddy.json
curl -X POST localhost:2019/load \
  -H "Content-Type: application/json" \
  --data-binary @caddy.json

# the same operation as a command line shortcut
caddy reload --config Caddyfile

# start with the last saved configuration after a machine restart
caddy run --resume

# what exactly is compiled into this binary
caddy build-info

# a custom binary with the Cloudflare DNS module
xcaddy build --with github.com/caddy-dns/cloudflare

Cette dernière commande mène à la limitation la plus sérieuse du projet. Caddy ne charge pas les plugins dynamiquement. Chaque module est compilé dans le binaire, donc ajouter la prise en charge du challenge DNS, un stockage adossé à une base de données ou une authentification personnalisée signifie construire ton propre exécutable avec xcaddy et installer Go sur la machine de build. Mettre à jour Caddy signifie alors reconstruire l'image plutôt que lancer apt upgrade. En échange, tu obtiens un fichier unique sans dépendances système qui peut être copié n'importe où.

La taille de l'écosystème est la deuxième limitation et il n'y a aucune raison de l'enjoliver. Le registre officiel des plugins Caddy recense 319 paquets enregistrés. Nginx et Apache ont deux décennies de modules, d'articles de blog et d'extraits de configuration prêts à copier. Les chiffres de Stack Overflow le montrent : le tag caddy compte 369 questions, traefik 2266, nginx 54493 et apache 91489. Quand tu as besoin de quelque chose d'ordinaire, la documentation de Caddy est meilleure que celle de nginx et tout à fait suffisante. Quand tu as besoin de quelque chose d'étrange, tu t'installes sur le forum du projet et tu attends au lieu de trouver la réponse en deux minutes. C'est le coût réel du choix du plus petit outil.

Il vaut la peine de le mettre à côté des plateformes qui t'enlèvent de toute façon la couche serveur. Railway, Fly.io et Coolify terminent elles-mêmes le TLS pour tes applications, donc configurer Caddy à l'intérieur du conteneur y fait souvent double emploi.

Caddy face aux alternatives

CritèreCaddynginx plus certbotTraefik
Certificats TLSdans le processus du serveur, pas de cronoutil séparé, timer et hook de rechargementdans le processus du serveur, pas de cron
Format de configurationCaddyfile ou JSONson propre langage de directivesYAML, TOML ou labels de conteneur
Rechargement de la configurationAPI HTTP sur le port 2019signal au processussurveillance de fichiers et API des providers
Pluginscompilés via xcaddy, 319 dans le registremodules dynamiques et compilés, deux décennies de travailcompilés, ensemble plus réduit
LicenceApache 2.0, aucune fonctionnalité payanteBSD à deux clauses, variante commerciale PlusMIT, variante commerciale Hub
Questions Stack Overflow369544932266
Support payantsponsoring à partir de 25 dollars par moiscontrat NGINX Pluscontrat Traefik Hub

La troisième colonne mérite une phrase de plus, car la différence avec Traefik ne tient pas aux certificats, que les deux gèrent de la même manière, mais à l'origine des routes : Caddy les lit dans un fichier que tu écris toi-même, tandis que Traefik découvre les services dans Docker ou Kubernetes et construit les routes à partir de leurs labels. Avec un ensemble statique de services, le fichier l'emporte en lisibilité ; dans un environnement de conteneurs changeant, la découverte t'évite une couche de templating. Deux inconvénients de Traefik valent cependant la peine d'être connus : son stockage de certificats est un simple fichier acme.json, donc avec plusieurs réplicas le HTTPS automatique ne fonctionnera pas sans un module payant, et le produit payant a été renommé de Enterprise en Hub, ce que les anciens guides ont encore faux.

Erreurs courantes

Le stockage éphémère dans un conteneur est l'erreur numéro un. Si le répertoire de données de Caddy se trouve dans la couche inscriptible de l'image, chaque redémarrage signifie une nouvelle clé de compte et une nouvelle demande de certificat. Après quelques déploiements par jour, tu atteins la limite de débit de l'autorité de certification et tu te retrouves avec un site sans certificat pendant plusieurs heures. Monte un volume et pointe vers lui avec storage file_system.

Un port 80 fermé, en supposant que si tu ne sers que du HTTPS le port 80 est superflu. Le challenge HTTP-01 exige que le port 80 soit joignable depuis l'extérieur. Les alternatives sont le challenge TLS-ALPN-01 sur le port 443 ou le challenge DNS, mais ce dernier demande un module de fournisseur DNS compilé.

Tester contre l'autorité de certification de production. Pendant le débogage d'une configuration, pointe acme_ca vers le répertoire de staging de Let's Encrypt. Les certificats de là ne sont pas approuvés par les navigateurs, mais les limites sont bien plus souples et tu ne te bloqueras pas hors de ton propre domaine pendant une semaine.

S'attendre à ce que les directives s'exécutent dans l'ordre où elles sont écrites dans le fichier. Caddy les trie lui-même. Si ta logique dépend de l'ordre, enveloppe-la dans route.

Placer Caddy derrière un autre proxy sans configurer la confiance. Sans trusted_proxies, l'adresse du client dans les logs sera celle du proxy, et l'en-tête X-Forwarded-For peut être falsifié. Si ton proxy ajoute des adresses à droite, active aussi trusted_proxies_strict.

Omettre le préfixe http:// là où tu veux vraiment du HTTP simple, par exemple sur un endpoint de santé interne. Sans le préfixe, Caddy traite le nom comme un candidat à un certificat et continue d'essayer d'en obtenir un, remplissant les logs d'erreurs ACME.

FAQ

Caddy convient-il au trafic de production ?

Oui, et c'est le cas depuis des années, y compris dans des produits SaaS qui servent des dizaines de milliers de domaines clients via le TLS à la demande. Le goulot d'étranglement se révèle généralement être l'application derrière le proxy plutôt que le serveur lui-même. Si tu mesures des microsecondes sur des fichiers statiques, nginx gagne encore les benchmarks synthétiques, mais cette différence est rarement ce qui limite le système.

Puis-je utiliser Caddy en entreprise sans payer ?

Oui. La licence Apache 2.0 couvre toute la base de code et chaque fonctionnalité, sans variante amputée. Le sponsoring achète du support, de la priorité sur les issues et éventuellement des correctifs sur mesure, pas l'accès à des fonctionnalités. Sans sponsoring, tu n'as toutefois aucun délai de réponse contractuel en cas d'incident.

Que se passe-t-il quand l'autorité de certification est indisponible ?

Caddy essaie l'émetteur configuré suivant, en basculant par défaut entre Let's Encrypt et ZeroSSL. Comme le renouvellement démarre bien avant l'expiration, selon le réglage renewal_window_ratio, quelques heures d'indisponibilité chez une autorité ne se transforment pas en indisponibilité de ton site.

Ma configuration nginx existante se portera-t-elle un pour un ?

Non. Il n'existe pas de convertisseur sensé, et les modèles des deux serveurs diffèrent assez pour qu'une traduction ligne à ligne produise des résultats étranges. La voie pratique consiste à écrire un Caddyfile de zéro pour un site, comparer le comportement, et seulement ensuite migrer le reste.

Comment ajouter un plugin sans compiler sur le serveur de production ?

Construis l'image dans ton pipeline d'intégration continue avec xcaddy build --with <module> et déploie le binaire ou l'image de conteneur terminés. Pour vérifier ce qui a vraiment atterri dans le fichier, lance caddy build-info.

Où trouver des informations fiables sur la version et la licence ?

Tu trouveras la version sur la page des releases du dépôt et la référence complète des options sur caddyserver.com/docs. Les conditions de sponsoring et les tarifs du support sont décrits sur la page de sponsoring du projet.

À lire aussi