Uptime Kuma: installare il proprio monitoraggio dei siti su un VPS

Un sito può smettere di funzionare e continuare a rispondere con 200 OK. Anche un backup può non essere più creato senza mostrare un errore evidente. Uptime Kuma rileva entrambi i casi: controlla siti, API, porte e attività in background e invia una notifica quando si verifica un problema.

Vedremo dove ospitare il monitoraggio, quale VPS è necessario e come installare Uptime Kuma 2, attivare HTTPS, collegare Telegram e creare una pagina di stato.

Uptime Kuma in sette passaggi

1. Predisporre un piccolo VPS separato dai progetti monitorati.
2. Puntare verso di esso un sottodominio, ad esempio monitor.example.com.
3. Installare Docker e avviare Uptime Kuma 2.
4. Chiudere verso l’esterno la porta interna 3001 e configurare HTTPS.
5. Creare monitor HTTP, DNS, TCP o Push.
6. Configurare Telegram e, se necessario, una pagina di stato.
7. Impostare gli aggiornamenti e un backup esterno della directory dei dati.

Che cos’è Uptime Kuma

Uptime Kuma è uno strumento self-hosted gratuito e open source. Il pannello e la cronologia dei controlli vengono conservati sul proprio server.

Può monitorare HTTP(S), porte TCP, ping, DNS, WebSocket, testo e JSON nelle risposte, segnali Push e container Docker. L’intervallo minimo tra i controlli è di 20 secondi. Offre inoltre decine di canali di notifica, 2FA, grafici della latenza, controllo dei certificati TLS e più pagine di stato.

Come rilevare un guasto nascosto dietro 200 OK

Un normale controllo HTTP vede soltanto il codice di risposta. Tuttavia, il server web può mostrare una pagina vuota o una schermata di errore dell’applicazione e restituire comunque uno stato di successo.

Per un controllo più preciso, utilizzare:

• Keyword — cerca una frase prevista, ad esempio il nome del sito o il testo «Area clienti»;
• JSON Query — verifica un valore nella risposta dell’API, ad esempio status: healthy.

In questo modo il monitoraggio conferma non solo che la porta è raggiungibile, ma anche un requisito minimo del corretto funzionamento dell’applicazione.

Monitor Push per backup e attività cron

Un monitor Push non interroga il servizio, ma attende un segnale periodico inviato dal servizio stesso. Uno script di backup o un’attività cron richiama un URL univoco dopo essere terminato correttamente. Se il segnale non arriva in tempo, Uptime Kuma segnala il problema.

Questo permette di rilevare un problema «silenzioso»: il sito continua a funzionare, ma il backup giornaliero non viene creato da diversi giorni.

Che cosa non sostituisce Uptime Kuma

Uptime Kuma controlla principalmente la disponibilità e il tempo di risposta. Per CPU, RAM, disco, log e metriche dei container, è opportuno affiancarlo a Prometheus, Netdata, Zabbix o a un altro sistema: Kuma rileva il problema dall’esterno, mentre le metriche aiutano a individuarne la causa.

Perché conviene spostare il monitoraggio su un VPS separato

Se Uptime Kuma viene installato insieme al sito, un guasto del VPS, della rete o del data center può rendere indisponibili sia il progetto sia il monitoraggio. In questo caso, la notifica potrebbe non essere inviata.

Ospitare il pannello su un VPS separato e, per i progetti importanti, in un’altra località o presso un altro provider. È inoltre utile controllare Kuma stesso con un servizio esterno: anche il sistema di monitoraggio deve essere monitorato.

Requisiti del server per Uptime Kuma

Il progetto non stabilisce un minimo ufficiale rigido per CPU e RAM. Una configurazione iniziale pratica per una piccola installazione è:

• 1 vCPU;
• 1 GB di RAM;
• 10 GB di SSD;
• Ubuntu 24.04 LTS;
• IPv4;
• un dominio o sottodominio per HTTPS.

Questa configurazione è generalmente sufficiente per alcune decine di controlli semplici. Per centinaia di monitor, una cronologia estesa o controlli tramite browser, è preferibile scegliere almeno 2 GB di RAM.

Come installare Uptime Kuma su un VPS

In questo esempio vengono utilizzati Ubuntu 24.04 e il sottodominio monitor.example.com.

1. Configurare DNS e firewall

Creare un record DNS A che punti all’indirizzo IPv4 del VPS. Collegarsi tramite SSH e aprire le porte necessarie:

ssh root@SERVER_IP
apt update && apt upgrade -y

ufw allow OpenSSH
ufw allow 80/tcp
ufw allow 443/tcp
ufw --force enable

Non chiudere la sessione SSH corrente finché non è stata verificata una nuova connessione.

2. Installare Docker e Docker Compose

apt install -y ca-certificates curl
install -m 0755 -d /etc/apt/keyrings

curl -fsSL https://download.docker.com/linux/ubuntu/gpg \
  -o /etc/apt/keyrings/docker.asc
chmod a+r /etc/apt/keyrings/docker.asc

tee /etc/apt/sources.list.d/docker.sources > /dev/null <<EOF
Types: deb
URIs: https://download.docker.com/linux/ubuntu
Suites: $(. /etc/os-release && echo "${UBUNTU_CODENAME:-$VERSION_CODENAME}")
Components: stable
Architectures: $(dpkg --print-architecture)
Signed-By: /etc/apt/keyrings/docker.asc
EOF

apt update
apt install -y docker-ce docker-ce-cli containerd.io \
  docker-buildx-plugin docker-compose-plugin

docker compose version

3. Avviare Uptime Kuma 2

mkdir -p /opt/uptime-kuma
cd /opt/uptime-kuma

cat > compose.yaml <<'EOF'
services:
  uptime-kuma:
    image: louislam/uptime-kuma:2
    restart: unless-stopped
    ports:
      - "127.0.0.1:3001:3001"
    volumes:
      - ./data:/app/data
EOF

docker compose up -d
docker compose ps

Utilizzare il tag :2: latest continua a puntare al vecchio ramo v1. La directory /app/data deve trovarsi su un disco locale o in un normale Docker volume. NFS e i sistemi di archiviazione che non gestiscono correttamente il blocco dei file possono danneggiare il database.

La porta 3001 è accessibile soltanto su 127.0.0.1. Un proxy inverso con HTTPS pubblicherà il pannello verso l’esterno.

4. Configurare HTTPS con Caddy

apt install -y caddy

cat > /etc/caddy/Caddyfile <<'EOF'
monitor.example.com {
    reverse_proxy 127.0.0.1:3001
}
EOF

caddy validate --config /etc/caddy/Caddyfile
systemctl reload caddy

Se DNS punta al VPS, Caddy richiederà automaticamente un certificato TLS e inoltrerà le connessioni WebSocket. Il pannello deve essere ospitato nella radice di un dominio o sottodominio: un indirizzo come example.com/kuma non è supportato.

5. Creare l’account amministratore

Aprire https://monitor.example.com, creare un account con una password lunga e univoca e attivare l’autenticazione a due fattori.

Come aggiungere il primo monitor

Fare clic su Add New Monitor e selezionare HTTP(s):

1. Indicare un nome e l’URL completo.
2. Impostare un intervallo, ad esempio 60 secondi.
3. Aggiungere due tentativi per evitare falsi allarmi dovuti a problemi di rete occasionali.
4. Selezionare un canale di notifica.
5. Salvare il monitor e verificare che inizino a comparire richieste riuscite.

Per il sito principale sono utili i controlli HTTP e Keyword; per un’API, utilizzare un endpoint di health e JSON Query. Non esporre database o porte amministrative a Internet soltanto per il monitoraggio: utilizzare una rete attendibile o una VPN.

Esempio di monitor Push per un backup

Dopo aver creato un monitor di tipo Push, aggiungere il suo URL univoco alla fine dello script:

backup-command && \
  curl -fsS "https://monitor.example.com/api/push/SECRET_TOKEN?status=up&msg=backup-ok"

La richiesta verrà eseguita soltanto dopo un backup completato con successo. Conservare il token Push come una password: chiunque conosca l’URL può inviare un falso segnale.

Come collegare Telegram

Creare un bot tramite @BotFather, inviargli un messaggio e poi aprire Settings → Notifications → Telegram. Inserire Bot Token e Chat ID, fare clic su Test e associare il canale ai monitor. Per i servizi critici, aggiungere un secondo canale, ad esempio l’e-mail.

Come creare una pagina di stato

In Status Pages è possibile raggruppare i monitor, mostrare lo stato corrente e la cronologia della disponibilità, assegnare un dominio e comunicare gli interventi programmati tramite Maintenance. Non pubblicare IP interni o URL tecnici: ai clienti bastano componenti come «Sito», «API», «Area clienti» e «Pagamenti».

Aggiornamento e backup

Prima di un aggiornamento importante, arrestare il container e salvare la directory dei dati:

cd /opt/uptime-kuma
docker compose down

tar -czf /root/uptime-kuma-$(date +%F).tar.gz \
  data compose.yaml

docker compose up -d

Trasferire l’archivio su un altro dispositivo o in uno spazio di archiviazione esterno. Una copia sullo stesso VPS non protegge dall’eliminazione del server o dal guasto del disco.

Per un normale aggiornamento:

cd /opt/uptime-kuma
docker compose pull
docker compose up -d --force-recreate

Dopo l’avvio, controllare docker compose ps, il pannello e una notifica di prova.

Quale VPS scegliere per Uptime Kuma

Per una piccola installazione è sufficiente un VPS Linux con 1 vCPU e 1 GB di RAM. L’indipendenza è più importante della potenza: il monitor deve continuare a funzionare quando il progetto principale non è disponibile.

Uptime Kuma può essere ospitato su un VPS di tropic.host se i servizi monitorati si trovano su un’altra piattaforma o su un nodo indipendente. Ubuntu, Docker e un IP statico permettono di avviare rapidamente il pannello, mentre le risorse possono essere aumentate con la crescita del numero di controlli.

Se la produzione si trova già nella stessa infrastruttura, scegliere un altro nodo o aggiungere un monitor esterno di riserva. Separare i punti di guasto è più utile che aggiungere un core della CPU.

Errori comuni

Errore	Perché è un problema	Soluzione migliore
Il monitoraggio si trova insieme al progetto	Un guasto comune interrompe sia il servizio sia le notifiche	Utilizzare un VPS o una località separata
La porta 3001 è esposta pubblicamente	Il pannello è accessibile senza proxy inverso e HTTPS	Associare la porta a 127.0.0.1
Viene controllato soltanto il codice 200	Un errore dell’applicazione può sembrare un successo	Aggiungere Keyword o JSON Query
Viene utilizzato il tag latest	Punta al vecchio ramo v1	Utilizzare louislam/uptime-kuma:2
Il backup si trova sullo stesso VPS	Scomparirà insieme al server	Copiare all’esterno la directory data

In sintesi

Uptime Kuma trasforma un piccolo VPS in un centro di monitoraggio autonomo per siti, API, DNS, porte, certificati e attività in background. Keyword aiuta a rilevare una pagina danneggiata, JSON Query una risposta API errata e Push un backup o un’attività cron interrotti.

Per una configurazione affidabile, separare il monitoraggio dalla produzione, chiudere la porta 3001, attivare HTTPS e 2FA e impostare due canali di notifica. Configurare quindi un backup esterno della directory dei dati e un controllo indipendente dello stesso Uptime Kuma.

FAQ

Uptime Kuma è gratuito?

Sì. Il progetto è open source e distribuito con licenza MIT. Si pagano soltanto l’infrastruttura, il dominio e i backup esterni.

Quanta RAM richiede Uptime Kuma?

Per una piccola installazione, 1 GB di RAM è un punto di partenza ragionevole. Per centinaia di controlli, una cronologia estesa o Browser Engine, assegnare almeno 2 GB.

È possibile installare Uptime Kuma senza Docker?

Sì, tramite Node.js e PM2. Tuttavia, Docker Compose è generalmente più semplice da aggiornare, migrare e ripristinare su un VPS.

È possibile utilizzare Uptime Kuma senza dominio?

Tecnicamente sì, tramite l’indirizzo IP o un tunnel SSH. Per un accesso permanente da Internet, è più sicuro utilizzare un sottodominio con HTTPS.

Uptime Kuma mostra l’utilizzo di CPU, RAM e disco?

Non come un sistema completo di metriche del server. Per monitorare le risorse, è meglio affiancarlo a Prometheus, Netdata, Zabbix o a un altro strumento specializzato.