Che cos'è un Caddyfile e come si scrive?

Vuoi che il tuo sito venga caricato tramite HTTPS, che punti all'app corretta e che tu non debba imparare un linguaggio completamente nuovo solo per pubblicare una pagina web.

In breve: un Caddyfile è il principale file di configurazione di Caddy, un web server in grado di pubblicare siti web, fare da reverse proxy per le applicazioni e gestire automaticamente i certificati HTTPS. Per scrivere un Caddyfile, è sufficiente indicare il dominio e poi dire a Caddy cosa fare con le richieste dirette a quel dominio, ad esempio servire i file contenuti in una cartella oppure inoltrare il traffico a un'applicazione in esecuzione sul server.

Che cos'è un Caddyfile?

Un Caddyfile è un semplice file di testo che indica a Caddy come gestire il traffico web.

Immagina Caddy come il receptionist all'ingresso di un edificio. I visitatori arrivano chiedendo di example.com. Il Caddyfile è il foglio di istruzioni del receptionist: manda questo visitatore allo scaffale delle brochure, accompagna quell'altro all'applicazione al piano di sopra e assicurati che tutti entrino dall'ingresso sicuro.

Caddy è noto per semplificare la gestione di HTTPS. HTTPS è il lucchetto che vedi nel browser e che indica che la connessione è sicura. Con molti web server devi configurare manualmente i certificati. Con Caddy, spesso è sufficiente un semplice blocco relativo al dominio nel Caddyfile perché Caddy richieda e rinnovi automaticamente il certificato al posto tuo.

Questo non significa che il Caddyfile sia magico. È comunque una mappa. Se la mappa indica la cartella sbagliata, la porta sbagliata dell'applicazione o il dominio sbagliato, il sito può comunque smettere di funzionare.

Se devi ancora collegare il dominio al server, inizia dal livello del dominio: come puntare un dominio al tuo server.

Com'è fatto un Caddyfile?

Un Caddyfile di base è composto da blocchi relativi ai siti. Un blocco inizia con il nome del dominio e utilizza le parentesi graffe per definire cosa deve accadere per le richieste dirette a quel dominio.

Per un sito web statico, potrebbe essere simile a questo:

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

In parole semplici, significa:

• quando qualcuno visita example.com
• utilizza /var/www/example come cartella contenente i file del sito
• pubblica quei file come sito web

Per un'applicazione che gira dietro Caddy, il Caddyfile utilizza spesso un reverse proxy. Un reverse proxy è come un receptionist che inoltra il visitatore verso una stanza privata all'interno dell'edificio. Il visitatore vede example.com, mentre Caddy inoltra la richiesta all'applicazione senza che l'utente debba sapere dove si trova realmente.

caddyfileapp.example.com {
    reverse_proxy localhost:3000
}

Questo significa:

• quando qualcuno visita app.example.com
• inoltra la richiesta a un'applicazione in ascolto sulla porta 3000 dello stesso server

È una configurazione comune per applicazioni Node.js, dashboard, piccoli strumenti interni e container. Se vuoi capire meglio come si inserisce Docker in questo scenario, leggi Docker su un server per principianti.

Come si scrive un Caddyfile in modo sicuro?

Inizia con un dominio e un solo obiettivo.

Un Caddyfile diventa difficile da gestire quando cerca di fare troppe cose contemporaneamente. Pensalo come alle targhette sulle stanze di una casa. Prima indica la cucina. Poi lo studio. Poi il garage. Non iniziare disegnando tutte le tubature e i cavi.

Un buon Caddyfile di partenza dovrebbe rispondere a tre domande:

1. Per quale dominio è questa configurazione?
2. Caddy deve servire dei file oppure inoltrare il traffico a un'applicazione?
3. Dove si trovano esattamente quei file o quell'applicazione?

Per un normale sito web, la risposta potrebbe essere: "servi i file contenuti in questa cartella". Per una web app, potrebbe essere: "inoltra il traffico a questa porta locale".

Mantieni nomi semplici e facilmente riconoscibili. Se il progetto si chiama notes, utilizza cartelle e commenti che facciano riferimento a notes. Tra qualche mese non ricorderai che project-new-final-2 era quello importante.

È inoltre consigliabile mantenere separato ogni blocco relativo a un sito. Se ospiti più domini sullo stesso server, ogni dominio dovrebbe avere una sezione chiara e indipendente. In questo modo è meno probabile che un progetto venga compromesso quando modifichi la configurazione di un altro. È particolarmente importante quando ospiti più siti sulla stessa macchina: l'obiettivo è evitare un unico file intricato in cui ogni modifica diventa rischiosa.

Cosa può andare storto con un Caddyfile?

La maggior parte dei problemi legati ai Caddyfile non è particolarmente grave. Si tratta spesso di piccole incongruenze.

Il dominio potrebbe non puntare ancora al server. In questo caso Caddy potrebbe funzionare perfettamente, ma i visitatori non riescono comunque a raggiungerlo. Il DNS, ovvero la rubrica degli indirizzi di Internet, deve prima indirizzare il dominio verso il posto giusto perché Caddy possa fare il suo lavoro.

L'applicazione potrebbe non essere in esecuzione sulla porta indicata in reverse_proxy. Se il Caddyfile dice localhost:3000 ma l'applicazione è effettivamente disponibile su localhost:8080, Caddy sta semplicemente bussando alla porta sbagliata.

Anche il percorso della cartella potrebbe essere errato. Un blocco per un sito statico può essere scritto perfettamente, ma se root punta a una cartella vuota, i visitatori non vedranno il sito che ti aspettavi.

Anche HTTPS può non funzionare se il dominio non è raggiungibile da Internet, se alcune porte sono bloccate oppure se sono rimaste configurazioni obsolete relative ai certificati. Caddy automatizza gran parte del lavoro, ma ha comunque bisogno che il mondo esterno possa raggiungere correttamente il server. Per una panoramica più completa, consulta come ottenere HTTPS gratuito sul tuo server.

Quando qualcosa non funziona, il messaggio di errore esatto è importante. Messaggi del browser come ERR_CONNECTION_REFUSED, SSL_ERROR_INTERNAL_ERROR_ALERT o i messaggi nei log di Caddy relativi al rilascio dei certificati sono indizi, non semplici dettagli tecnici. I log sono il taccuino che racconta cosa ha provato a fare Caddy; se non hai ancora familiarità con questo tipo di informazioni, leggi come leggere i log del server quando qualcosa non funziona.

FAQ

Un Caddyfile è la stessa cosa di Caddy? No. Caddy è il web server. Il Caddyfile è uno dei modi con cui puoi configurare Caddy.

Dove viene salvato il Caddyfile? Dipende da come è stato installato Caddy, ma il concetto importante è che Caddy legge questo file per sapere come gestire e instradare il traffico.

Ho bisogno di un Caddyfile per HTTPS? Spesso sì. Il Caddyfile indica a Caddy per quali domini deve gestire HTTPS.

Un singolo Caddyfile può gestire più siti web? Sì. Puoi aggiungere blocchi separati per domini diversi, purché ogni blocco rimanga chiaro e ben organizzato.

Caddy è più semplice di nginx? Per molti siti e applicazioni di piccole dimensioni, sì, soprattutto perché Caddy gestisce automaticamente HTTPS. È comunque importante mantenere una configurazione ordinata.

La scorciatoia

Server Manager ti aiuta a mantenere sotto controllo tutti gli elementi coinvolti: quale dominio appartiene a quale progetto, dove deve essere indirizzato il traffico e se HTTPS fa parte della configurazione. In questo modo eviti i comuni errori nei Caddyfile descritti sopra, come indirizzare un dominio verso la porta sbagliata dell'applicazione, perdere di vista quale cartella serve quale sito oppure lasciare un problema relativo a un certificato nascosto in un file che non apri da mesi.

Il vero vantaggio è che la configurazione rimane comprensibile nel tempo. Quando torni sul server dopo qualche mese per aggiungere un altro sito o risolvere un problema, non devi decifrare un enigma costruito con vecchie modifiche, porte che ricordi a malapena e frammenti di configurazione copiati da altre parti.

Il server e le decisioni rimangono tuoi. Semplicemente, dedichi meno attenzione a mantenere comprensibile il foglio di istruzioni.

Un Caddyfile non è qualcosa da temere. È semplicemente un insieme di istruzioni: questo dominio, questa destinazione, questo tipo di gestione del traffico. Quando questi elementi sono chiari, diventa molto più facile capire come funziona Caddy e, soprattutto, è meno probabile che il tuo sito smetta di funzionare a causa di una piccola incongruenza nascosta.