IT

Applicazioni

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.

8 min di lettura, aggiornato il 18 novembre 2026

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:

Terminale
sudo apt update
sudo apt install -y bind9-dnsutils
dig +short A app.tuo-dominio.com
dig +short AAAA app.tuo-dominio.com

Il 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:

Terminale
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

Il pacchetto crea l'utente di sistema caddy e avvia il servizio omonimo. Controlla l'installazione:

Terminale
caddy version
systemctl status caddy --no-pager

Passo 3: aprire il firewall

Se usi UFW, autorizza le porte web:

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

Verifica che l'applicazione risponda correttamente in locale:

Terminale
curl -I http://127.0.0.1:3000

Se 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:

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

Sostituisci il suo contenuto con:

caddyfile
{
	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

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

Il 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:

Terminale
sudo journalctl -u caddy --no-pager -n 50
curl -I http://app.tuo-dominio.com
curl -I https://app.tuo-dominio.com

La 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:

Terminale
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 caddy

La 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:

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

Inserisci il blocco del sito in /etc/caddy/sites/app.caddy:

caddyfile
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:

caddyfile
{
	email admin@tuo-dominio.com
}

import sites/*.caddy

Convalida 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:

Terminale
caddy hash-password

Aggiungi poi questo sito, sostituendo BCRYPT_HASH con l'hash ottenuto:

caddyfile
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

caddyfile
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

caddyfile
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

caddyfile
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.

caddyfile
{
	email admin@tuo-dominio.com
	servers {
		trusted_proxies static 203.0.113.10/32
	}
}

Aggiornare Caddy

Poiché Caddy è installato tramite pacchetto, aggiornalo con APT:

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

Non 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
Terminale
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

Questo 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:

Terminale
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 caddy

In caso di problemi

listen tcp :80: bind: address already in use

Un altro servizio occupa la porta 80 o 443:

Terminale
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:

caddyfile
{
	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:

Terminale
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:

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

Ciclo 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:

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

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

Caddy funziona con l'utente caddy e non può scrivere ovunque. Scrivi i log in /var/log/caddy/.

Riferimenti