Uptime Kuma su VPS: Docker Compose, Caddy, avvisi

Uptime Kuma è un monitor open source e self-hosted per controlli HTTP(S), TCP, ping, DNS, WebSocket e altri. Su un VPS separato continua a controllare quando il tuo server di produzione va giù, invece di sparire insieme a lui.

Questa configurazione di Uptime Kuma su VPS installa la v2 con Docker Compose, tiene la porta 3001 sul loopback, aggiunge HTTPS tramite Caddy, instrada gli avvisi verso Telegram, Discord e Slack e pubblica una pagina di stato.

Prerequisiti e cosa ti servirà

Un VPS con almeno 1 vCPU, 1 GB di RAM e 10 GB di spazio SSD locale
Ubuntu 24.04 LTS o un'altra versione attuale di Ubuntu supportata da Docker
Docker Engine e Docker Compose installati sul VPS
Un dominio o sottodominio che punta al VPS tramite un record A (per esempio status.example.com)
Accesso SSH e una minima dimestichezza con la riga di comando

Se Docker non è ancora installato, segui la guida all'installazione di Docker su Ubuntu. Installa Docker Engine e il plugin Compose usato più avanti.

Perché il VPS di monitoraggio deve essere separato da ciò che controlla

Production in Region A has failed and its website, API and database are down, while Uptime Kuma on a separate VPS in Region B stays online, keeps probing those services and routes alerts to Telegram, Discord and Slack. An external watchdog checks Uptime Kuma itself.

Produzione e monitoraggio sullo stesso server condividono lo stesso dominio di guasto. Se quel server si ferma, spariscono insieme l'applicazione e il sistema che dovrebbe inviare l'avviso.

Due configurazioni pratiche migliorano la situazione:

Stesso provider, località diversa. Metti produzione e monitoraggio su host separati, in località diverse. Questo riduce l'esposizione al guasto di un singolo server o di un singolo datacenter, ma non protegge da ogni incidente di rete o del control plane che colpisca l'intero provider.
Un provider completamente diverso. Ospitare il monitor altrove aggiunge protezione anche contro gli incidenti che colpiscono l'intero provider. In cambio hai un account, una fattura e una superficie operativa in più da gestire.

Una singola istanza di Uptime Kuma resta comunque senza un guardiano esterno. Aggiungi un controllo HTTP(S) esterno sulla sua pagina di stato pubblica. Il piano gratuito di UptimeRobot include attualmente 50 monitor con intervalli di cinque minuti. Questo non renderà Uptime Kuma ad alta disponibilità, ma ti dirà quando è il monitor stesso a sparire.

La stessa regola vale per le pagine di stato pubbliche: ciò che ti avvisa del guasto non deve condividere il dominio di guasto con ciò che si guasta.

Costruisci su un VPS Linux con accesso root, NVMe e la potenza di AMD EPYC.

Vedi piani Linux

Dimensionare il VPS

Uptime Kuma non ha una formula affidabile che leghi il numero di monitor alla RAM, perché il carico cambia con il tipo di monitor, l'intervallo, le impostazioni dei tentativi e la conservazione dello storico. I controlli semplici HTTP(S), TCP, ping e DNS sono più leggeri di quelli Browser Engine, che avviano Chromium.

Per un piccolo insieme di controlli di base, parti con 1 vCPU, 1 GB di RAM e storage SSD locale. Tieni d'occhio il consumo reale con docker stats uptime-kuma e la crescita del database con du -sh /opt/uptime-kuma/data. Aggiungi memoria quando il consumo resta alto, quando il container segnala un OOM kill o quando introduci controlli Browser Engine.

L'immagine v2 completa include Chromium e un MariaDB integrato; la documentazione dei tag Docker spiega la differenza tra l'immagine completa e quella slim.

Installare Uptime Kuma con Docker Compose

Salva questo file come docker-compose.yml in /opt/uptime-kuma/:

services:
  uptime-kuma:
    image: louislam/uptime-kuma:2
    container_name: uptime-kuma
    restart: unless-stopped
    ports:
      # Bind to localhost only. The reverse proxy will expose it on 443.
      - "127.0.0.1:3001:3001"
    volumes:
      - ./data:/app/data

Tre righe meritano attenzione:

image: louislam/uptime-kuma:2 blocca la versione major. Il tag :2 segue la linea stabile 2.x. Non usare :latest.
127.0.0.1:3001:3001 lega il container solo a localhost. Internet non deve mai raggiungere direttamente la porta 3001. È il reverse proxy a detenere il certificato TLS e l'hostname pubblico.
Il volume dati contiene il database, la configurazione dei monitor e lo storico. Tienilo su storage locale, perché la documentazione di installazione di Uptime Kuma avverte che i filesystem senza un locking POSIX affidabile, comprese molte configurazioni NFS, possono corrompere SQLite. Ferma lo stack prima di fare una copia a livello di filesystem.

Avvialo e verifica:

sudo install -d -o "$USER" -g "$USER" /opt/uptime-kuma
cd /opt/uptime-kuma
# Paste the docker-compose.yml file above.
sudo docker compose up -d
sudo docker compose ps

Output atteso di docker compose ps:

NAME          IMAGE                       STATUS                   PORTS
uptime-kuma   louislam/uptime-kuma:2      Up (healthy)             127.0.0.1:3001->3001/tcp

Per raggiungere la dashboard la prima volta, non aprire la porta 3001 su Internet, nemmeno per poco. Passa da un tunnel SSH:

ssh -L 3001:127.0.0.1:3001 [email protected]

Apri http://localhost:3001 nel browser, crea l'account amministratore, imposta una password robusta e chiudi il tunnel. Da qui in poi la dashboard ti raggiunge in HTTPS attraverso il tuo reverse proxy.

Se non hai bisogno di fare Compose a mano, offriamo anche Uptime Kuma come app installabile con un clic. La pagina attuale dell'app indica la v1, quindi non corrisponde alla configurazione v2 di questa guida. Segui la via manuale con Compose se ti serve proprio la v2.

Reverse proxy e TLS

Public traffic reaches Caddy on the host or an Nginx Proxy Manager container over HTTPS on port 443. Caddy forwards to Uptime Kuma on 127.0.0.1:3001 while the NPM container uses a shared Docker network instead. Public access to port 3001 is blocked, and first-time setup runs through an SSH tunnel to localhost:3001.

Non esporre Uptime Kuma direttamente. Mettigli davanti un reverse proxy per il TLS, una gestione corretta degli URL e un unico punto di ingresso pubblico. Due strade.

Caddy. Se Caddy non è ancora installato, segui i passaggi ufficiali del pacchetto per Ubuntu. Con Caddy in esecuzione come servizio dell'host, il Caddyfile qui sotto inoltra a Uptime Kuma sul loopback e gestisce da solo emissione e rinnovo del certificato.

Consiglio: quando il VPS di monitoraggio ospita solo Uptime Kuma, usa Caddy. Il Caddyfile sta in tre righe e Caddy gestisce da sé emissione e rinnovo del certificato. Niente Certbot e nessun timer di rinnovo separato da sorvegliare alle 4 del mattino.

Salva questo come /etc/caddy/Caddyfile:

status.example.com {
    reverse_proxy 127.0.0.1:3001
}

Ricarica Caddy:

sudo systemctl reload caddy

Verifica:

curl -I https://status.example.com

Dovresti ricevere una risposta 2xx o 3xx valida con un certificato corretto. Se la connessione fallisce, verifica che il record A o AAAA del dominio punti a questo VPS, che le porte 80 e 443 siano raggiungibili e che Caddy possa mettersi in ascolto su entrambe. Tutto questo rientra nei requisiti dell'HTTPS automatico di Caddy.

Nginx Proxy Manager. Se NPM gira direttamente sull'host, aggiungi un Proxy Host per status.example.com, inoltralo a 127.0.0.1 sulla porta 3001, richiedi un certificato Let's Encrypt e attiva Websockets Support. Se NPM gira in Docker, 127.0.0.1 punta al container di NPM stesso. Collega invece NPM e Uptime Kuma alla stessa rete Docker, poi inoltra il proxy host a uptime-kuma sulla porta 3001.

Instradare gli avvisi: Telegram, Discord, Slack

Uptime Kuma può instradare lo stesso evento di un monitor verso più canali di notifica. Configura ogni provider una volta sola, poi collega a un monitor uno o più canali in base a chi deve ricevere l'avviso.

Le notifiche si configurano a livello globale in Impostazioni > Notifiche, per poi assegnarle ai singoli monitor. Ogni monitor può attivare uno o più canali. Lo stesso avviso può arrivare su Telegram al reperibile, su Slack al team e via email per il registro di audit, tutto da un unico evento.

In Telegram, scrivi a @BotFather ed esegui /newbot. Scegli un nome e uno username. BotFather risponde con un token del bot. Conservalo.
Invia un messaggio qualsiasi al tuo nuovo bot. Poi apri https://api.telegram.org/bot<YOUR_TOKEN>/getUpdates in un browser. Cerca il campo chat.id: quello è il tuo ID chat.
In Uptime Kuma: Impostazioni > Notifiche > Configura notifica > Telegram. Incolla il token del bot e l'ID chat. Fai clic su Prova. Verifica che il bot invii l'avviso di prova.
Se il messaggio di prova non arriva, verifica che il token del bot e l'ID chat siano corretti e che il firewall del VPS consenta il traffico HTTPS in uscita verso api.telegram.org.

Discord

Apri il server Discord in cui vuoi ricevere gli avvisi. Fai clic destro sul canale di destinazione, poi Modifica canale > Integrazioni > Webhook > Nuovo webhook. Dagli un nome (qualcosa come "Uptime Kuma"), scegli il canale e copia l'URL del webhook.
In Uptime Kuma: Impostazioni > Notifiche > Configura notifica > Discord. Incolla l'URL del webhook. Volendo, imposta anche username e avatar.
Fai clic Prova. Verifica che il webhook pubblichi l'avviso di prova nel canale.

Slack

In Slack, crea un Incoming Webhook per il canale in cui vuoi gli avvisi. Slack restituisce un URL di webhook nella forma https://hooks.slack.com/services/T.../B.../....
In Uptime Kuma: Impostazioni > Notifiche > Configura notifica > Slack. Incolla l'URL del webhook. Volendo, configura anche l'icona e l'override del canale.
Fai clic Prova.

Quando tutti i test passano, modifica ogni monitor e seleziona i canali di notifica che deve usare. Imposta Max Retries (numero massimo di tentativi) e i piani Retry Interval (intervallo tra i tentativi) in modo che un guasto breve non faccia scattare subito un avviso.

La pagina di stato integrata (e quando ti starà stretta)

Uptime Kuma include pagine di stato pubbliche con slug personalizzati, monitor raggruppati, domini propri, post sugli incidenti e messaggi di manutenzione programmata. Da una sola istanza puoi anche pubblicare più pagine di stato, per servizi o pubblici diversi.

Il limite più grosso riguarda la comunicazione verso i clienti. Al momento i visitatori non possono iscriversi via email agli aggiornamenti direttamente da una pagina di stato, e quella pagina pubblica resta parte della stessa applicazione Uptime Kuma della dashboard dell'operatore. L'auto-iscrizione dei visitatori è ancora tracciata come una richiesta di funzionalità aperta.

Se ti servono le iscrizioni dei clienti o un sistema di stato separato dalla dashboard di monitoraggio, Kener è un'alternativa. Il nostro articolo sullo stack di monitoraggio self-hosted spiega come si possono abbinare i due strumenti.

Problemi comuni

Le notifiche falliscono in silenzio quando il firewall del VPS blocca l'HTTPS in uscita. Sintomo: il pulsante Test funziona per alcuni canali e per altri no. Soluzione: verifica che le connessioni HTTPS in uscita siano consentite e che curl -I https://api.telegram.org vada a buon fine dal VPS.

Il browser mostra "ERR_TOO_MANY_REDIRECTS" dopo aver attivato il proxy. Controlla se ci sono redirect HTTP verso HTTPS duplicati in Caddy, Nginx Proxy Manager o in un CDN a monte. Uptime Kuma deve continuare a servire HTTP sulla porta 3001, mentre è il reverse proxy pubblico a terminare il TLS. Se abiliti gli header di proxy attendibile, il percorso attuale è Impostazioni > Reverse Proxy > Header HTTP > Trust Proxy.

Il container si riavvia ogni pochi minuti. Controlla se il container è stato terminato per esaurimento di memoria, poi osserva il consumo attuale con docker stats uptime-kuma. Se il container è stato ucciso dall'OOM o la memoria resta vicina al limite del VPS, aggiungi RAM, riduci i controlli pesanti o allunga i loro intervalli.

La pagina di stato funziona su localhost ma non tramite l'hostname pubblico. Verifica che il reverse proxy inoltri il percorso radice senza modifiche, conservi l'header Host e supporti i WebSockets. Uptime Kuma non supporta l'installazione in una sottocartella, quindi usa un dominio o sottodominio dedicato invece di un percorso come example.com/uptime-kuma.

Tirando le somme

Uptime Kuma su un VPS separato ti dà il controllo su controlli, instradamento degli avvisi e pagina di stato pubblica, ma ti carichi anche aggiornamenti, backup, patch del sistema operativo e il guardiano esterno del monitor stesso. Scegli un VPS in una località diversa dalla produzione, installa la v2 con Docker Compose oppure usa l'app con un clic dopo aver controllato la versione indicata, mettici davanti Caddy e collega i canali che il tuo team guarda davvero.

Domande frequenti

Quanta RAM serve a Uptime Kuma?

Uptime Kuma non ha una formula affidabile che leghi il numero di monitor alla RAM, perché il consumo cambia con il tipo di monitor, l'intervallo di controllo, le impostazioni dei tentativi, la conservazione dello storico e l'uso del Browser Engine. Per un piccolo insieme di controlli di base, parti con 1 GB di RAM e osserva il consumo reale con docker stats uptime-kuma. Aggiungi memoria se il consumo resta vicino al limite o se il container viene ucciso dall'OOM.

Conviene far girare Uptime Kuma sullo stesso server della mia app?

No. Se lo strumento di monitoraggio e l'applicazione condividono il server, un guasto li manda offline insieme e perdi gli avvisi proprio quando ti servono di più. Fai girare Uptime Kuma su un VPS separato, possibilmente in un datacenter diverso.

Uptime Kuma può inviare avvisi a Telegram, Discord e Slack?

Sì. Telegram, Discord e Slack sono servizi di notifica integrati, insieme a email, webhook generici, PagerDuty, ntfy, Mattermost e molti altri. Telegram usa un token del bot e un ID chat, mentre Discord e Slack usano URL di webhook. Puoi collegare più canali di notifica allo stesso monitor.

Qual è la differenza tra Uptime Kuma e UptimeRobot?

Uptime Kuma è self-hosted, quindi sei tu a gestire server, aggiornamenti, backup e instradamento degli avvisi. Supporta intervalli di controllo fino a 20 secondi. UptimeRobot è un SaaS ospitato e il suo piano gratuito attuale include 50 monitor con controlli ogni cinque minuti. Scegli Uptime Kuma se vuoi il controllo, oppure UptimeRobot se non vuoi gestire il server di monitoraggio.

Uptime Kuma ha una pagina di stato pubblica?

Sì. Puoi scegliere quali monitor sono visibili, raggrupparli, pubblicare più pagine di stato, associarle a domini personalizzati e programmare messaggi di manutenzione. L'auto-iscrizione via email dei visitatori non è integrata, quindi usa uno strumento separato di pagine di stato rivolto ai clienti quando questi devono iscriversi agli aggiornamenti.

Come configurare Uptime Kuma su un VPS