Caddy reverse proxy con HTTPS automatico per i servizi di casa

Se in casa girano più servizi e li si vuole raggiungere da fuori, ognuno con il suo sottodominio e su una connessione cifrata, serve un programma che stia davanti a tutti e smisti le richieste. Caddy fa da reverse proxy: riceve le connessioni sulle porte 80 e 443, le passa alla porta locale del servizio giusto e intanto ottiene e rinnova da solo i certificati TLS. Alla fine della guida Caddy gira come servizio systemd su Debian o Ubuntu e legge un Caddyfile con un blocco per ogni sottodominio, così che tutto venga servito in HTTPS. I comandi sono quelli della documentazione ufficiale, elencata in fondo.

Cosa serve

• Un server con Debian, Ubuntu o Raspbian, cioè i sistemi per cui vale il repository ufficiale Cloudsmith usato qui, con systemd e un utente con privilegi sudo.
• Un dominio di cui si possano modificare i record DNS, con un sottodominio per ogni servizio da pubblicare.
• Un indirizzo IP pubblico raggiungibile da internet, con le porte 80 e 443 aperte e inoltrate al server.
• I servizi da pubblicare già avviati e in ascolto su una porta locale (negli esempi 8080 e 9000).
• Dimestichezza con il terminale e con la modifica dei file di testo, che la documentazione di Caddy chiede a chi parte da zero.

Preparare dominio, record DNS e porte del router

Buona parte del lavoro si fa prima di installare il pacchetto, perché l’HTTPS automatico per i nomi pubblici dipende da condizioni che Caddy non può creare da solo. Secondo la pagina Automatic HTTPS, i certificati arrivano senza altri interventi se i record A/AAAA del dominio puntano al server, se le porte 80 e 443 sono aperte verso l’esterno e inoltrate a Caddy, se la cartella dei dati è scrivibile e persistente e se il nome del sito compare nella configurazione.

Per ogni servizio si crea quindi, nel pannello del fornitore DNS, un record A (IPv4) o AAAA (IPv6) con il nome del sottodominio, per esempio app e foto, che punta all’IP pubblico della connessione di casa. Tutti i sottodomini puntano allo stesso indirizzo, dato che è Caddy a distinguerli in base al nome richiesto.

Sul router, nella sezione dedicata all’inoltro delle porte (port forwarding, con nomi che cambiano da un modello all’altro), si inoltrano le porte 80 e 443 all’indirizzo IP locale del server su cui girerà Caddy. Si aprono entrambe: la porta 80 permette la verifica HTTP e il reindirizzamento da HTTP a HTTPS, la 443 serve il sito in HTTPS e permette la verifica TLS-ALPN. Per ottenere il certificato basta che una delle due sfide riesca, quindi la sola 443 può bastare: Caddy le tiene abilitate tutte e due, ne sceglie una a caso, col tempo impara a preferire quella che riesce più spesso e passa all’altra se la prima fallisce. Un inoltro rende il server raggiungibile da chiunque su internet, perciò si inoltrano soltanto queste due porte e si ricontrolla l’IP locale di destinazione, dato che un indirizzo sbagliato esporrebbe un altro dispositivo della rete.

Un limite: con il CGNAT, diffuso con molti operatori italiani, sulle linee FWA e su quelle mobili, l’indirizzo pubblico è condiviso con altri clienti e da fuori non si arriva alle porte del proprio router. In queste condizioni l’HTTPS automatico descritto qui non funziona, qualunque cosa si scriva nel Caddyfile.

Il servizio fa girare Caddy come utente caddy, con la home in /var/lib/caddy; certificati e stato finiscono in /var/lib/caddy/.local/share/caddy, come spiega la pagina Keep Caddy Running, e quella posizione non deve trovarsi su un supporto temporaneo. Caddy esiste anche per Windows (Chocolatey, Scoop) e macOS (Homebrew), con metodi mantenuti dalla comunità e descritti nella pagina Install; qui si resta su Debian e Ubuntu.

Installare Caddy dal repository ufficiale Cloudsmith

Per un sistema in produzione la pagina Install raccomanda il pacchetto ufficiale della distribuzione al posto del binario statico, dato che porta con sé il servizio systemd e la configurazione predefinita. Il repository è ospitato su Cloudsmith e ha due rami: stable, usato qui, e testing, che comprende beta e release candidate.

Il primo comando installa i portachiavi Debian, il supporto HTTPS per APT e curl.

sudo apt install --yes debian-keyring debian-archive-keyring apt-transport-https curl

I due comandi successivi scaricano da dl.cloudsmith.io la chiave GPG del repository e il file con l’elenco delle sorgenti, e li scrivono con i privilegi di root in /usr/share/keyrings/ e in /etc/apt/sources.list.d/. Non eseguono script, ma da quel momento APT si fida dei pacchetti firmati con quella chiave: per questo gli indirizzi vanno copiati esattamente come sono, senza modificarli.

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

I due chmod che seguono cambiano i permessi soltanto di quei due file, non di intere cartelle: aggiungono la lettura per gli altri utenti, così che APT possa leggerli.

sudo chmod o+r /usr/share/keyrings/caddy-stable-archive-keyring.gpg

sudo chmod o+r /etc/apt/sources.list.d/caddy-stable.list

Resta da aggiornare l’elenco dei pacchetti e installare Caddy.

sudo apt update

sudo apt install caddy

Se apt update si chiude senza errori sulla riga di Cloudsmith e l’installazione termina regolarmente, il pacchetto è al suo posto. L’installazione avvia subito Caddy come servizio systemd chiamato caddy. C’è anche un secondo servizio, caddy-api, non abilitato, pensato per chi configura Caddy tramite API anziché con il Caddyfile.

Controllare che il servizio sia attivo e parta all’avvio

Il gestore di servizi, spiega la documentazione di Caddy, fa ripartire il programma al riavvio della macchina e ne raccoglie i log. Prima di toccare la configurazione si controlla quindi lo stato del servizio.

systemctl status caddy

L’output indica se il servizio è attivo e il percorso del file di servizio in uso. Se risultasse fermo o disabilitato, lo si abilita e avvia con un solo comando:

sudo systemctl enable --now caddy

Scrivere il Caddyfile con un sottodominio per servizio

Il servizio legge la configurazione da /etc/caddy/Caddyfile, che si apre con un editor qualsiasi; qui si usa nano.

sudo nano /etc/caddy/Caddyfile

Il file contiene la configurazione predefinita del pacchetto: la si sostituisce con i blocchi dei siti da pubblicare.

La logica, secondo la pagina sul Caddyfile, è scrivere prima l’indirizzo del sito e poi le funzioni che gli servono. Nel quick-start sul reverse proxy l’esempio si riduce a due righe: il nome del dominio e, sotto, reverse_proxy seguito dalla porta del servizio locale. Con più servizi ogni sito ha il proprio blocco fra parentesi graffe, come nell’esempio della pagina Caddyfile. Per due servizi, uno sulla porta 8080 e uno sulla 9000, il file contiene due blocchi, uno sotto l’altro e separati da una riga vuota:

1. il primo blocco apre con app.example.com {, ha nella riga sotto reverse_proxy :8080 e si chiude con } su una riga a sé;
2. il secondo apre con foto.example.com {, ha nella riga sotto reverse_proxy :9000 e si chiude allo stesso modo con }.

Al posto di app.example.com e foto.example.com vanno i sottodomini per cui sono stati creati i record DNS, e al posto di :8080 e :9000 le porte su cui ascoltano davvero i servizi, che si leggono nella loro configurazione. Per aggiungere un terzo servizio si ripete lo schema con un nuovo blocco. Il nome del sito non va preceduto da http://, perché quel prefisso disattiva l’HTTPS automatico per quel sito.

Chi ha seguito le guide di opengeek su Nextcloud, Immich, Vaultwarden o Forgejo indica qui la porta configurata in quelle installazioni; impostazioni specifiche per i singoli programmi non rientrano nella documentazione di Caddy e qui non si aggiungono. Si salva e si esce da nano con le scorciatoie indicate in fondo alla schermata.

Applicare la configurazione e leggere i log

Prima di ricaricare vale un’avvertenza della pagina Automatic HTTPS: le autorità di certificazione applicano limiti di frequenza, e chi fa molte prove rischia di vedersi bloccato l’HTTPS fino a una settimana. Per gli esperimenti la stessa pagina consiglia l’ambiente di staging di Let’s Encrypt, che non ha gli stessi limiti; configurarlo esce però dallo scopo di questa guida. Caddy interrompe le richieste di certificato in corso quando la configurazione cambia, per cui conviene, come suggerisce la documentazione, raccogliere le modifiche e ricaricare una volta sola, lasciandogli il tempo di finire.

sudo systemctl reload caddy

Il ricaricamento è graduale: Caddy legge il nuovo Caddyfile e, per ogni nome pubblico, chiede il certificato a Let’s Encrypt; se non lo ottiene passa a ZeroSSL. Dato che la gestione dei certificati avviene in background, il servizio risulta attivo anche prima che i certificati siano arrivati. Si ricontrolla lo stato:

systemctl status caddy

Errori di sintassi nel Caddyfile o problemi nell’emissione dei certificati finiscono nel journal. Il comando seguente mostra i log completi senza troncare le righe e si posiziona sulle più recenti; si esce premendo q.

journalctl -u caddy --no-pager | less +G

Verificare l’HTTPS da una rete esterna

La prova va fatta da fuori, perché dalla rete di casa non si verifica che porte e inoltri funzionino davvero. Da un dispositivo collegato a un’altra rete, per esempio il telefono con i dati mobili e il Wi-Fi spento, si apre nel browser https:// seguito dal sottodominio e si controlla, dal lucchetto nella barra degli indirizzi, che il certificato risulti valido e rilasciato per quel nome. Chi digita l’indirizzo con http:// viene reindirizzato in HTTPS da Caddy stesso.

Avviso di sicurezza: un servizio raggiungibile da internet è raggiungibile da chiunque. Va tenuto aggiornato e protetto con password robuste, perché il certificato cifra la connessione ma non protegge un programma vecchio o un account con una password debole.

Fermare, riavviare o disattivare Caddy

I comandi che seguono interrompono, nel caso del riavvio solo per poco, l’accesso a tutti i servizi pubblicati attraverso Caddy: nessun sottodominio risponde finché il servizio non torna attivo. Per fermarlo:

sudo systemctl stop caddy

Il riavvio completo la documentazione lo indica dopo aver modificato le impostazioni del servizio systemd con un file «drop-in»; per le modifiche al Caddyfile basta il reload visto sopra.

sudo systemctl restart caddy

Per fermarlo e impedire che riparta all’avvio:

sudo systemctl disable --now caddy

Un comando di disinstallazione per Debian e Ubuntu non è indicato nella documentazione di Caddy. Per togliere il programma si rimuove il pacchetto caddy con il gestore dei pacchetti, poi si cancellano il file caddy-stable.list in /etc/apt/sources.list.d/ e la chiave caddy-stable-archive-keyring.gpg in /usr/share/keyrings/, così che APT smetta di interrogare il repository. Le fonti non dicono se la rimozione del pacchetto cancelli anche i dati in /var/lib/caddy, dove stanno certificati e chiavi private: quella cartella va controllata a mano.

Se qualcosa va storto

• Il certificato non arriva. Caddy riprova una volta dopo una breve pausa, poi passa all’altro tipo di sfida, poi all’altro emittente (da Let’s Encrypt a ZeroSSL); se falliscono tutti, distanzia i tentativi in modo esponenziale, al massimo un giorno fra l’uno e l’altro, per un periodo fino a 30 giorni. Il motivo dell’errore si legge nei log; le condizioni da ricontrollare sono il record DNS che punta all’IP pubblico e le porte 80 e 443 raggiungibili da fuori.
• Troppe prove ravvicinate. I limiti di frequenza delle autorità possono bloccare l’HTTPS fino a una settimana. Durante i tentativi con Let’s Encrypt, Caddy passa da solo al loro ambiente di staging per contenere il problema.
• Il nome non è idoneo. localhost, i nomi che finiscono in .localhost, .local, .internal o .home.arpa e gli indirizzi IP non ricevono un certificato pubblico: Caddy li serve con un certificato della propria autorità locale, che gli altri dispositivi riconoscono solo se vi si installa il certificato radice di Caddy.
• Problemi di archiviazione. Prima di ogni richiesta Caddy verifica che lo spazio dei dati sia scrivibile e abbia capacità sufficiente; con la configurazione predefinita la cartella $HOME dell’utente caddy deve essere scrivibile e persistente.

Documentazione di riferimento

Pagine ufficiali consultate il 24 ottobre 2026:

• Caddy — Install
• Caddy — Keep Caddy Running
• Caddy — Reverse proxy quick-start
• Caddy — Automatic HTTPS
• Caddy — The Caddyfile

Leggi anche

• Vaultwarden Docker Compose con HTTPS: installarlo su Linux con Caddy
• Tailscale: come raggiungere la rete di casa da fuori senza aprire porte