Quando si gestisce un sito web, un servizio API o un server casalingo, sapere se e quando qualcosa va offline è fondamentale.
Uptime-Kuma è una soluzione open-source semplice, leggera e potente per il monitoraggio dell’uptime dei tuoi servizi, completamente self-hosted e altamente personalizzabile.
In questo articolo vedremo come installare e configurare Uptime-Kuma su Ubuntu Server 24.04, l’ultima versione LTS del sistema operativo Linux di Canonical.
Grazie alla sua interfaccia intuitiva e al supporto per notifiche via Telegram, Discord, e-mail e molti altri canali, Uptime-Kuma è lo strumento ideale per chi vuole tenere sotto controllo i propri servizi in modo elegante e senza costi.
Che tu stia utilizzando un VPS, un Raspberry Pi, o un server fisico, questa guida ti accompagnerà passo dopo passo nell’installazione e nella configurazione iniziale, con un focus sulla praticità e sulla sicurezza.
PREREQUISITI
Un server Ubuntu 24.04
Accesso SSH con privilegi root
CREAZIONE UTENZA DI SISTEMA
Come prima cosa creare un utenza di sistema con il comando:
|
0 |
adduser serviceuser |
Successivamente eseguire il comando seguente per aggiungere il nuovo utente al gruppo sudo.
|
0 |
usermod -aG sudo serviceuser |
Una volta creati e dati i privilegi sudo, possiamo accedere come nuovo utente serviceuser e utilizzeremo questo utente per eseguire i comandi e completare l’installazione di Uptime Kuma.
|
0 |
su - serviceuser |
INSTALLAZIONE DI NODEJS E NPM
Kuma richiede l’ambiente di runtime NodeJS e npm. Possiamo installare NodeJS dal repository predefinito di Ubuntu, ma otterremo una versione precedente di NodeJS se utilizziamo questo metodo e Uptime Kuma richiede almeno NodeJS versione 14. In questo passaggio, installeremo NodeJS e npm tramite il repository NodeJS per ottenerne la versione più recente.
Eseguire il comando:
|
0 |
curl -sL https://deb.nodesource.com/setup_lts.x | sudo -E bash - |
Una volta completato, dobbiamo scaricare le informazioni sul pacchetto dalla fonte appena aggiunta sopra.
|
0 |
sudo apt update |
Quindi, eseguire il seguente comando per installare finalmente NodeJS e NPM.
|
0 |
sudo apt install nodejs |
È possibile verificare la versione installata di NodeJs e NPM eseguendo questa riga:
|
0 |
node -v; npm -v |
Dovremmo visualizzare un output come questo:
|
0 |
v22.17.110.9.2 |
INSTALLAZIONE DI UPTIME KUMA
Uptime Kuma non è disponibile nel repository Ubuntu predefinito. Possiamo installarlo scaricandolo da GitHub usando git.
|
0 |
sudo apt install git |
Dopo l’installazione di git, possiamo continuare a clonare Uptime Kuma dal suo repository GitHub con i seguenti comandi:
|
0 |
git clone https://github.com/louislam/uptime-kuma.gitcd uptime-kuma |
È il momento di eseguire l’installazione utilizzando il gestore di pacchetti NPM di Nodejs con il comando:
|
0 |
npm run setup |
Dovremmo visualizzare il seguente output:
|
0 |
npm noticenpm notice New major version of npm available! 10.9.2 -> 11.5.2npm notice Changelog: https://github.com/npm/cli/releases/tag/v11.5.2npm notice To update run: npm install -g npm@11.5.2npm notice |
Possiamo procedere con l’aggiornamento alla versione 11.5.2 con il comando:
|
0 |
npm install -g npm@11.5.2 |
INSTALLAZIONE DI PM2
Con Process Manager (PM2), possiamo mantenere in vita le nostre applicazioni per sempre, ricaricarle senza tempi di inattività e facilitare le comuni attività di amministrazione del sistema.
Eseguire il comando seguente per installare PM2 su Ubuntu 24.04.
|
0 |
sudo npm install pm2 -g |
Una volta installato pm2 eseguire il nostro Uptime Kuma con questo comando.
|
0 |
pm2 start server/server.js --name kuma |
Dovremmo visualizzare il seguente output:
A questo punto aprire una qualsiasi browser web e richiamare l’indirizzo http://TUO_SERVER_IP_ADDRESS:3001
Dovremmo vedere la pagina di benvenuto di Kuma uptime come mostrato nell’immagine sovrastante
Selezionare la lingua quindi creare un account con relativa password e cliccare Create
Se è andato tutto a buon fine dovremmo visualizzare la Dashboard di Uptime-Kuma
AUTOMAZIONE DEI SERVIZI
Dopo aver avviato Uptime Kuma creare un file di servizio per PM2 per fare in modo che Uptime Kuma si avvii automaticamente al riavvio.
Eseguire il comando:
|
0 |
pm2 startup |
Dovremmo visualizzare un output come questo:
|
0 |
[PM2] Init System found: systemd[PM2] To setup the Startup Script, copy/paste the following command:sudo env PATH=$PATH:/usr/bin /usr/lib/node_modules/pm2/bin/pm2 startup systemd -u serviceuser --hp /home/serviceuser |
Basta seguire le istruzioni mostrate sullo schermo ed eseguire il comando:
|
0 |
sudo env PATH=$PATH:/usr/bin /usr/lib/node_modules/pm2/bin/pm2 startup systemd -u serviceuser --hp /home/serviceuser |
Dovremmo visualizzare un output come questo:
|
0 |
Runtime EditionPM2 is a Production Process Manager for Node.js applicationswith a built-in Load Balancer.Start and Daemonize any application:$ pm2 start app.jsLoad Balance 4 instances of api.js:$ pm2 start api.js -i 4Monitor in production:$ pm2 monitorMake pm2 auto-boot at server restart:$ pm2 startupTo go further checkout:http://pm2.io/-------------[PM2] Init System found: systemdPlatform systemdTemplate[Unit]Description=PM2 process managerDocumentation=https://pm2.keymetrics.io/After=network.target[Service]Type=forkingUser=serviceuserLimitNOFILE=infinityLimitNPROC=infinityLimitCORE=infinityEnvironment=PATH=/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin:/usr/games:/usr/local/games:/snap/bin:/usr/bin:/bin:/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/binEnvironment=PM2_HOME=/home/serviceuser/.pm2PIDFile=/home/serviceuser/.pm2/pm2.pidRestart=on-failureExecStart=/usr/lib/node_modules/pm2/bin/pm2 resurrectExecReload=/usr/lib/node_modules/pm2/bin/pm2 reload allExecStop=/usr/lib/node_modules/pm2/bin/pm2 kill[Install]WantedBy=multi-user.targetTarget path/etc/systemd/system/pm2-serviceuser.serviceCommand list[ 'systemctl enable pm2-serviceuser' ][PM2] Writing init configuration in /etc/systemd/system/pm2-serviceuser.service[PM2] Making script booting at startup...[PM2] [-] Executing: systemctl enable pm2-serviceuser...Created symlink /etc/systemd/system/multi-user.target.wants/pm2-serviceuser.service → /etc/systemd/system/pm2-serviceuser.service.[PM2] [v] Command successfully executed.+---------------------------------------+[PM2] Freeze a process list on reboot via:$ pm2 save[PM2] Remove init script via:$ pm2 unstartup systemd |
A questo punto salvare l’attuale processo in corso con il comando:
|
0 |
pm2 save |
Dovremmo visualizzare il seguente output:
|
0 |
[PM2] Saving current process list...[PM2] Successfully saved in /home/serviceuser/.pm2/dump.pm2 |
CONFIGURAZIONE DEL MONITORAGGIO
Collegarsi alla Dashboard di Uptime Kuma
Cliccare su Add New Monitor
Di seguito trovi un elenco completo e aggiornato al 2025 delle principali opzioni disponibili con una breve descrizione per ciascuna.
🖥️ SEZIONE: Tipo di monitoraggio
Quando clicchi su “Aggiungi nuovo monitor”, la prima scelta è:
Tipo di monitor
Seleziona il metodo di monitoraggio tra:
- HTTP(s): Controlla la disponibilità di un sito web via HTTP o HTTPS.
- TCP Port: Controlla se una porta TCP (es. 22, 80, 443) risponde su un host.
- Ping: Usa ICMP per vedere se un host è raggiungibile.
- DNS: Controlla se una query DNS restituisce un valore atteso.
- Push: Aspetta che il monitor venga attivato da una chiamata esterna (es. webhook).
- Steam Game Server: Monitora server di gioco compatibili (es. CS:GO, TF2, etc.).
- MQTT: Verifica se un broker MQTT risponde (utile per IoT).
- Docker: Controlla se un container Docker è attivo.
- WebSocket: Monitora la connessione a un endpoint WebSocket.
- HTTP Keyword: Come HTTP(s), ma cerca una parola chiave specifica nella risposta.
- Radius: Monitora server RADIUS.
- GRPC: Monitora servizi GRPC
🛠️ SEZIONE: Impostazioni comuni (variano a seconda del tipo)
Ecco le impostazioni principali che puoi configurare per ogni monitor:
- Nome: Etichetta visibile nella dashboard.
- URL / Host / IP: L’indirizzo del server/servizio da monitorare (es. https://example.com, 192.168.1.100).
- Porta: (solo per TCP, Docker, MQTT, ecc.) Specifica la porta da monitorare.
- Intervallo (Heartbeat Interval): Tempo in secondi tra un controllo e il successivo. (Default: 60s, minimo consigliato: 20s)
- Timeout: Tempo massimo di attesa per una risposta. (Es: se dopo 10s il sito non risponde, risulta “Down”)
- Ritardi nei tentativi falliti (Retries): Quanti tentativi devono fallire prima di dichiarare un “Down”.
- Parola chiave: (solo in HTTP Keyword): parola/frase da cercare nella risposta.
- Header HTTP personalizzati: Puoi aggiungere intestazioni HTTP (es. User-Agent, Authorization).
- Metodo HTTP: GET, POST, PUT, ecc. (utile se fai health check customizzati).
- Corpo della richiesta: Per i metodi POST/PUT, puoi specificare un corpo (es. JSON).
- Certificato SSL: Può verificare la validità e scadenza del certificato SSL (HTTPS).
- Ignora Errori SSL: Può forzare la connessione anche se il certificato non è valido.
📣 SEZIONE: Notifiche
Notificatori (Notification Channels): Seleziona a quali canali inviare notifiche (Telegram, Discord, email, etc.).
Configurabili da Impostazioni > Notifiche.
📨 Tipologie di notifiche supportate
- Email (SMTP): Invia una email via server SMTP.
- Telegram: Invia messaggi a un bot/utente/gruppo su Telegram.
- Discord: Invia messaggi a un canale Discord via Webhook.
- Slack: Invia notifiche a Slack via Webhook.
- Microsoft Teams: Notifiche in canali Teams via webhook.
- Webhooks: Notifica generica verso qualsiasi URL con payload personalizzato.
- Gotify: Sistema di notifiche self-hosted.
- Pushover: Notifiche su dispositivi mobili via app Pushover.
- Pushbullet: Notifiche push su PC e dispositivi mobili.
- Lark (Feishu): Notifiche su piattaforma di messaggistica asiatica (simile a Slack).
- Line Notify: Notifiche push su Line (app asiatica di messaggistica).
- Mattermost: Invia messaggi a un canale Mattermost.
- Google Chat: Notifiche a spazi Google Chat.
- Signal: Invia notifiche su Signal tramite bridge (come ntfy.sh o signal-cli).
- Matrix: Invia messaggi a stanze Matrix.
- Zulip: Piattaforma di chat simile a Slack, open-source.
- ntfy.sh: Notifiche via pubblicazione su server ntfy.sh (pubblico o self-hosted).
- SMS (via Twilio): Invia SMS tramite API Twilio.
- DingTalk: Messaggistica aziendale cinese.
- Rocket.Chat: Alternativa self-hosted a Slack.
- Opsgenie: Servizio di gestione incidenti (monitoring professionale).
- PagerDuty: Integrazione per alert professionali e DevOps.
- Prometheus AlertManager: Notifiche verso Prometheus Alertmanager.
- LunaSea: Sistema per ricevere notifiche su media server.
- Apprise URL: Supporto per moltissimi servizi via Apprise.
- Email (Sendmail): Notifica via sendmail locale invece di SMTP.
- Bark: Notifiche push su dispositivi Apple (via app Bark).
- WeCom (WeChat Work): Versione aziendale di WeChat.
- Home Assistant: Notifica via webhook o script su Home Assistant.
- iGot: Notifica push asiatica via API.
- SMS (Custom URL): Invia SMS via servizio personalizzato (definisci l’URL API).
🧠 SEZIONE: Avanzate / Condizionali
Avvia disattivato: Aggiungi il monitor ma senza attivarlo subito.
- Resend Down Notification: Invia nuovamente una notifica se il servizio resta giù per molto tempo.
- Heartbeat Retry Strategy: (per Push monitors): strategie su come considerare un heartbeat “fallito”.
- Tag: Categorie o etichette personalizzate per organizzare i monitor.
Cliccare Save dopo aver impostato tutto
Dovremmo visualizzare una schermata come quella sovrastante con il monitoraggio attivo del sito inserito
A questo punto è possibile inserire tutto ciò che desideriamo monitorare…
🧠 Considerazioni generali su Uptime Kuma
✅ Punti di forza
- Open-source e gratuito
- Nessun costo di licenza.
- Attivamente sviluppato dalla community (GitHub).
- Codice leggibile, modificabile, auditabile.
- Interfaccia moderna e intuitiva
- Dashboard pulita e responsive.
- Grafici chiari, cronologia dello stato, uptime %.
- Ideale anche per utenti non esperti.
- Ampio supporto di protocolli: HTTP/HTTPS, ping, TCP, DNS, WebSocket, MQTT, Docker, GRPC, e altri.
- Copre la maggior parte dei casi d’uso reali (server, API, IoT, giochi, etc.).
- Notifiche versatili
- Supporta Telegram, Discord, Slack, e moltissimi altri.
- Anche via Webhook o API personalizzate (ottimo per DevOps).
- Facile da deployare
- Compatibile con Docker, Raspberry Pi, VPS, bare-metal.
- Setup in pochi minuti.
- Basso impatto sulle risorse
- Consuma poca CPU e RAM.
- Può girare anche su sistemi embedded.
⚠️ Limiti e considerazioni
- Non è un sistema di monitoraggio “enterprise”
- Non offre monitoraggio SNMP, metriche di sistema, tracing distribuito, etc.
- Non è pensato per ambienti complessi con centinaia di nodi e metriche avanzate (come Prometheus, Zabbix o Nagios).
- Non fa analisi delle performance
- Uptime Kuma verifica la disponibilità, ma non misura il tempo di risposta dettagliato, il carico del server, o la saturazione delle risorse.
- Database integrato semplice
- Usa SQLite (o eventualmente PostgreSQL), non ottimale per grandi quantità di dati nel lungo periodo (ma sufficiente per la maggior parte dei casi).
- Backup e scalabilità
- Il backup va gestito manualmente (o tramite snapshot Docker).
- Non ha clustering o failover: è pensato per ambienti singoli.
🧩 Quando è la scelta giusta?
✅ Perfetto se:
- Vuoi sapere se il tuo sito o servizio è online.
- Hai una piccola/media infrastruttura.
- Ti serve un’alternativa semplice a servizi commerciali (come UptimeRobot, StatusCake, Pingdom).
- Cerchi qualcosa di self-hosted, privato e controllabile.
❌ Non adatto se:
- Hai bisogno di monitorare l’intero stato di salute di un server (CPU, RAM, disco, log).
- Stai costruendo una piattaforma di monitoring per decine di team e microservizi complessi.
0 commenti