Guida introduttiva

Benvenuti in Caddy! Questo tutorial esplorerà le basi dell'uso di Caddy e vi aiuterà a familiarizzare con esso a un livello generale.

Obiettivi:

• 🔲 Eseguire il demone
• 🔲 Provare l'API
• 🔲 Fornire una configurazione a Caddy
• 🔲 Testare la configurazione
• 🔲 Creare un Caddyfile
• 🔲 Usare l'adattatore di configurazione
• 🔲 Avviare con una configurazione iniziale
• 🔲 Confrontare JSON e Caddyfile
• 🔲 Confrontare API e file di configurazione
• 🔲 Eseguire in background
• 🔲 Ricaricamento della configurazione senza tempi di inattività

Prerequisiti:

• Competenze di base del terminale / riga di comando
• Competenze di base con editor di testo
• caddy e curl nel vostro PATH

Se avete installato Caddy da un gestore di pacchetti, Caddy potrebbe essere già in esecuzione come servizio. In tal caso, interrompete il servizio prima di seguire questo tutorial.

Iniziamo eseguendolo:

caddy

Oops; senza un sottocomando, il comando caddy visualizza solo il testo di aiuto. Potete usarlo ogni volta che dimenticate cosa fare.

Per avviare Caddy come demone, usate il sottocomando run:

caddy run

Questo comando blocca il terminale a tempo indeterminato, ma cosa sta facendo? Al momento... nulla. Per impostazione predefinita, la configurazione ("config") di Caddy è vuota. Possiamo verificarlo usando l'API di amministrazione in un altro terminale:

curl localhost:2019/config/

Possiamo rendere Caddy utile fornendogli una configurazione. Questo può essere fatto in molti modi, ma inizieremo effettuando una richiesta POST all'endpoint /load usando curl nella sezione successiva.

La vostra prima configurazione

Per preparare la nostra richiesta, dobbiamo creare una configurazione. Nel suo nucleo, la configurazione di Caddy è semplicemente un documento JSON.

Salvate questo contenuto in un file JSON (es. caddy.json):

{
	"apps": {
		"http": {
			"servers": {
				"example": {
					"listen": [":2015"],
					"routes": [
						{
							"handle": [{
								"handler": "static_response",
								"body": "Hello, world!"
							}]
						}
					]
				}
			}
		}
	}
}

Quindi caricatela:

curl localhost:2019/load \
	-H "Content-Type: application/json" \
	-d @caddy.json

Possiamo verificare che Caddy abbia applicato la nostra nuova configurazione con un'altra richiesta GET:

curl localhost:2019/config/

Verificate che funzioni andando su localhost:2015 nel vostro browser o usando curl:

curl localhost:2015
Hello, world!

Se vedete Hello, world!, congratulazioni -- funziona! È sempre una buona idea assicurarsi che la configurazione funzioni come previsto, specialmente prima di passare alla produzione.

Il vostro primo Caddyfile

È stato un bel po' di lavoro solo per un Hello World.

Un altro modo per configurare Caddy è con il Caddyfile. La stessa configurazione che abbiamo scritto sopra in JSON può essere espressa semplicemente come:

:2015

respond "Hello, world!"

Salvate questo contenuto in un file chiamato Caddyfile (senza estensione) nella directory corrente.

Fermate Caddy se è già in esecuzione (Ctrl+C), quindi eseguite:

caddy adapt

O se avete salvato il Caddyfile altrove o lo avete chiamato in modo diverso da Caddyfile:

caddy adapt --config /percorso/del/Caddyfile

Vedrete un output JSON! Cosa è successo?

Abbiamo appena usato un adattatore di configurazione per convertire il nostro Caddyfile nella struttura JSON nativa di Caddy.

Anche se potremmo prendere quell'output ed effettuare un'altra richiesta API, possiamo saltare tutti questi passaggi perché il comando caddy può farlo per noi. Se nella directory corrente è presente un file chiamato Caddyfile e non è specificata altra configurazione, Caddy caricherà il Caddyfile, lo adatterà per noi e lo eseguirà immediatamente.

Ora che c'è un Caddyfile nella cartella corrente, eseguiamo di nuovo caddy run:

caddy run

O se il vostro Caddyfile è altrove:

caddy run --config /percorso/del/Caddyfile

(Se si chiama in un altro modo che non inizia con "Caddyfile", dovrete specificare --adapter caddyfile.)

Potete ora provare a caricare nuovamente il vostro sito e vedrete che funziona!

Come potete vedere, ci sono diversi modi per avviare Caddy con una configurazione iniziale:

• Un file chiamato Caddyfile nella directory corrente
• Il flag --config (opzionalmente con il flag --adapter)
• Il flag --resume (se una configurazione è stata caricata in precedenza)

JSON vs. Caddyfile

Ora sapete che il Caddyfile viene semplicemente convertito in JSON per voi.

Il Caddyfile sembra più facile del JSON, ma dovreste usarlo sempre? Ci sono pro e contro per ogni approccio. La risposta dipende dalle vostre esigenze e dal caso d'uso.

Dovrete decidere quale sia il migliore per il vostro caso d'uso.

È importante notare che sia JSON che il Caddyfile (e qualsiasi altro adattatore di configurazione supportato) possono essere utilizzati con l'API di Caddy. Tuttavia, ottenete l'intera gamma di funzionalità e caratteristiche API di Caddy se utilizzate JSON. Se utilizzate un adattatore di configurazione, l'unico modo per caricare o modificare la configurazione con l'API è l'endpoint /load.

API vs. File di configurazione

Dovrete anche decidere se il vostro flusso di lavoro debba essere basato su API o su CLI. (È possibile usare sia l'API che i file di configurazione sullo stesso server, ma non lo raccomandiamo: meglio avere un'unica fonte di verità.)

La scelta tra flusso di lavoro API o file di configurazione è ortogonale all'uso degli adattatori di configurazione: potete usare JSON ma memorizzarlo in un file e usare l'interfaccia a riga di comando; viceversa, potete anche usare il Caddyfile con l'API.

Ma la maggior parte delle persone userà le combinazioni JSON+API o Caddyfile+CLI.

Come potete vedere, Caddy è adatto per un'ampia varietà di casi d'uso e distribuzioni!

Start, stop, run

Dato che Caddy è un server, viene eseguito a tempo indeterminato. Ciò significa che il vostro terminale non si sbloccherà dopo aver eseguito caddy run finché il processo non viene terminato (solitamente con Ctrl+C).

Sebbene caddy run sia il più comune e solitamente raccomandato (specialmente quando si crea un servizio di sistema!), potete in alternativa usare caddy start per avviare Caddy e farlo girare in background:

caddy start

Questo vi permetterà di usare nuovamente il terminale, il che è comodo in alcuni ambienti interattivi headless.

Dovrete poi interrompere il processo voi stessi, dato che Ctrl+C non lo fermerà per voi:

caddy stop

Oppure usate l'endpoint /stop dell'API.

Ricaricamento della configurazione

Il vostro server può eseguire ricaricamenti/modifiche della configurazione senza tempi di inattività (zero-downtime).

Tutti gli endpoint API che caricano o modificano la configurazione sono sicuri e senza interruzioni.

Quando usate la riga di comando, tuttavia, potreste essere tentati di usare Ctrl+C per fermare il server e poi riavviarlo per applicare la nuova configurazione. Non fatelo: fermare e avviare il server è ortogonale alle modifiche della configurazione e comporterà tempi di inattività.

Invece, usate il comando caddy reload per una modifica della configurazione senza interruzioni:

caddy reload

Questo comando in realtà utilizza semplicemente l'API sotto il cofano. Caricherà e, se necessario, adatterà il vostro file di configurazione in JSON, quindi sostituirà gradualmente la configurazione attiva senza tempi di inattività.

Se si verificano errori nel caricamento della nuova configurazione, Caddy ripristina l'ultima configurazione funzionante.