A Project Store Forum GitHub Theme: System
Download Sponsor

Mantenere Caddy in esecuzione

Sebbene Caddy possa essere eseguito direttamente tramite la sua interfaccia a riga di comando, l'uso di un gestore di servizi per mantenerlo in esecuzione offre numerosi vantaggi, come garantire l'avvio automatico al riavvio del sistema e catturare i log di stdout/stderr.

Servizio Linux

Il modo raccomandato per eseguire Caddy su distribuzioni Linux dotate di systemd è utilizzare i nostri file di unità systemd ufficiali.

File di unità

Forniamo due diversi file di unità systemd tra cui scegliere, a seconda del vostro caso d'uso:

  • caddy.service se configurate Caddy con un Caddyfile. Se preferite utilizzare un adattatore di configurazione diverso o un file di configurazione JSON, potete effettuare l'override dei comandi ExecStart e ExecReload.

  • caddy-api.service se configurate Caddy esclusivamente tramite la sua API. Questo servizio utilizza l'opzione --resume che avvierà Caddy utilizzando il file autosave.json, il quale viene mantenuto per impostazione predefinita.

Sono molto simili, ma differiscono nei comandi ExecStart e ExecReload per adattarsi ai diversi flussi di lavoro.

Se dovete passare da un servizio all'altro, dovreste disabilitare e fermare quello precedente prima di abilitare e avviare l'altro. Ad esempio, per passare dal servizio caddy al servizio caddy-api:

sudo systemctl disable --now caddy
sudo systemctl enable --now caddy-api

Installazione manuale

Alcuni metodi di installazione configurano automaticamente Caddy per l'esecuzione come servizio. Se avete scelto un metodo che non lo prevede, potete seguire queste istruzioni per farlo:

Requisiti:

Spostate il binario di caddy nel vostro $PATH, ad esempio:

sudo mv caddy /usr/bin/

Verificate che funzioni:

caddy version

Create un gruppo chiamato caddy:

sudo groupadd --system caddy

Create un utente chiamato caddy con una home directory scrivibile:

sudo useradd --system \
    --gid caddy \
    --create-home \
    --home-dir /var/lib/caddy \
    --shell /usr/sbin/nologin \
    --comment "Caddy web server" \
    caddy

Se utilizzate un file di configurazione, assicuratevi che sia leggibile dall'utente caddy appena creato.

Successivamente, scegliete un file di unità systemd in base al vostro caso d'uso.

Controllate attentamente le direttive ExecStart e ExecReload. Assicuratevi che la posizione del binario e gli argomenti della riga di comando siano corretti per la vostra installazione! Ad esempio: se utilizzate un file di configurazione, modificate il percorso di --config se è diverso dai valori predefiniti.

Il percorso abituale dove salvare il file del servizio è: /etc/systemd/system/caddy.service

Dopo aver salvato il file del servizio, potete avviarlo per la prima volta con la solita procedura systemctl:

sudo systemctl daemon-reload
sudo systemctl enable --now caddy

Verificate che sia in esecuzione:

systemctl status caddy

Ora siete pronti per usare il servizio!

Uso del servizio

Se utilizzate un Caddyfile, potete modificare la vostra configurazione con nano, vi o il vostro editor preferito:

sudo nano /etc/caddy/Caddyfile

Potete posizionare i file del vostro sito statico in /var/www/html o in /srv. Assicuratevi che l'utente caddy abbia i permessi per leggere i file.

Per verificare che il servizio sia in esecuzione:

systemctl status caddy

Il comando di stato mostrerà anche la posizione del file di servizio attualmente in esecuzione.

Quando si utilizza il nostro file di servizio ufficiale, l'output di Caddy viene reindirizzato a journalctl. Per leggere i log completi ed evitare che le righe vengano troncate:

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

Se utilizzate un file di configurazione, potete ricaricare Caddy gradualmente dopo aver apportato modifiche:

sudo systemctl reload caddy

Potete fermare il servizio con:

sudo systemctl stop caddy

Il processo Caddy verrà eseguito come utente caddy, che ha la sua $HOME impostata su /var/lib/caddy. Ciò significa che:

HTTPS locale con systemd

Quando utilizzate Caddy per lo sviluppo locale con HTTPS, potreste usare un hostname come localhost o app.localhost. Questo abilita l'HTTPS locale utilizzando la CA locale di Caddy per emettere certificati.

Poiché Caddy viene eseguito come utente caddy quando agisce come servizio, non avrà i permessi per installare il suo certificato CA radice nell'archivio di fiducia del sistema. Per farlo, eseguite sudo caddy trust per completare l'installazione.

Se volete che altri dispositivi si connettano al vostro server quando utilizzate l'emittente internal, dovrete installare il certificato CA radice anche su quei dispositivi. Potete trovare il certificato CA radice in /var/lib/caddy/.local/share/caddy/pki/authorities/local/root.crt. Molti browser web ora utilizzano il proprio archivio di fiducia (ignorando quello del sistema), quindi potrebbe essere necessario installare il certificato manualmente anche lì.

Override

Il modo migliore per effettuare l'override di aspetti dei file di servizio è con questo comando:

sudo systemctl edit caddy

Questo aprirà un file vuoto con il vostro editor di testo predefinito del terminale nel quale potrete sovrascrivere o aggiungere direttive alla definizione dell'unità. Questo è chiamato file "drop-in".

Variabili d'ambiente

Se avete bisogno di definire variabili d'ambiente da usare nella vostra configurazione, potete farlo in questo modo:

[Service]
Environment="CF_API_TOKEN=super-secret-cloudflare-tokenvalue"

Allo stesso modo, se preferite mantenere un file separato per le variabili d'ambiente (envfile), potete utilizzare la direttiva EnvironmentFile così:

[Service]
EnvironmentFile=/etc/caddy/.env

Quindi il vostro file /etc/caddy/.env potrebbe apparire così (non usate le virgolette " attorno ai valori):

CF_API_TOKEN=super-secret-cloudflare-tokenvalue

Override di run e reload

Se dovete cambiare il file di configurazione da quello predefinito (Caddyfile) per usarne uno JSON (notate che le direttive Exec* devono essere resettate con stringhe vuote prima di impostare un nuovo valore):

[Service]
ExecStart=
ExecStart=/usr/bin/caddy run --environ --config /etc/caddy/caddy.json
ExecReload=
ExecReload=/usr/bin/caddy reload --config /etc/caddy/caddy.json

Riavvio in caso di crash

Se volete che Caddy si riavvii da solo dopo 5 secondi in caso di crash imprevisto:

[Service]
# Riavvia automaticamente caddy in caso di crash, a meno che il codice di uscita non sia 1
RestartPreventExitStatus=1
Restart=on-failure
RestartSec=5s

Quindi, salvate il file, uscite dall'editor e riavviate il servizio per rendere effettive le modifiche:

sudo systemctl restart caddy

Considerazioni su SELinux

Sui sistemi con SELinux abilitato avete due opzioni:

  1. Installare Caddy utilizzando il repository COPR. Il file systemd e il binario caddy saranno già creati ed etichettati correttamente (quindi potete ignorare questa sezione). Se desiderate utilizzare una build personalizzata di Caddy, dovrete etichettare l'eseguibile come descritto di seguito.

  2. Scaricare Caddy da questo sito o compilarlo con xcaddy. In entrambi i casi, dovrete etichettare i file voi stessi.

I file di unità systemd e i loro eseguibili non verranno eseguiti a meno che non siano etichettati rispettivamente con systemd_unit_file_t e bin_t.

L'etichetta systemd_unit_file_t viene applicata automaticamente ai file creati in /etc/systemd/..., quindi assicuratevi di creare lì il vostro file caddy.service, come da istruzioni per l'installazione manuale.

Per etichettare il binario caddy, potete usare il seguente comando:

semanage fcontext -a -t bin_t /usr/bin/caddy && restorecon -Rv /usr/bin/caddy

Servizio Windows

Ci sono due modi per eseguire Caddy come servizio su Windows: sc.exe o WinSW.

sc.exe

Per creare il servizio, eseguite:

sc.exe create caddy start= auto binPath= "VOSTRO_PERCORSO\caddy.exe run"

(sostituite VOSTRO_PERCORSO con il percorso effettivo del vostro caddy.exe)

Per avviare:

sc.exe start caddy

Per fermare:

sc.exe stop caddy

WinSW

Installate Caddy come servizio su Windows seguendo queste istruzioni.

Requisiti:

  • Il binario caddy.exe che avete scaricato o compilato dai sorgenti
  • Qualsiasi .exe dall'ultima release del wrapper di servizio WinSW (la configurazione del servizio qui sotto è scritta per le versioni v2.x)

Mettete tutti i file in una directory del servizio. Negli esempi seguenti, utilizziamo C:\caddy.

Rinominate il file WinSW-x64.exe in caddy-service.exe.

Aggiungete un file caddy-service.xml nella stessa directory:

<service>
  <id>caddy</id>
  <!-- Nome visualizzato del servizio -->
  <name>Caddy Web Server (alimentato da WinSW)</name>
  <!-- Descrizione del servizio -->
  <description>Caddy Web Server (https://caddyserver.com/)</description>
  <executable>%BASE%\caddy.exe</executable>
  <arguments>run</arguments>
  <log mode="roll-by-time">
    <pattern>yyyy-MM-dd</pattern>
  </log>
</service>

Ora potete installare il servizio usando:

caddy-service install

Potreste voler avviare la Console dei Servizi di Windows per vedere se il servizio è in esecuzione correttamente:

services.msc

Tenete presente che i servizi Windows non possono essere ricaricati, quindi dovete dire direttamente a Caddy di ricaricare:

caddy reload

Il riavvio è possibile tramite i normali comandi dei servizi Windows, ad esempio tramite la scheda "Servizi" di Gestione Attività.

Per personalizzare il wrapper del servizio, consultate la documentazione di WinSW

Docker Compose

Il modo più semplice per iniziare con Docker è utilizzare Docker Compose. Consultate la documentazione su Docker Hub for ulteriori dettagli sull'immagine Docker ufficiale di Caddy.

Configurazione

Per prima cosa, create un file compose.yml (o aggiungete questo servizio al vostro file esistente):

services:
  caddy:
    image: caddy:<version>
    restart: unless-stopped
    ports:
      - "80:80"
      - "443:443"
      - "443:443/udp"
    volumes:
      - ./conf:/etc/caddy
      - ./site:/srv
      - caddy_data:/data
      - caddy_config:/config

volumes:
  caddy_data:
  caddy_config:

Assicuratevi di inserire la <version> dell'immagine con l'ultimo numero di versione, che potete trovare elencato su Docker Hub nella sezione "Tags".

Cosa fa questa configurazione:

  • Utilizza la policy di riavvio unless-stopped per garantire che il container Caddy venga riavviato automaticamente al riavvio della macchina.
  • Si collega alle porte 80 e 443 rispettivamente per HTTP e HTTPS, più 443/udp per HTTP/3.
  • Monta la directory conf che contiene la configurazione del vostro Caddyfile.
  • Monta la directory site per servire i file statici del vostro sito da /srv.
  • Volumi nominati per /data e /config per mantenere informazioni importanti.

Quindi, create un file chiamato Caddyfile come unico file nella directory conf e scrivete la vostra configurazione del Caddyfile.

Se avete file statici da servire, potete posizionarli in una directory site/ accanto alle configurazioni, quindi impostare la root usando root /srv. In caso contrario, potete rimuovere il montaggio del volume /srv.

Se avete bisogno di una build personalizzata di Caddy con dei plugin, seguite le istruzioni per la build Docker per creare un'immagine Docker personalizzata. Create il Dockerfile accanto al vostro compose.yml, quindi sostituite la riga image: nel vostro compose.yml con build: ..

Utilizzo

Successivamente, potete avviare il container:

docker compose up -d

Per ricaricare Caddy dopo aver apportato modifiche al vostro Caddyfile:

docker compose exec -w /etc/caddy caddy caddy reload

Dalla v2.11.0, potete ricaricare usando SIGUSR1, a condizione che Caddy sia stato avviato con caddy run e un file di configurazione:

docker compose kill -sUSR1 caddy

Per vedere i 1000 log più recenti di Caddy e seguirne i nuovi in tempo reale:

docker compose logs caddy -n=1000 -f

HTTPS locale con Docker

Quando utilizzate Docker per lo sviluppo locale con HTTPS, potreste usare un hostname come localhost or app.localhost. Questo abilita l'HTTPS locale utilizzando la CA locale di Caddy per emettere certificati. Ciò significa che i client HTTP al di fuori del container non si fideranno del certificato TLS servito da Caddy. Per risolvere il problema, potete installare il certificato CA radice di Caddy nell'archivio di fiducia del vostro computer host:

docker compose cp \
    caddy:/data/caddy/pki/authorities/local/root.crt \
    /usr/local/share/ca-certificates/root.crt \
  && sudo update-ca-certificates
docker compose cp \
    caddy:/data/caddy/pki/authorities/local/root.crt \
    /tmp/root.crt \
  && sudo security add-trusted-cert -d -r trustRoot \
    -k /Library/Keychains/System.keychain /tmp/root.crt
docker compose cp \
    caddy:/data/caddy/pki/authorities/local/root.crt \
    %TEMP%/root.crt \
  && certutil -addstore -f "ROOT" %TEMP%/root.crt

Molti browser web ora utilizzano il proprio archivio di fiducia (ignorando quello del sistema), quindi potrebbe essere necessario installare il certificato manualmente anche lì, utilizzando il file root.crt copiato dal container nel comando sopra.

  • Per Firefox, andate in Preferenze > Privacy e sicurezza > Certificati > Mostra certificati > Autorità > Importa, e selezionate il file root.crt.

  • For Chrome, andate in Impostazioni > Privacy e sicurezza > Sicurezza > Gestisci certificati > Autorità > Importa, e selezionate il file root.crt.