Tutorial sull'API

Questo tutorial vi mostrerà come utilizzare l'API di amministrazione di Caddy, che consente l'automazione in modo programmabile.

Obiettivi:

🔲 Eseguire il demone
🔲 Fornire una configurazione a Caddy
🔲 Testare la configurazione
🔲 Sostituire la configurazione attiva
🔲 Esplorare la configurazione
🔲 Usare i tag @id

Prerequisiti:

Competenze di base del terminale / riga di comando
Esperienza di base con il JSON
caddy e curl nel vostro PATH

Per avviare il demone Caddy, 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. Un modo per farlo è effettuare una richiesta POST all'endpoint /load. Proprio come ogni richiesta HTTP, ci sono molti modi per farlo, ma in questo tutorial useremo curl.

La vostra prima configurazione

Per preparare la nostra richiesta, dobbiamo creare una configurazione. La configurazione di Caddy è semplicemente un documento JSON (o qualsiasi cosa che si converta in JSON).

Salvate questo contenuto in un file 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.

Cambiamo il nostro messaggio di benvenuto da "Hello world!" a qualcosa di un po' più motivazionale: "I can do hard things." (Posso fare cose difficili). Apportate questa modifica nel vostro file di configurazione, in modo che l'oggetto handler appaia ora così:

{
	"handler": "static_response",
	"body": "I can do hard things."
}

Salvate il file di configurazione, quindi aggiornate la configurazione attiva di Caddy eseguendo nuovamente la stessa richiesta POST:

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

Per sicurezza, verificate che la configurazione sia stata aggiornata:

curl localhost:2019/config/

Verificatelo ricaricando la pagina nel vostro browser (o eseguendo nuovamente curl) e vedrete un messaggio d'ispirazione!

Esplorazione della configurazione (Config traversal)

Invece di caricare l'intero file di configurazione per una piccola modifica, utilizziamo una potente funzionalità dell'API di Caddy per effettuare il cambiamento senza mai toccare il nostro file di configurazione.

Usando il percorso dell'URI della richiesta, possiamo esplorare la struttura della configurazione e aggiornare solo la stringa del messaggio (assicuratevi di scorrere a destra se il testo è tagliato):

curl \
	localhost:2019/config/apps/http/servers/example/routes/0/handle/0/body \
	-H "Content-Type: application/json" \
	-d '"Work smarter, not harder."'

Potete verificare che abbia funzionato con una richiesta GET simile, ad esempio:

curl localhost:2019/config/apps/http/servers/example/routes

Dovreste vedere:

[{"handle":[{"body":"Work smarter, not harder.","handler":"static_response"}]}]

Nota importante: Dovrebbe essere ovvio, ma una volta utilizzata l'API per effettuare una modifica che non è nel file di configurazione originale, il vostro file di configurazione diventa obsoleto. Ci sono alcuni modi per gestire questa situazione:

Usate il flag --resume del comando caddy run per utilizzare l'ultima configurazione attiva.
Non mescolate l'uso dei file di configurazione con le modifiche via API; mantenete un'unica fonte di verità.
Esportate la nuova configurazione di Caddy con una successiva richiesta GET (opzione meno raccomandata rispetto alle prime due).

Uso di `@id` in JSON

L'esplorazione della configurazione è certamente utile, ma i percorsi sono un po' lunghi, non trovate?

Possiamo assegnare al nostro oggetto handler un tag @id per renderlo più facile da raggiungere:

curl \
	localhost:2019/config/apps/http/servers/example/routes/0/handle/0/@id \
	-H "Content-Type: application/json" \
	-d '"msg"'

Questo aggiunge una proprietà al nostro oggetto handler: "@id": "msg", che ora appare così:

{
	"@id": "msg",
	"body": "Work smarter, not harder.",
	"handler": "static_response"
}

Possiamo quindi accedervi direttamente:

curl localhost:2019/id/msg

E ora possiamo cambiare il messaggio con un percorso più breve:

curl \
	localhost:2019/id/msg/body \
	-H "Content-Type: application/json" \
	-d '"Some shortcuts are good."'

E controllarlo di nuovo:

curl localhost:2019/id/msg/body

Usare i tag @id