Uptime Kuma: monitoraggio open source e self-hosted

Sapere che un sito, un’API o un server non risponde prima che se ne accorgano gli utenti trasforma un disservizio imprevisto in un incidente gestibile. Uptime Kuma è uno strumento di monitoraggio open source e self-hosted che riunisce controlli, notifiche, statistiche e pagine di stato in un’interfaccia semplice da amministrare.

In questa guida vediamo cosa monitora Uptime Kuma, come funziona il controllo push o heartbeat, quando conviene installarlo e dove scaricare la versione ufficiale.

Cos’è Uptime Kuma

Uptime Kuma è un’applicazione open source pensata per controllare la disponibilità e i tempi di risposta dei servizi di rete. È una soluzione self-hosted: viene installata su un server, una VPS, un NAS o un ambiente di laboratorio e conserva localmente configurazioni e storico dei monitor.

Dalla dashboard si definiscono i servizi da verificare, l’intervallo dei controlli, le condizioni che determinano un errore e i canali ai quali inviare l’allarme. Il progetto ufficiale supporta monitor HTTP/HTTPS, TCP, DNS, Ping, WebSocket, query JSON, servizi Docker e controlli push.

Cosa si può monitorare

• Siti e applicazioni web: disponibilità HTTP/HTTPS, codice di risposta, parole chiave e contenuti JSON.
• Server e servizi di rete: porte TCP, Ping e record DNS.
• Container Docker: stato dei servizi eseguiti nell’infrastruttura containerizzata.
• Certificati TLS: informazioni e scadenza del certificato esposto dal servizio.
• Processi non raggiungibili dall’esterno: cron job, backup e script tramite monitor push.

Monitoraggio push e heartbeat

Nei controlli tradizionali è Uptime Kuma a interrogare periodicamente il servizio. Con un monitor push il rapporto si inverte: il processo controllato chiama un URL univoco per comunicare che l’esecuzione è avvenuta correttamente. Se il segnale non arriva entro il tempo previsto, Uptime Kuma genera l’allarme.

È una modalità particolarmente utile per verificare backup notturni, sincronizzazioni, importazioni, elaborazioni pianificate e dispositivi collocati dietro NAT o firewall. Il mancato heartbeat rende visibile un processo che altrimenti potrebbe interrompersi senza produrre errori immediatamente percepibili.

Notifiche via email, Telegram, Slack e webhook

Il progetto dichiara il supporto per oltre 90 servizi di notifica. Tra quelli più utilizzati ci sono email SMTP, Telegram, Slack, Discord, Microsoft Teams, PagerDuty, Gotify, Pushover e webhook personalizzati.

I canali possono essere assegnati ai singoli monitor. È quindi possibile separare gli avvisi informativi dagli incidenti critici, coinvolgere gruppi differenti e ridurre il rumore operativo. Prima della messa in esercizio è importante provare ogni canale e simulare almeno un’interruzione.

Dashboard, storico e pagine di stato

La dashboard mostra stato corrente, latenza, percentuale di disponibilità e cronologia dei controlli. Tag e gruppi aiutano a organizzare ambienti o clienti diversi. Lo storico permette di riconoscere rallentamenti ricorrenti e di disporre di dati oggettivi durante l’analisi di un incidente.

Uptime Kuma consente inoltre di creare pagine di stato pubbliche. Una status page comunica agli utenti quali servizi sono disponibili e quali stanno subendo un’interruzione o una manutenzione, riducendo le richieste ripetitive durante un problema.

Perché scegliere il self-hosting

Con il self-hosting l’organizzazione controlla infrastruttura, aggiornamenti, accessi e dati di monitoraggio. Non esistono limiti commerciali al numero di monitor, ma la gestione operativa resta a carico di chi installa il servizio: servono backup, aggiornamenti, protezione dell’account, HTTPS e controllo delle risorse.

Il sistema di monitoraggio non dovrebbe dipendere esclusivamente dall’infrastruttura che deve sorvegliare. Quando possibile, è preferibile collocare Uptime Kuma su un host o una rete indipendente.

Installare Uptime Kuma con Docker

La documentazione ufficiale propone Docker Compose come percorso rapido. Il file Compose viene scaricato direttamente dal repository del progetto:

mkdir uptime-kuma
cd uptime-kuma
curl -o compose.yaml https://raw.githubusercontent.com/louislam/uptime-kuma/master/compose.yaml
docker compose up -d

L’interfaccia usa normalmente la porta 3001. In produzione è opportuno limitarne l’esposizione, pubblicarla dietro un reverse proxy HTTPS e conservare /app/data su un filesystem locale compatibile con i lock POSIX. La documentazione ufficiale sconsiglia NFS per i dati applicativi.

Download ufficiale di Uptime Kuma

Codice sorgente, note di rilascio e pacchetti disponibili sono pubblicati esclusivamente nel repository ufficiale del progetto. Verificare sempre versione, requisiti e istruzioni di migrazione prima di aggiornare un’installazione esistente.

Per l’installazione e l’aggiornamento consultare anche la guida ufficiale di Uptime Kuma.

Quando Uptime Kuma è la scelta giusta

Uptime Kuma è adatto a sviluppatori, sistemisti, team DevOps, organizzazioni e PMI che desiderano un monitoraggio semplice, estensibile e privo di costi di licenza. Per infrastrutture soggette a requisiti avanzati di correlazione, alta disponibilità o conservazione a lungo termine, va inserito in una strategia più ampia che comprenda log centralizzati, metriche, tracing e procedure di gestione degli incidenti.

Conclusioni

Uptime Kuma rende accessibili funzioni essenziali di uptime monitoring: controlli di rete, heartbeat, notifiche, storico e status page. La possibilità di ospitarlo sulla propria infrastruttura offre controllo e flessibilità, a condizione di gestire correttamente sicurezza, backup e aggiornamenti. È un ottimo punto di partenza per sapere rapidamente quando un servizio smette di funzionare e intervenire prima che il problema raggiunga gli utenti.