Caddy : HTTPS automatique et configuration simple

Caddy est un serveur web moderne avec HTTPS automatique par défaut. Contrairement à Nginx ou Apache, Caddy obtient et renouvelle vos certificats TLS sans configuration. En 5 minutes, vous pouvez servir un site statique sécurisé ou proxyfier une API.

Ce que vous allez apprendre

Niveau : Débutant → Intermédiaire · Durée : 25-35 min

À la fin de ce guide, vous saurez :

• Servir un site statique avec HTTPS automatique
• Configurer un reverse proxy vers une application
• Comprendre le modèle mental du Caddyfile
• Déboguer les erreurs courantes (ACME, 502)
• Utiliser tls internal pour les environnements LAN

Choisissez votre parcours

🚀 Site statique Caddyfile minimal + HTTPS auto

🔀 Reverse proxy Proxyfier une API Node/Python/Go

🔒 HTTPS : ce qu'il faut savoir Prérequis, DNS challenge, tls internal

🔧 Dépannage Erreurs ACME, 502, logs

Pourquoi Caddy plutôt que Nginx ?

Critère	Caddy	Nginx
HTTPS	Automatique (Let’s Encrypt intégré)	Manuel (certbot séparé)
Configuration	Lisible (Caddyfile)	Verbeux (nginx.conf)
Rechargement	caddy reload sans perte	nginx -s reload
HTTP/3	Natif	Module externe
Courbe d’apprentissage	30 min	2-3 heures

Glissez pour voir

En résumé : Caddy pour la simplicité, Nginx pour le contrôle fin et l’écosystème mature.

📜 Pour la culture : historique de Caddy

Caddy a été créé par Matt Holt en 2015 avec une vision claire : simplifier la configuration des serveurs web et rendre HTTPS accessible à tous. À l’époque, obtenir un certificat SSL était complexe et coûteux. L’intégration native de Let’s Encrypt dans Caddy a démocratisé HTTPS.

Aujourd’hui, Caddy est utilisé en production par de nombreuses entreprises pour sa simplicité et sa robustesse. Il est écrit en Go, ce qui lui confère d’excellentes performances et une facilité de déploiement (un seul binaire).

Le modèle mental du Caddyfile

Avant de plonger dans la configuration, prenons 2 minutes pour comprendre comment Caddy pense. Cette compréhension vous évitera 90% des erreurs.

L’analogie du routeur réseau

Imaginez un routeur entreprise avec des règles de routage :

• Le site block (example.com { }) = une interface réseau (eth0, wan0)
• Les handlers (root, file_server) = les règles de traitement du trafic
• Le matcher (/api/*) = les ACL/filtres qui dirigent vers le bon backend
• HTTPS automatique = le tunnel VPN configuré en auto-provisioning

Quand un paquet (requête HTTP) arrive, le routeur (matcher) l’oriente vers le bon backend (handler), et le tunnel TLS s’occupe du chiffrement automatiquement.

Visualisation

Les 4 couches du Caddyfile

Pourquoi 4 couches ? Chaque requête traverse ces étapes dans l’ordre. Si vous comprenez ce flux, vous comprenez 90% de Caddy.

Couche	Rôle	Analogie	Exemples
Site block	Définit le domaine ou l’adresse	Interface réseau (quelle interface écoute ?)	example.com { }, :8080 { }, localhost { }
Matchers	Filtrent les requêtes (chemin, méthode, headers)	ACL/règles de filtrage (quel trafic router ?)	/api/*, @websocket, path /static/*
Handlers	Traitent la requête	Règles de routage (où envoyer le paquet)	file_server, reverse_proxy, respond, redir
Réponse	HTTPS activé par défaut si domaine public	Auto-provisioning TLS (tunnel sécurisé auto)	TLS auto via Let’s Encrypt

Glissez pour voir

La règle d'or

Caddy active HTTPS automatiquement pour tout domaine public. Vous n’avez rien à configurer. C’est la philosophie “secure by default”.

Concrètement : si vous écrivez example.com { } et que le DNS pointe vers votre serveur, Caddy obtient un certificat Let’s Encrypt sans que vous le demandiez.

Installation

Ubuntu/Debian

# Ajouter le dépôt officiel
sudo apt install -y debian-keyring debian-archive-keyring apt-transport-https curl
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

# Installer
sudo apt update && sudo apt install caddy

# Le service systemd est configuré automatiquement
sudo systemctl status caddy

RHEL/Rocky/Fedora

# Ajouter le dépôt officiel
sudo dnf install 'dnf-command(copr)'
sudo dnf copr enable @caddy/caddy
sudo dnf install caddy

# Démarrer le service
sudo systemctl enable --now caddy

macOS

brew install caddy

Docker

docker run -d -p 80:80 -p 443:443 \
  -v /path/to/Caddyfile:/etc/caddy/Caddyfile \
  -v caddy_data:/data \
  -v caddy_config:/config \
  caddy:latest

Vérification :

caddy version
# v2.8.x

# Le Caddyfile par défaut est dans /etc/caddy/Caddyfile
cat /etc/caddy/Caddyfile

Installation = service systemd inclus

Si vous installez via le dépôt officiel, le package fournit automatiquement les units systemd et place le Caddyfile dans /etc/caddy/Caddyfile. Pas besoin de créer le service manuellement.

Servir un site statique

1. Créer le répertoire et le fichier

   sudo mkdir -p /var/www/monsite
   echo '<h1>Hello Caddy!</h1>' | sudo tee /var/www/monsite/index.html
   sudo chown -R caddy:caddy /var/www/monsite

2. Configurer le Caddyfile

   sudo tee /etc/caddy/Caddyfile << 'EOF'
   # Pour un test local (pas de TLS)
   :8080 {
       root * /var/www/monsite
       file_server
   }
   EOF

3. Recharger Caddy

   sudo systemctl reload caddy

4. Tester

   curl http://localhost:8080
   # <h1>Hello Caddy!</h1>

Avec un domaine public (HTTPS automatique)

Si votre domaine pointe vers votre serveur :

monsite.com {
    root * /var/www/monsite
    file_server
}

C’est tout. Caddy :

• Obtient automatiquement un certificat Let’s Encrypt
• Redirige HTTP → HTTPS
• Renouvelle le certificat avant expiration

SPA (Single Page Application)

Pour React, Vue, Angular, etc. — fallback vers index.html :

monsite.com {
    root * /var/www/spa
    try_files {path} /index.html
    file_server
}

Configurer un reverse proxy

Qu’est-ce qu’un reverse proxy ?

Un reverse proxy est un intermédiaire entre vos utilisateurs et votre application. C’est comme un réceptionniste d’hôtel :

• Le client ne parle jamais directement aux employés (backend)
• Le réceptionniste (Caddy) reçoit la demande et la transmet au bon service
• Le réceptionniste ajoute des informations utiles (“ce client vient de la chambre 42”)

Pourquoi utiliser un reverse proxy ?

Sans reverse proxy	Avec reverse proxy (Caddy)
Votre app Node/Python écoute sur le port 80	Caddy écoute sur 80/443, votre app sur 3000
Pas de HTTPS (ou config manuelle)	HTTPS automatique
Une seule app par serveur	Plusieurs apps sur le même serveur
Votre app gère les logs HTTP	Caddy centralise les logs

Glissez pour voir

Configuration de base

api.example.com {
    reverse_proxy localhost:3000
}

C’est tout. En une ligne, Caddy :

• Écoute sur api.example.com ports 80 et 443
• Obtient un certificat HTTPS
• Transmet les requêtes à votre app sur localhost:3000
• Ajoute automatiquement les headers Host, X-Forwarded-For, X-Forwarded-Proto

Pourquoi ces headers ?

Quand Caddy transmet une requête à votre app, celle-ci voit l’IP de Caddy (127.0.0.1), pas celle du client. Les headers X-Forwarded-* permettent à votre app de connaître l’IP réelle du client, le protocole utilisé (HTTP/HTTPS), etc.

Avec un chemin spécifique

example.com {
    # L'API sur /api/*
    reverse_proxy /api/* localhost:3000

    # Le reste en statique
    root * /var/www/frontend
    file_server
}

Attention au trailing slash

Le comportement change selon la présence du / final dans reverse_proxy :

# Sans réécriture : /api/users → backend reçoit /api/users
reverse_proxy /api/* localhost:3000

# Avec réécriture : /api/users → backend reçoit /users
handle_path /api/* {
    reverse_proxy localhost:3000
}

Utilisez handle_path si votre backend attend des chemins sans préfixe.

WebSocket

example.com {
    reverse_proxy /ws/* localhost:3000
}

Caddy gère automatiquement l’upgrade WebSocket. Pas de configuration spéciale.

Load balancing

example.com {
    reverse_proxy {
        to backend1:3000
        to backend2:3000
        to backend3:3000

        lb_policy round_robin
        health_uri /health
        health_interval 10s
    }
}

HTTPS automatique : ce qu’il faut savoir

Comment ça marche (en 30 secondes)

Quand vous écrivez example.com { } dans votre Caddyfile, Caddy :

1. Détecte que c’est un domaine public (pas localhost, pas une IP)
2. Contacte Let’s Encrypt pour prouver que vous contrôlez le domaine
3. Obtient un certificat valide 90 jours
4. Configure TLS avec les bonnes options de sécurité
5. Crée une redirection HTTP → HTTPS automatique
6. Renouvelle le certificat avant expiration (environ 30 jours avant)

Tout cela sans une seule ligne de configuration TLS.

HTTPS auto ≠ magie

Caddy active HTTPS automatiquement, mais il y a des prérequis :

1. Le domaine doit pointer vers votre serveur (DNS A/AAAA)
2. Les ports 80 et 443 doivent être accessibles depuis Internet
3. Le domaine doit être public (pas localhost, pas IP)

Si ces conditions ne sont pas remplies, Caddy ne pourra pas obtenir de certificat.

Les 3 modes TLS de Caddy

Mode	Quand l’utiliser	Configuration
Auto (défaut)	Domaine public accessible	example.com { ... }
Internal	Réseau local / développement	tls internal
Manuel	Certificats existants	tls /path/cert.pem /path/key.pem

Glissez pour voir

tls internal pour le LAN

Pour un serveur interne sans accès Internet :

intranet.local {
    tls internal
    reverse_proxy localhost:3000
}

Caddy génère un certificat auto-signé. Important : vous devez installer la CA Caddy dans les navigateurs/clients pour éviter les avertissements de sécurité.

# Afficher le chemin de la CA
caddy trust
# Installe la CA dans le trust store système (Linux/macOS)

DNS Challenge (wildcard, serveur privé)

Si les ports 80/443 ne sont pas accessibles (firewall, NAT), utilisez le DNS Challenge :

# Compiler Caddy avec le plugin DNS (ex: Cloudflare)
xcaddy build --with github.com/caddy-dns/cloudflare

*.example.com {
    tls {
        dns cloudflare {env.CLOUDFLARE_API_TOKEN}
    }
    reverse_proxy localhost:3000
}

Pages d’erreur personnalisées

example.com {
    root * /var/www/html
    file_server

    handle_errors {
        @404 expression {err.status_code} == 404
        handle @404 {
            root * /var/www/errors
            rewrite * /404.html
            file_server
        }

        @5xx expression {err.status_code} >= 500
        handle @5xx {
            respond "Service temporairement indisponible" 503
        }
    }
}

Recettes courantes

Site statique

example.com {
    root * /var/www/html
    file_server
}

SPA (React/Vue/Angular)

example.com {
    root * /var/www/app
    try_files {path} /index.html
    file_server
}

Reverse proxy simple

api.example.com {
    reverse_proxy localhost:3000
}

Proxy + statique (API sur /api)

example.com {
    handle /api/* {
        reverse_proxy localhost:3000
    }
    handle {
        root * /var/www/frontend
        file_server
    }
}

Strip path prefix (/api/users → /users)

example.com {
    handle_path /api/* {
        reverse_proxy localhost:3000
    }
}

TLS interne (LAN)

intranet.local {
    tls internal
    reverse_proxy localhost:3000
}

Certificats manuels

example.com {
    tls /etc/ssl/cert.pem /etc/ssl/key.pem
    file_server
}

Redirection permanente

old.example.com {
    redir https://new.example.com{uri} permanent
}

Headers de sécurité

example.com {
    header {
        Strict-Transport-Security "max-age=31536000"
        X-Content-Type-Options "nosniff"
        X-Frame-Options "DENY"
    }
    file_server
}

Basic Auth

example.com {
    basicauth /admin/* {
        admin $2a$14$hash...
    }
    file_server
}

Pour générer un hash de mot de passe :

caddy hash-password
# Entrez le mot de passe, Caddy retourne le hash bcrypt

Métriques Prometheus

{
    servers {
        metrics
    }
}

example.com {
    file_server
}

Pièges à éviter

Erreur	Conséquence	Solution
DNS ne pointe pas vers le serveur	HTTPS auto échoue (erreur ACME)	dig example.com pour vérifier
Ports 80/443 fermés	Let’s Encrypt ne peut pas valider	Ouvrir les ports ou utiliser DNS Challenge
Domaine local sans tls internal	Caddy tente d’obtenir un certificat	Ajouter tls internal pour .local, .lan
Oublier handle_path pour strip	Backend reçoit /api/users au lieu de /users	Utiliser handle_path /api/* { ... }
Ordre des handlers incorrect	Un handler large capture tout	Placer /api/* avant file_server catch-all
Backend down	Caddy renvoie 502	curl localhost:3000 pour confirmer
https:// dans reverse_proxy	Erreurs de connexion	Ne pas mettre https:// sauf si backend l’exige

Glissez pour voir

Dépannage

Commandes essentielles

# Valider la configuration
caddy validate --config /etc/caddy/Caddyfile

# Recharger sans downtime
sudo systemctl reload caddy

# Voir les logs
sudo journalctl -u caddy -f

# Formater le Caddyfile (indentation)
caddy fmt --overwrite /etc/caddy/Caddyfile

Erreurs courantes

Erreur	Cause probable	Solution
ACME challenge failed	DNS incorrect ou ports fermés	Vérifier DNS + ouvrir 80/443
502 Bad Gateway	Backend ne répond pas	curl localhost:3000 pour tester
too many redirects	Boucle HTTP ↔ HTTPS	Vérifier la config proxy/CDN
permission denied	Caddy ne peut pas lire les fichiers	chown -R caddy:caddy /var/www
address already in use	Autre service sur le port	ss -tlnp | grep :80

Glissez pour voir

Déboguer une erreur ACME

# Voir les détails de l'erreur
sudo journalctl -u caddy | grep -i acme

# Erreurs typiques :
# - "no valid IP addresses" → DNS pas configuré
# - "connection refused" → port 80 fermé
# - "rate limit" → trop de tentatives (attendre 1h)

Déboguer un 502

# 1. Le backend tourne-t-il ?
curl -I http://localhost:3000

# 2. Caddy peut-il joindre le backend ?
sudo -u caddy curl http://localhost:3000

# 3. Regarder les logs
sudo journalctl -u caddy -f

Observabilité

Logs structurés

example.com {
    log {
        output file /var/log/caddy/access.log {
            roll_size 100mb
            roll_keep 5
        }
        format json
    }
    file_server
}

Métriques Prometheus

Ajoutez dans le bloc global :

{
    servers {
        metrics
    }
}

example.com {
    file_server
}

Les métriques sont exposées sur :2019/metrics par défaut.

curl localhost:2019/metrics

Aide-mémoire

Fichiers

Directive	Description
root * /path	Définir la racine des fichiers
file_server	Servir les fichiers statiques
file_server browse	Avec listing des répertoires
try_files {path} /index.html	Fallback SPA

Glissez pour voir

Proxy

Directive	Description
reverse_proxy localhost:3000	Proxy simple
reverse_proxy /api/* localhost:3000	Proxy sur un chemin
handle_path /api/* { reverse_proxy ... }	Strip le préfixe

Glissez pour voir

TLS

Directive	Description
tls email@example.com	HTTPS auto avec email
tls internal	Certificat auto-signé (LAN)
tls /cert.pem /key.pem	Certificats manuels

Glissez pour voir

Headers & Sécurité

Directive	Description
header X-Custom "value"	Ajouter un header
header -Server	Supprimer un header
basicauth /admin/* { user hash }	Auth basique
encode gzip zstd	Compression

Glissez pour voir

Routing

Directive	Description
redir /old /new permanent	Redirection 301
rewrite /old /new	Réécriture interne
respond "OK" 200	Réponse directe
handle_errors { ... }	Pages d’erreur custom

Glissez pour voir

CLI

Commande	Description
caddy validate --config /etc/caddy/Caddyfile	Valider la config
caddy fmt --overwrite Caddyfile	Formater
caddy reload	Recharger la config
caddy hash-password	Générer un hash bcrypt
caddy trust	Installer la CA interne

Glissez pour voir

À retenir

1. HTTPS automatique : fonctionne si DNS + ports 80/443 accessibles
2. tls internal : pour les environnements LAN sans accès Internet
3. caddy validate : toujours valider avant de recharger
4. handle_path : pour strip le préfixe URL avant le backend
5. Ordre des handlers : spécifique → générique
6. Logs : journalctl -u caddy -f pour déboguer

Prochaines étapes

Nginx Alternative avec plus de contrôle

Traefik Reverse proxy cloud-native pour Docker/K8s

HTTP/HTTPS Comprendre le protocole et TLS

Docker + Caddy Caddy comme reverse proxy pour conteneurs

Ressources

• Documentation officielle : caddyserver.com/docs
• Directives Caddyfile : caddyserver.com/docs/caddyfile/directives
• HTTPS automatique : caddyserver.com/docs/automatic-https
• GitHub : github.com/caddyserver/caddy
• Plugins DNS : github.com/caddy-dns

FAQ - Questions Fréquemment Posées

Qu'est-ce que Caddy et pourquoi l'utiliser plutôt que Nginx ?

Caddy est un serveur web moderne avec HTTPS automatique par défaut. Contrairement à Nginx, il obtient et renouvelle les certificats Let's Encrypt sans configuration. Le Caddyfile est plus lisible que nginx.conf. Idéal pour simplicité.

Comment installer Caddy sur Linux ?

Sur Debian/Ubuntu, ajoutez le dépôt officiel puis apt install caddy. Sur RHEL/Fedora, utilisez dnf copr enable @caddy/caddy puis dnf install caddy. Le service systemd est configuré automatiquement.

Comment fonctionne le HTTPS automatique de Caddy ?

Quand vous définissez un domaine public dans le Caddyfile, Caddy contacte automatiquement Let's Encrypt, prouve le contrôle du domaine, obtient un certificat, configure TLS et renouvelle avant expiration. Prérequis : DNS configuré, ports 80/443 ouverts.

Quelle est la structure d'un Caddyfile ?

Un Caddyfile contient des site blocks (domaine entre accolades) avec des directives. Le site block définit l'adresse, les matchers filtrent les requêtes, les handlers les traitent. Exemple : example.com { root * /var/www file_server }

Comment configurer un reverse proxy avec Caddy ?

Utilisez la directive reverse_proxy dans un site block. Exemple : api.example.com { reverse_proxy localhost:3000 }. Caddy ajoute automatiquement les headers X-Forwarded-For et gère l'upgrade WebSocket.

Comment utiliser tls internal pour un serveur local ?

tls internal génère un certificat auto-signé pour les environnements sans accès Internet (LAN, développement). Ajoutez tls internal dans le site block. Installez la CA Caddy avec caddy trust pour éviter les avertissements navigateur.

Comment déboguer une erreur ACME sur Caddy ?

Une erreur ACME signifie que Caddy n'a pas pu obtenir le certificat. Vérifiez le DNS avec dig, les ports 80/443 ouverts, et les logs avec journalctl -u caddy. Erreurs courantes : no valid IP (DNS), connection refused (port fermé).

Comment résoudre une erreur 502 Bad Gateway sur Caddy ?

Une erreur 502 signifie que le backend ne répond pas. Vérifiez que votre application tourne avec curl localhost:3000. Consultez les logs avec journalctl -u caddy -f. N'utilisez pas https:// dans reverse_proxy sauf si le backend l'exige.

Comment valider et recharger la configuration Caddy ?

Validez le Caddyfile avec caddy validate --config /etc/caddy/Caddyfile. Si valide, rechargez avec systemctl reload caddy (sans downtime). Formatez le fichier avec caddy fmt --overwrite pour une indentation propre.

Comment servir une SPA (React/Vue/Angular) avec Caddy ?

Pour une Single Page Application, utilisez try_files {path} /index.html pour rediriger toutes les routes vers index.html. Le routeur frontend gère ensuite l'affichage. Ajoutez file_server pour servir les fichiers statiques.

Comment ajouter une authentification basique avec Caddy ?

Utilisez basicauth avec un nom d'utilisateur et un hash bcrypt du mot de passe. Générez le hash avec caddy hash-password. Exemple : basicauth /admin/* { admin $2a$14$... }. Protège un chemin spécifique.

Comment activer les métriques Prometheus sur Caddy ?

Ajoutez un bloc global avec servers { metrics } pour exposer les métriques sur le port admin (2019 par défaut). Accédez aux métriques via curl localhost:2019/metrics. Format compatible Prometheus.

×

📖 Voir la documentation →