Uptime Kuma su un VPS: installazione con Docker e primo alert funzionante

Chi gestisce anche un solo VPS ha bisogno di sapere quando un servizio si ferma, non di scoprirlo da un cliente. Uptime Kuma è un monitor self-hosted gratuito, open source, che gira in un container Docker e si installa in pochi minuti. Qui sotto i comandi verificati sulla documentazione ufficiale del progetto, per Ubuntu 24.04.

Prerequisiti: Docker su Ubuntu 24.04

Ubuntu 24.04 LTS (nome in codice Noble) è una delle versioni supportate ufficialmente da Docker Engine. Prima di installare, vanno rimossi eventuali pacchetti Docker non ufficiali presenti nel sistema, perché possono entrare in conflitto con quelli ufficiali: Docker stesso segnala tra questi docker.io, docker-compose e containerd installati da repository diversi dal proprio.

I comandi ufficiali per il repository apt di Docker sono:

sudo apt update
sudo apt install ca-certificates curl
sudo install -m 0755 -d /etc/apt/keyrings
sudo curl -fsSL https://download.docker.com/linux/ubuntu/gpg -o /etc/apt/keyrings/docker.asc
sudo chmod a+r /etc/apt/keyrings/docker.asc
sudo apt update
sudo apt install docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin

Dopo l'installazione si verifica che il servizio sia attivo con sudo systemctl status docker.

Installare Uptime Kuma con Docker Compose

Il metodo raccomandato dal progetto è Docker Compose. I comandi pubblicati nel repository ufficiale su GitHub sono:

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

Al termine, Uptime Kuma è raggiungibile su http://localhost:3001 oppure su http://<ip-del-vps>:3001.

In alternativa, il comando docker run diretto, sempre dalla documentazione ufficiale:

docker run -d --restart=unless-stopped -p 3001:3001 -v uptime-kuma:/app/data --name uptime-kuma louislam/uptime-kuma:2

Due avvertenze della documentazione da non saltare. Primo: il filesystem che ospita la cartella dati deve supportare i lock POSIX, per evitare corruzione del database SQLite; NFS non va bene, va mappata una directory locale o un volume Docker. Secondo: se il VPS espone già un reverse proxy, conviene limitare la porta al solo localhost con -p 127.0.0.1:3001:3001, lasciando che sia il proxy a terminare il traffico pubblico.

Per chi preferisse evitare Docker, l'installazione nativa richiede Node.js 20.4 o superiore, Git e pm2 per tenere il processo in background, su distribuzioni Linux come Debian, Ubuntu, Fedora o ArchLinux.

Primo monitor HTTP

Al primo accesso via browser va creato l'account amministratore. Da dashboard si clicca su "Add New Monitor", si sceglie il tipo HTTP(s), si inserisce l'URL del servizio da controllare e l'intervallo di controllo (di default 60 secondi, configurabile anche su intervalli più brevi). Il progetto dichiara un intervallo minimo di 20 secondi tra i controlli.

Configurare una notifica

Uptime Kuma supporta nativamente l'invio di notifiche via Telegram, Discord, Slack, Pushover ed email SMTP, oltre a oltre 90 servizi aggiuntivi tramite l'integrazione con Apprise. La configurazione si fa da Settings → Notifications, creando un nuovo profilo di notifica e collegandolo al monitor. Per Telegram serve il token del bot e il chat ID; per email i parametri del server SMTP (host, porta, utente, password, mittente).

Verificare che l'alert arrivi davvero

Non ci si deve fidare del pannello verde. Il test corretto è fermare per qualche minuto il servizio monitorato (ad esempio sudo systemctl stop nginx sul server che ospita il sito controllato, oppure bloccare la porta con un iptables temporaneo) e controllare che:

1. Uptime Kuma segni il monitor come down entro l'intervallo di controllo impostato;
2. arrivi davvero la notifica sul canale configurato (email o Telegram);
3. al riavvio del servizio arrivi anche la notifica di recovery.

Se la notifica non arriva, i punti da controllare per primi sono le credenziali SMTP (porta e autenticazione) o, per Telegram, che il bot sia stato avviato in chat prima di recuperare il chat ID.

Aggiornamenti

Per aggiornare il container basta tirare la nuova immagine e riavviare: docker compose pull && docker compose up -d se si usa Compose, oppure fermare e ricreare il container con il nuovo tag se si usa docker run. Il progetto consiglia di non passare direttamente da immagini rootless in un upgrade da v1 a v2, perché possono presentarsi problemi di avvio legati ai permessi della cartella dati.