Ospitare Uptime Kuma su un VPS gestito: monitorate i vostri servizi

Che cosa monitora Uptime Kuma

Uptime Kuma interroga i vostri servizi a intervalli regolari, fino a ogni 20 secondi, conserva la cronologia delle loro risposte e vi avvisa non appena uno di essi smette di rispondere. Si usa da un'interfaccia web, disponibile in più lingue.

• Le sonde: HTTP e HTTPS, ricerca di una parola chiave nella pagina, richiesta JSON, TCP, WebSocket, ping, record DNS, container Docker e sonda «push» per un'attività pianificata che segnala da sola il proprio passaggio.
• Gli avvisi: più di 90 servizi di notifica, tra cui Telegram, Discord, Slack e l'e-mail.
• Le pagine di stato: più pagine pubbliche, ciascuna sul proprio dominio, se lo desiderate.
• I certificati: le informazioni del certificato HTTPS di ogni servizio monitorato.
• L'account: autenticazione a due fattori e passaggio da un proxy per le sonde che ne hanno bisogno.

Collocate Uptime Kuma su un server diverso da quello dei servizi che monitora. Su una macchina distinta, vede il guasto dall'esterno e invia l'avviso mentre i vostri servizi sono fermi.

Che cosa consente la licenza MIT

Uptime Kuma è pubblicato con licenza MIT. Autorizza a usare, copiare, modificare, unire, pubblicare, distribuire, concedere in sublicenza e vendere il software, a una condizione: conservare la nota di copyright e il testo della licenza in ogni copia.

Potete quindi far girare Uptime Kuma in azienda, monitorarvi i servizi dei vostri clienti e aprire per loro delle pagine di stato, senza alcuna licenza da acquistare.

L'installazione con Docker Compose

La documentazione di Uptime Kuma parte da Docker Compose. Su un server in cui Docker è installato, create una cartella e scaricate il file ufficiale:

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

Il file del progetto pubblica la porta 3001 su tutti gli indirizzi del server. Dietro un reverse proxy, limitatela all'indirizzo locale, come propone il README:

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

docker compose up -d

• Una porta pubblicata su 127.0.0.1: Docker pubblica per impostazione predefinita su tutti gli indirizzi del server, prima delle regole del firewall ufw. In locale, Uptime Kuma si raggiunge solo tramite il reverse proxy.
• Una cartella data su un disco locale: contiene il database kuma.db, i file caricati e gli screenshot. Il progetto esclude NFS e gli altri file system di rete, perché SQLite ha bisogno di blocchi di file affidabili.
• Il tag 2 segue la versione 2 di Uptime Kuma, e il passaggio a una versione maggiore successiva resta una vostra scelta.
• L'immagine 2-slim è più leggera, circa 185 MB da scaricare contro 620 MB: lascia da parte Chromium e il MariaDB integrato che l'immagine 2 include. L'immagine 2 è quella che il progetto raccomanda, e una sonda «Browser Engine» richiede allora un Chromium esterno con 2-slim.

Al primo avvio, aprite l'interfaccia: una procedura guidata vi fa scegliere il database, poi creare l'account amministratore. Attivate l'autenticazione a due fattori fin dal primo accesso.

Il progetto non indica né la memoria né il processore necessari: la taglia dipende dal numero di servizi da monitorare e dalla frequenza desiderata. Su un VPS gestito, descrivetici il vostro uso e vi raccomandiamo la taglia adatta.

HTTPS e WebSocket: il reverse proxy

Su una rete pubblica, il progetto richiede HTTPS. Uptime Kuma si basa su WebSocket: il reverse proxy deve inoltrare le intestazioni Upgrade e Connection. Si serve dalla radice di un dominio o di un sottodominio, e il suo wiki esclude le sottocartelle come example.com/uptimekuma.

Con Caddy

Caddy ottiene e rinnova da solo il certificato, e inoltra WebSocket senza altre impostazioni:

uptime.example.com {
    reverse_proxy 127.0.0.1:3001
}

Con Nginx e Certbot

server {
    listen 80;
    server_name uptime.example.com;

    location / {
        proxy_pass         http://localhost:3001;
        proxy_http_version 1.1;
        proxy_set_header   Upgrade $http_upgrade;
        proxy_set_header   Connection "upgrade";
        proxy_set_header   Host $host;
    }
}

Certbot installa poi il certificato Let's Encrypt e il reindirizzamento verso HTTPS, quindi rinnova il certificato in autonomia:

sudo certbot --nginx -d uptime.example.com

Quando Uptime Kuma è raggiungibile solo tramite il proxy, aprite le sue impostazioni, «Settings», «Reverse Proxy», «HTTP Headers», e portate «Trust Proxy» su «Yes»: i log mostrano allora l'indirizzo reale dei visitatori.

SQLite o MariaDB

Dalla versione 2, Uptime Kuma offre tre database, tra cui scegliere nella procedura guidata del primo avvio:

Per fissare la scelta in anticipo, senza passare dalla procedura guidata, le variabili UPTIME_KUMA_DB_TYPE, UPTIME_KUMA_DB_HOSTNAME, UPTIME_KUMA_DB_PORT, UPTIME_KUMA_DB_NAME, UPTIME_KUMA_DB_USERNAME e UPTIME_KUMA_DB_PASSWORD si aggiungono al servizio in compose.yaml.

Le notifiche, e-mail comprese

Una sonda serve solo se l'avviso vi raggiunge. Dichiarate i vostri canali in «Settings», «Notifications», inviate un messaggio di prova da ciascuno e prevedetene due, per esempio una messaggistica e l'e-mail: se uno cade, l'altro prende il testimone.

Per l'e-mail, Uptime Kuma si connette a un server SMTP. Su un VPS Simafri, l'invio passa da un relay autenticato, sulla porta 587: l'indirizzo di un account di posta che avete già, oppure Simafri Suite.

Backup e aggiornamenti

Dalla versione 2, il backup della cartella data è l'unico metodo che il progetto supporta. Con SQLite o con il MariaDB integrato, c'è tutto lì. Un database SQLite copiato in piena scrittura può risultare corrotto: fermate il container per il tempo della copia, sapendo che le sonde si fermano con lui.

docker compose stop
tar -czf uptime-kuma-$(date +%F).tar.gz data
docker compose start

Aggiornare

Il wiki del progetto fornisce due comandi, dalla cartella del compose.yaml. La cartella data resta al suo posto:

docker compose pull
docker compose up -d --force-recreate

Leggete le note di rilascio prima di ogni aggiornamento: alcune contengono correzioni di sicurezza, come la 2.5.9 del 31 ottobre 2026. Un backup subito prima vi offre un ritorno indietro semplice.

Il passaggio dalla versione 1 alla versione 2 richiede più cura: salvate la cartella data, a container fermo, e lasciate che la migrazione arrivi fino in fondo, perché una migrazione interrotta obbliga a ripristinare il backup. Il progetto ha rilevato circa 7 minuti per 20 sonde e 90 giorni di cronologia, e molto di più su una macchina modesta o con più sonde.

Chi fa che cosa su un VPS gestito

Il self-hosting richiede di occuparsi del server oltre che dell'applicazione. Su un VPS gestito, i nostri team prendono in carico il server e seguono la vostra istanza in modo proattivo; Uptime Kuma resta il vostro software, con le sue impostazioni e i suoi dati.

Se preferite che i nostri team intervengano nell'applicazione stessa, questa prestazione si fattura a ore o a forfait, con un preventivo comunicato prima dell'intervento.