IT

Applicazioni

Monitorare i propri servizi con Uptime Kuma

Installa Uptime Kuma con Docker Compose su Debian o Ubuntu, proteggi l'accesso in HTTPS, crea i tuoi monitor e le tue notifiche, poi gestisci aggiornamenti e backup.

10 min di lettura, aggiornato il 18 novembre 2026

In questa pagina

I tuoi valori

Inseriscili una volta: i comandi della guida si aggiornano.

Uptime Kuma è uno strumento di monitoraggio self-hosted. Controlla regolarmente i tuoi siti, le tue porte e i tuoi servizi, conserva lo storico della loro disponibilità e ti avvisa in caso di guasto.

Al termine di questa guida, Uptime Kuma gira in Docker, ascolta solo sull'indirizzo locale del server e risponde in HTTPS dietro Caddy, con un accesso protetto. Avrai creato un primo monitor e una notifica, e saprai aggiornare l'istanza ed eseguirne il backup.

Ordina un Server

Questa guida si applica ai server che amministri tu stesso:

Prerequisiti

  • Un server con Debian 12 o 13, oppure Ubuntu 22.04 o 24.04
  • Un accesso SSH con un utente che dispone di sudo
  • Docker Engine e Docker Compose, installati con la guida Installare Docker Engine e Docker Compose
  • Caddy, installato con la guida Caddy come reverse proxy
  • Un record A per uptime.tuo-dominio.com verso IP_DEL_TUO_SERVER
  • Un disco locale per i dati: le condivisioni di rete come NFS non sono supportate

I comandi docker presuppongono che il tuo utente appartenga al gruppo docker. In caso contrario, aggiungi sudo davanti.

Questa guida usa la versione 2.5.12, l'ultima versione stabile al momento della stesura. Controlla la versione attuale nella pagina delle versioni di Uptime Kuma. Il ramo 3 è ancora in beta: non usarlo in produzione.

Porte utilizzate

Porta Direzione Ruolo Da aprire
80/tcp In entrata Certificato e reindirizzamento a HTTPS, tramite Caddy Sì
443/tcp In entrata Accesso HTTPS, tramite Caddy Sì
3001/tcp Locale Interfaccia di Uptime Kuma, su 127.0.0.1 No

Il server deve anche poter raggiungere, in uscita, i servizi monitorati e i tuoi servizi di notifica.

Passo 1: creare il progetto Compose

Terminale
sudo mkdir -p /opt/uptime-kuma
sudo chown "$USER": /opt/uptime-kuma
cd /opt/uptime-kuma
nano compose.yaml

Incolla questa configurazione:

YAML
services:
  uptime-kuma:
    image: louislam/uptime-kuma:2.5.12
    container_name: uptime-kuma
    restart: unless-stopped
    ports:
      - "127.0.0.1:3001:3001"
    volumes:
      - ./data:/app/data

Avvia il container:

Terminale
docker compose config --quiet
docker compose up -d
docker compose ps

Il container deve risultare avviato (Up). Il suo controllo di integrità può restare nello stato starting durante i primi minuti.

Passo 2: creare l'account tramite un tunnel SSH

Il primo visitatore crea l'account amministratore. Fallo quindi prima di pubblicare il sito. In un terminale sul tuo computer:

Terminale
ssh -N -L 3001:127.0.0.1:3001 TUO_USER@IP_DEL_TUO_SERVER

Il comando resta attivo senza mostrare nulla. Apri poi http://localhost:3001, quindi:

  1. Scegli la tua lingua.
  2. Seleziona il database SQLite, adatto a un'installazione di dimensioni contenute.
  3. Attendi la preparazione del database.
  4. Crea l'account amministratore con una password lunga e unica.

Passo 3: rafforzare l'account

In Settings (Impostazioni):

Sezione Impostazione Valore
Security 2FA Settings Attiva l'autenticazione a due fattori con un'applicazione TOTP
Security Disable Auth Non attivarla
Reverse Proxy Trust Proxy Yes, perché il servizio è raggiungibile solo tramite Caddy

Trust Proxy permette di mostrare nei log il vero indirizzo dei visitatori. Attiva questa opzione solo se la porta 3001 resta limitata a 127.0.0.1.

Passo 4: pubblicare l'interfaccia con Caddy

Scegli la modalità adatta al tuo utilizzo.

Accesso limitato al tuo indirizzo (consigliato)

Solo il tuo indirizzo IP raggiunge l'interfaccia. Gli URL /api/push/ restano accessibili, così le tue attività pianificate possono inviare i loro segnali. Aggiungi questo sito in /etc/caddy/Caddyfile:

caddyfile
uptime.tuo-dominio.com {
	@push path /api/push/*
	@allowed client_ip TUO_IP

	handle @push {
		reverse_proxy 127.0.0.1:3001
	}

	handle @allowed {
		reverse_proxy 127.0.0.1:3001
	}

	handle {
		abort
	}
}

Se il tuo indirizzo cambia spesso, passa piuttosto da WireGuard o Tailscale.

Accesso pubblico con pagina di stato

Una pagina di stato deve restare visibile ai tuoi utenti. In questo caso, anche l'interfaccia di accesso è raggiungibile: l'autenticazione a due fattori del passo 3 diventa indispensabile.

caddyfile
uptime.tuo-dominio.com {
	reverse_proxy 127.0.0.1:3001
}

Applicare la configurazione

Caddy inoltra da solo i WebSocket di cui Uptime Kuma ha bisogno. Poiché Caddy è installato sul server e non in Docker, UFW si applica alle sue porte:

Terminale
sudo ufw allow 80,443/tcp comment 'Caddy'
sudo -u caddy caddy validate --config /etc/caddy/Caddyfile --adapter caddyfile
sudo systemctl reload caddy

Verificare il risultato

Puoi chiudere il tunnel con Ctrl+C. Apri https://uptime.tuo-dominio.com: deve comparire la pagina di accesso con un certificato valido. Sul server, controlla la porta:

Terminale
docker ps --filter name=uptime-kuma --format '{{.Names}} {{.Status}} {{.Ports}}'

L'output deve contenere 127.0.0.1:3001->3001/tcp. Da un'altra macchina, la porta 3001 non deve essere aperta:

Terminale
nmap -Pn -p 3001 IP_DEL_TUO_SERVER

Con l'accesso limitato, una connessione da un indirizzo diverso dal tuo deve essere interrotta.

Passo 5: aggiungere un primo monitor

  1. Clicca su Add New Monitor.
  2. In Monitor Type, scegli HTTP(s).
  3. Compila Friendly Name, poi inserisci l'indirizzo da monitorare in URL, ad esempio https://www.tuo-dominio.com.
  4. Imposta Heartbeat Interval (l'intervallo tra due controlli) e Retries (il numero di nuovi tentativi prima dell'avviso).
  5. Attiva Certificate Expiry Notification per essere avvisato prima della scadenza del certificato.
  6. Clicca su Save.

I tipi di monitor più utili:

Tipo Utilizzo
HTTP(s) Sito o API, con controllo del codice di risposta
HTTP(s) - Keyword Presenza di una parola nella pagina
TCP Port Servizio in ascolto su una porta, come SSH o un database
Ping Risposta di rete di una macchina
DNS Risoluzione di un nome di dominio
Push Attività pianificata che segnala da sola la propria esecuzione

Monitorare un'attività pianificata

Crea un monitor Push e copia il suo Push URL. Richiamalo alla fine del tuo script, solo se questo riesce:

Terminale
/usr/local/bin/mio-backup.sh && curl -fsS -m 10 --retry 3 "https://uptime.tuo-dominio.com/api/push/TUO_TOKEN?status=up&msg=OK"

Sostituisci TUO_TOKEN con il valore del tuo URL. Se non arriva alcun segnale entro il tempo previsto, il monitor passa allo stato DOWN. Considera questo URL un segreto.

Passo 6: configurare le notifiche

Apri Settings > Notifications, poi clicca su Set Up Notification. Uptime Kuma supporta numerosi servizi. L'esempio seguente usa Telegram:

  1. In Telegram, scrivi a @BotFather, invia /newbot e copia il token ottenuto.
  2. Invia un messaggio al tuo nuovo bot.
  3. In Uptime Kuma, scegli Telegram in Notification Type.
  4. Incolla il token in Bot Token.
  5. Clicca su Auto Get per compilare Chat ID.
  6. Attiva Default enabled per applicarla ai prossimi monitor, e Apply on all existing monitors per quelli già esistenti.
  7. Clicca su Test. Se il messaggio arriva, clicca su Save.

Per un'e-mail, scegli Email (SMTP) e inserisci i parametri forniti dal tuo servizio di posta, preferibilmente con un account dedicato.

Una notifica funziona solo se è associata al monitor. Verificalo nella colonna Notifications della scheda di ogni monitor.

Creare una pagina di stato

In Status Pages, clicca su New Status Page, scegli un nome e un indirizzo, poi aggiungi i monitor da mostrare. La pagina diventa accessibile su /status/nome-scelto. È pensata per essere pubblica e i suoi dati vengono memorizzati nella cache per 5 minuti.

Con l'accesso limitato del passo 4, sarà visibile solo dal tuo indirizzo. Per renderla pubblica, usa il secondo blocco Caddy.

Aggiornare Uptime Kuma

Esegui prima il backup della cartella data e leggi le note di rilascio. Sostituisci poi il tag in compose.yaml, quindi esegui:

Terminale
cd /opt/uptime-kuma
nano compose.yaml
docker compose pull
docker compose up -d --force-recreate
docker compose ps

Resta sul ramo 2 finché non hai letto la guida alla migrazione alla versione 3. Questa migrazione modifica il database e non consente di tornare indietro senza un backup.

Backup e ripristino

La cartella data è l'unico elemento di cui eseguire il backup, insieme a compose.yaml. È il metodo supportato dal progetto: la vecchia esportazione JSON è stata rimossa nella versione 2.

Terminale
cd /opt/uptime-kuma
mkdir -p backups
docker compose stop
sudo tar -czf "backups/uptime-kuma-$(date +%F).tar.gz" data compose.yaml
docker compose start
sudo chmod 600 backups/*.tar.gz

L'archivio contiene il database, gli account e i token di notifica. Copialo fuori dal server, in una posizione cifrata.

Per ripristinare un archivio, sostituendo AAAA-MM-GG con la sua data:

Terminale
cd /opt/uptime-kuma
docker compose down
sudo mv data "data.vecchio-$(date +%F)"
sudo tar -xzf backups/uptime-kuma-AAAA-MM-GG.tar.gz
docker compose up -d

Usa la stessa versione dell'immagine del backup, o una versione più recente dello stesso ramo.

In caso di problemi

Cannot connect to the socket server

L'interfaccia non riesce ad aprire la connessione WebSocket. Verifica che il container sia in esecuzione e consulta i suoi log:

Terminale
docker compose ps
docker compose logs --tail=50 uptime-kuma

Se un altro proxy, come Cloudflare, si trova davanti a Caddy, verifica che i WebSocket siano attivati e che il nome di dominio originale venga trasmesso correttamente.

Errore 502 con Caddy

Caddy non raggiunge l'applicazione. Verifica la porta locale:

Terminale
curl -I http://127.0.0.1:3001
sudo journalctl -u caddy --no-pager -n 50

Un monitor indica DOWN anche se il servizio risponde

Il controllo parte dal container, la cui rete è diversa da quella del tuo computer. Prova dal container, adattando l'indirizzo:

Terminale
docker exec uptime-kuma node -e "fetch('https://www.tuo-dominio.com').then(r => console.log(r.status)).catch(console.error)"

Verifica anche che il servizio monitorato non blocchi l'indirizzo del server, ad esempio con un firewall o CrowdSec.

Un monitor IPv6 non riesce

Per impostazione predefinita, la rete Docker del container non usa IPv6. Se il servizio è raggiungibile solo in IPv6, aggiungi una rete con IPv6 a compose.yaml:

YAML
services:
  uptime-kuma:
    networks:
      - uptime-kuma-net

networks:
  uptime-kuma-net:
    enable_ipv6: true

Unisci queste chiavi al tuo servizio esistente, poi riesegui docker compose up -d.

I segnali Push non arrivano

Prova l'URL con curl -i dalla macchina che esegue l'attività. Una connessione interrotta indica generalmente che in Caddy manca il blocco @push. La risposta deve contenere "ok":true.

Non arriva alcuna notifica

Usa il pulsante Test e leggi il messaggio di errore. Verifica poi che la notifica sia attivata sul monitor. Per un invio SMTP, controlla l'host, la porta e l'identificativo presso il tuo servizio di posta.

Password persa o autenticazione a due fattori inaccessibile

Esegui il comando adatto, poi segui le istruzioni mostrate:

Terminale
docker exec -it uptime-kuma npm run reset-password
docker exec -it uptime-kuma npm run remove-2fa

database is locked o database danneggiato

Verifica che data si trovi su un disco locale e non su NFS, e che lo spazio su disco sia sufficiente con df -h. Se il database è danneggiato, ripristina il tuo ultimo backup.

port is already allocated

Un altro servizio occupa la porta 3001. Individualo con sudo ss -ltnp | grep ':3001 '. Per cambiare porta, modifica solo la parte sinistra, ad esempio 127.0.0.1:3002:3001, poi adatta Caddy.

Riferimenti