Caddy come reverse proxy con HTTPS automatico
Installare Caddy su Debian o Ubuntu dal suo repository ufficiale, pubblicare un'applicazione in HTTPS automatico, proteggere un'interfaccia di amministrazione, aggiornare ed eseguire il backup.
In questa pagina
I tuoi valori
Inseriscili una volta: i comandi della guida si aggiornano.
Questa guida spiega come mettere Caddy davanti a un'applicazione ospitata sul tuo server. Caddy riceve i visitatori sulle porte 80 e 443, ottiene e rinnova da solo il certificato TLS, poi inoltra le richieste all'applicazione, che resta accessibile solo in locale.
Al termine della guida, la tua applicazione risponde su https://app.tuo-dominio.com, il traffico HTTP viene reindirizzato a HTTPS e sai proteggere un'interfaccia di amministrazione, aggiornare Caddy ed eseguire il backup dei suoi dati.
Ordina un Server
Questa guida si applica ai server che amministri tu stesso:
Prerequisiti
- Un server con Debian 12 o 13, oppure Ubuntu 22.04 o 24.04
- Un accesso SSH con un utente che dispone di
sudo - Un nome di dominio di cui gestisci la zona DNS
- Un'applicazione in ascolto in locale, ad esempio su
127.0.0.1:3000 - Nessun altro software che occupi le porte 80 e 443, come Nginx o Apache
Porte utilizzate
| Porta | Direzione | Ruolo | Da aprire |
|---|---|---|---|
| 80/tcp | In entrata | Validazione HTTP-01 e reindirizzamento a HTTPS | Sì |
| 443/tcp | In entrata | HTTPS (HTTP/1.1 e HTTP/2) e validazione TLS-ALPN-01 | Sì |
| 443/udp | In entrata | HTTP/3 | Consigliato |
| 2019/tcp | Locale | API di amministrazione di Caddy, su localhost |
No |
| 3000/tcp | Locale | Applicazione di esempio | No |
Passo 1: far puntare il dominio al server
Crea un record A per app.tuo-dominio.com verso IP_DEL_TUO_SERVER. Se il tuo dominio è gestito presso HostMyServers, segui la guida Creare un record A.
Verifica poi il risultato dal server:
sudo apt update
sudo apt install -y bind9-dnsutils
dig +short A app.tuo-dominio.com
dig +short AAAA app.tuo-dominio.comIl primo comando deve restituire l'indirizzo del tuo server. Se il secondo restituisce un indirizzo IPv6, anch'esso deve corrispondere a questo server: l'autorità di certificazione può usarlo per convalidare il dominio. In caso contrario, elimina questo record AAAA.
Passo 2: installare Caddy dal repository ufficiale
Aggiungi il repository stabile pubblicato dal progetto Caddy, poi installa il pacchetto:
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 caddyIl pacchetto crea l'utente di sistema caddy e avvia il servizio omonimo. Controlla l'installazione:
caddy version
systemctl status caddy --no-pagerPasso 3: aprire il firewall
Se usi UFW, autorizza le porte web:
sudo ufw allow 80/tcp
sudo ufw allow 443/tcp
sudo ufw allow 443/udp
sudo ufw statusVerifica che l'applicazione risponda correttamente in locale:
curl -I http://127.0.0.1:3000Se gira in Docker, pubblica la sua porta solo sul loopback, con 127.0.0.1:3000:3000. Una porta pubblicata nella forma 3000:3000 resta raggiungibile da Internet, perché Docker inserisce le proprie regole di firewall e UFW non le filtra.
Passo 4: scrivere il Caddyfile
Conserva il file fornito, poi aprilo:
sudo cp /etc/caddy/Caddyfile /etc/caddy/Caddyfile.orig
sudo nano /etc/caddy/CaddyfileSostituisci il suo contenuto con:
{
email admin@tuo-dominio.com
}
app.tuo-dominio.com {
encode zstd gzip
reverse_proxy 127.0.0.1:3000
}| Elemento | Ruolo |
|---|---|
email |
Indirizzo associato all'account ACME, utile in caso di problemi con il certificato |
app.tuo-dominio.com |
Nome pubblico: la sua presenza attiva l'HTTPS automatico |
encode zstd gzip |
Compressione delle risposte |
reverse_proxy |
Inoltro delle richieste all'applicazione |
Caddy gestisce da solo il reindirizzamento da HTTP a HTTPS e il passaggio dei WebSocket. Imposta inoltre gli header X-Forwarded-For, X-Forwarded-Proto e X-Forwarded-Host, e inoltra l'Host originale a un'applicazione in HTTP.
Passo 5: convalidare e applicare la configurazione
sudo caddy fmt --overwrite /etc/caddy/Caddyfile
sudo -u caddy caddy validate --config /etc/caddy/Caddyfile --adapter caddyfile
sudo systemctl reload caddyIl ricaricamento non interrompe le connessioni in corso. Se la nuova configurazione viene rifiutata, Caddy continua con la precedente.
Verificare il risultato
Consulta i log, poi testa entrambi i protocolli:
sudo journalctl -u caddy --no-pager -n 50
curl -I http://app.tuo-dominio.com
curl -I https://app.tuo-dominio.comLa richiesta HTTP deve restituire un reindirizzamento 308 verso HTTPS, e la richiesta HTTPS la risposta della tua applicazione. I log devono contenere certificate obtained successfully.
Controlla poi l'emittente e le date del certificato, oltre alle porte in ascolto:
echo | openssl s_client -connect app.tuo-dominio.com:443 -servername app.tuo-dominio.com 2>/dev/null | openssl x509 -noout -issuer -dates
sudo ss -tulpn | grep caddyLa porta 2019 deve comparire solo su 127.0.0.1. Dal tuo computer, l'indirizzo http://IP_DEL_TUO_SERVER:3000 non deve rispondere.
Pubblicare più siti
Per avere un file per ogni sito, crea una cartella dedicata:
sudo mkdir -p /etc/caddy/sites
sudo nano /etc/caddy/sites/app.caddyInserisci il blocco del sito in /etc/caddy/sites/app.caddy:
app.tuo-dominio.com {
encode zstd gzip
reverse_proxy 127.0.0.1:3000
}Il file /etc/caddy/Caddyfile contiene ormai solo le opzioni globali e l'import:
{
email admin@tuo-dominio.com
}
import sites/*.caddyConvalida e ricarica di nuovo come al passo 5.
Proteggere un'interfaccia di amministrazione
Un'interfaccia di amministrazione non deve essere aperta a tutti. L'esempio seguente combina due protezioni: viene accettato solo il tuo indirizzo IP, poi viene richiesta una password.
Genera prima l'hash della password. Il comando la chiede due volte e mostra il risultato:
caddy hash-passwordAggiungi poi questo sito, sostituendo BCRYPT_HASH con l'hash ottenuto:
admin.tuo-dominio.com {
@allowed client_ip TUO_IP
handle @allowed {
basic_auth {
admin BCRYPT_HASH
}
reverse_proxy 127.0.0.1:9000
}
handle {
abort
}
}Le connessioni provenienti da un altro indirizzo vengono interrotte senza risposta. Se il tuo indirizzo IP cambia spesso, riserva piuttosto questa interfaccia a una rete privata, con WireGuard o Tailscale.
Impostazioni comuni
Ripartire il carico tra più istanze
app.tuo-dominio.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 deve esistere nella tua applicazione e rispondere con un codice 2xx. Un'istanza che non supera questo controllo viene esclusa finché non torna disponibile.
Raggiungere un'applicazione in HTTPS
app.tuo-dominio.com {
reverse_proxy https://127.0.0.1:8443 {
header_up Host {host}
transport http {
tls_server_name backend.tuo-dominio.com
}
}
}Caddy verifica il certificato dell'applicazione. tls_server_name deve corrispondere a un nome presente in tale certificato. Da Caddy 2.11, l'Host inviato a una destinazione HTTPS è per impostazione predefinita quello della destinazione: header_up Host {host} mantiene il nome pubblico per le applicazioni che ne hanno bisogno.
Scrivere gli accessi in un file
app.tuo-dominio.com {
log {
output file /var/log/caddy/app.log
}
reverse_proxy 127.0.0.1:3000
}Il pacchetto crea /var/log/caddy per l'utente caddy. Conserva i tuoi log in questa cartella per evitare errori di permessi.
Mettere Caddy dietro un altro proxy
Se un altro proxy riceve i visitatori prima di Caddy, dichiara il suo indirizzo nelle opzioni globali. In caso contrario, Caddy non tiene conto dell'indirizzo client che questo proxy gli trasmette.
{
email admin@tuo-dominio.com
servers {
trusted_proxies static 203.0.113.10/32
}
}Aggiornare Caddy
Poiché Caddy è installato tramite pacchetto, aggiornalo con APT:
sudo apt update
sudo apt install --only-upgrade caddy
caddy version
systemctl status caddy --no-pagerNon usare caddy upgrade su questa installazione: questo comando sperimentale sostituisce direttamente il binario gestito dal pacchetto.
Backup e ripristino
Due percorsi sono da conservare:
| Percorso | Contenuto |
|---|---|
/etc/caddy/ |
Caddyfile e file importati |
/var/lib/caddy/.local/share/caddy/ |
Certificati, chiavi private e account ACME |
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.gzQuesto archivio contiene chiavi private: copialo fuori dal server in una posizione cifrata. La cartella dei dati non è una cache. Conservarla evita di richiedere di nuovo tutti i certificati e di incappare nei limiti dell'autorità di certificazione.
Per ripristinare l'archivio su un server in cui Caddy è installato, sostituendo AAAA-MM-GG con la sua data:
sudo systemctl stop caddy
sudo tar -xzf /root/caddy-AAAA-MM-GG.tar.gz -C /
sudo chown -R caddy:caddy /var/lib/caddy
sudo systemctl start caddyIn caso di problemi
listen tcp :80: bind: address already in use
Un altro servizio occupa la porta 80 o 443:
sudo ss -ltnp | grep -E ':(80|443) 'Arresta e disattiva questo servizio se non ti serve più, ad esempio con sudo systemctl disable --now nginx.
urn:ietf:params:acme:error:dns o NXDOMAIN
Il nome non esiste ancora nel DNS, oppure la propagazione non è terminata. Verificalo con dig +short A app.tuo-dominio.com. Caddy riprova da solo: è inutile riavviarlo in continuazione.
urn:ietf:params:acme:error:unauthorized o urn:ietf:params:acme:error:connection
L'autorità di certificazione non è riuscita a raggiungere questo server. Controlla i record A e AAAA, poi le regole del firewall per le porte 80 e 443. Se sul server è tutto corretto e la porta resta irraggiungibile dall'esterno, contatta il supporto dalla tua area clienti.
urn:ietf:params:acme:error:caa
Un record CAA del dominio vieta l'autorità utilizzata. Aggiungi l'autorità interessata, letsencrypt.org per Let's Encrypt, oppure elimina questa restrizione.
urn:ietf:params:acme:error:rateLimited
Sono state inviate troppe richieste per questo dominio. Attendi la fine del periodo indicato nel messaggio. Per le tue prove, usa l'ambiente di test di Let's Encrypt, i cui certificati non sono riconosciuti dai browser, e rimuovi poi questa riga:
{
acme_ca https://acme-staging-v02.api.letsencrypt.org/directory
}tlsv1 alert internal error nel browser o con curl
Caddy non ha ancora un certificato per questo nome. Cerca la causa nei log:
sudo journalctl -u caddy --no-pager -n 100 | grep -iE 'error|acme|challenge'Errore 502 e connect: connection refused
Caddy non riesce a raggiungere l'applicazione. Verifica che sia in funzione e che ascolti sull'indirizzo indicato in reverse_proxy:
curl -I http://127.0.0.1:3000
sudo ss -ltnp | grep 3000Ciclo di reindirizzamenti
L'applicazione forza HTTPS senza riconoscere l'header X-Forwarded-Proto. Attiva l'opzione «trust proxy» o il suo equivalente nell'applicazione. Se il dominio passa anche dal proxy di Cloudflare, imposta la modalità SSL/TLS su Full (strict): la modalità Flexible provoca questo tipo di ciclo.
localhost:2019 e connection refused al ricaricamento
Il servizio è fermo oppure l'API di amministrazione è stata disattivata. Consulta il suo stato, correggi l'errore segnalato, poi avvialo:
systemctl status caddy --no-pager
sudo systemctl start caddyopen /var/log/...: permission denied
Caddy funziona con l'utente caddy e non può scrivere ovunque. Scrivi i log in /var/log/caddy/.