1 04/11/2026 11 min

Su Ubuntu 22.04 LTS Uptime Kuma si installa senza complicazioni, ma il punto non è solo far partire il servizio: conviene chiuderlo bene dietro reverse proxy, con un utente dedicato, un percorso chiaro per i dati e un controllo minimo su aggiornamenti e backup. Se il monitoraggio serve davvero in produzione, la differenza la fanno i dettagli operativi, non l’installazione in sé.

Qui sotto trovi una procedura completa e lineare: preparazione del sistema, installazione con Node.js, creazione del servizio systemd, pubblicazione tramite Nginx e verifiche finali. L’obiettivo è avere una dashboard accessibile in modo stabile, senza esporre direttamente la porta applicativa su Internet.

Prerequisiti sul server Ubuntu 22.04

Prima di iniziare, verifica di avere accesso SSH con un utente dotato di privilegi sudo, un hostname già risolto correttamente e una porta HTTP/HTTPS raggiungibile dall’esterno se prevedi l’accesso pubblico. Uptime Kuma non richiede un database esterno: conserva i dati localmente nel proprio percorso applicativo, quindi la scelta del disco e dei backup conta più del resto.

Conviene anche aggiornare il sistema e installare i pacchetti di base. In un’installazione nuova è una buona pratica, perché riduce il rischio di conflitti con librerie vecchie o repository incompleti.

sudo apt update
sudo apt -y upgrade
sudo apt -y install curl git ca-certificates gnupg nginx

Se il server è già in produzione, valuta l’impatto dell’upgrade prima di applicarlo: il blast radius è l’intero host, e il rollback dipende da snapshot o backup del provider. In assenza di snapshot, almeno documenta i pacchetti aggiornati con apt history e conserva una finestra di manutenzione.

Installare Node.js su Ubuntu 22.04

Uptime Kuma gira su Node.js. Sulla 22.04 la scelta più semplice è usare il repository ufficiale NodeSource, così eviti versioni troppo vecchie nei repository di base. In genere una versione LTS recente è la scelta più prudente per stabilità e compatibilità.

curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash -
sudo apt -y install nodejs

Dopo l’installazione, controlla le versioni effettive:

node -v
npm -v

Ti aspetti una versione coerente con il ramo LTS installato, ad esempio v20.x. Se node -v restituisce una versione inattesa, il problema è quasi sempre nel repository configurato o in un conflitto con installazioni precedenti. In quel caso, prima di procedere, conviene capire quale binario stai usando con which node e apt policy nodejs.

Creare un utente dedicato e scaricare Uptime Kuma

Non installarlo come root. Un utente dedicato riduce l’impatto di un eventuale problema applicativo e rende più pulita la gestione dei permessi. Qui uso uptimekuma e una directory in /opt/uptime-kuma, scelta comoda perché separa il software dai dati di sistema.

sudo useradd --system --create-home --home-dir /opt/uptime-kuma --shell /usr/sbin/nologin uptimekuma
sudo mkdir -p /opt/uptime-kuma
sudo chown -R uptimekuma:uptimekuma /opt/uptime-kuma

Scarica il codice sorgente dal repository ufficiale. In produzione è meglio fissare una release o un tag, invece di inseguire sempre main, perché così rendi più prevedibile il comportamento e semplifichi rollback e audit. Se preferisci partire con l’ultima versione disponibile, puoi farlo, ma sappi che stai accettando un cambiamento potenzialmente più variabile.

sudo -u uptimekuma git clone https://github.com/louislam/uptime-kuma.git /opt/uptime-kuma

Se il clone fallisce, le cause più comuni sono DNS, uscita verso GitHub bloccata o certificati CA mancanti. La verifica minima è curl -I https://github.com e, se serve, il controllo di connettività verso il resolver configurato sul server.

Installare le dipendenze e avviare l’applicazione

Dentro la directory del progetto installa le dipendenze npm. Questo passaggio può richiedere qualche minuto e dipende dalla velocità del server e dalla rete. Se stai lavorando su una macchina con poco spazio libero, controlla prima il filesystem perché un ENOSPC durante l’installazione crea solo rumore e lascia l’installazione a metà.

cd /opt/uptime-kuma
sudo -u uptimekuma npm install

Per un primo test puoi avviare l’applicazione in foreground, così capisci subito se parte davvero. È utile per distinguere un problema applicativo da uno di servizio o di proxy.

sudo -u uptimekuma npm run start-server

Se tutto va bene, il processo resta in ascolto sulla porta interna predefinita, normalmente 3001. Il test rapido è:

curl -I http://127.0.0.1:3001

Atteso: una risposta HTTP valida, tipicamente 200 o comunque un’intestazione coerente con il servizio attivo. Se ottieni Connection refused, l’app non è partita o sta ascoltando su un indirizzo diverso. In quel caso il primo punto da leggere è l’output del terminale, perché spesso indica subito file mancanti, permessi errati o dipendenze non installate.

Creare il servizio systemd per Uptime Kuma

Per un server vero, il servizio deve essere gestito da systemd. In questo modo hai avvio automatico al boot, restart controllato in caso di crash e un punto unico di osservazione con systemctl status e journal. Il blast radius qui è limitato al servizio applicativo, e il rollback consiste nel disabilitare l’unità e tornare all’avvio manuale, se necessario.

sudo nano /etc/systemd/system/uptime-kuma.service

Inserisci una unità come questa:

[Unit]
Description=Uptime Kuma
After=network-online.target
Wants=network-online.target [Service]
Type=simple
User=uptimekuma
Group=uptimekuma
WorkingDirectory=/opt/uptime-kuma
ExecStart=/usr/bin/npm run start-server
Restart=always
RestartSec=5
Environment=NODE_ENV=production [Install]
WantedBy=multi-user.target

Ricarica systemd e abilita il servizio:

sudo systemctl daemon-reload
sudo systemctl enable --now uptime-kuma

Verifica lo stato con:

systemctl status uptime-kuma --no-pager
journalctl -u uptime-kuma -n 50 --no-pager

Condizione OK: unità active (running) e nessun errore ricorrente nel journal. Se vedi code=exited o restart continui, il problema è quasi sempre nel percorso di lavoro, nei permessi o nella chiamata a npm. In quel caso controlla che /usr/bin/npm esista davvero e che l’utente uptimekuma possa leggere e scrivere nella directory del progetto.

Esporre Uptime Kuma dietro Nginx

Non esporre direttamente la porta 3001 su Internet. Un reverse proxy ti consente di gestire TLS, header corretti, eventuale redirect HTTP→HTTPS e log più leggibili. Se il server ha già altri siti, puoi aggiungere un nuovo virtual host senza toccare il resto.

sudo nano /etc/nginx/sites-available/uptime-kuma

Usa una configurazione di base come questa, sostituendo monitor.example.com con il tuo nome host:

server { listen 80; server_name monitor.example.com; location / { proxy_pass http://127.0.0.1:3001; proxy_http_version 1.1; proxy_set_header Host $host; proxy_set_header X-Real-IP $remote_addr; proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; proxy_set_header X-Forwarded-Proto $scheme; proxy_set_header Upgrade $http_upgrade; proxy_set_header Connection "upgrade"; }
}

Abilita il sito e verifica la sintassi prima di ricaricare Nginx:

sudo ln -s /etc/nginx/sites-available/uptime-kuma /etc/nginx/sites-enabled/
sudo nginx -t
sudo systemctl reload nginx

La verifica nginx -t è il controllo minimo da fare sempre. Se fallisce, non ricaricare il servizio: correggi prima il file di configurazione. L’output atteso è una sintassi valida e un riferimento alla configurazione testata. Se il reload va a buon fine ma il sito mostra errore 502, significa che Nginx non riesce a raggiungere il backend sulla porta 3001 oppure che il servizio non è in ascolto.

Abilitare HTTPS con Let’s Encrypt

Per un pannello di monitoraggio esposto all’esterno, HTTPS non è opzionale. Con Certbot puoi ottenere e rinnovare automaticamente il certificato, a patto che il DNS punti già al server e che le porte 80 e 443 siano raggiungibili. Se usi un firewall locale o un security group del provider, controlla prima quel livello.

sudo apt -y install certbot python3-certbot-nginx
sudo certbot --nginx -d monitor.example.com

Durante la procedura, Certbot può riscrivere il blocco server per forzare il redirect verso HTTPS. È comodo, ma conviene rileggere il file finale in /etc/nginx/sites-available/uptime-kuma per capire esattamente cosa è stato aggiunto. Il rollback, se necessario, consiste nel ripristino della configurazione precedente da backup o snapshot del file.

Dopo l’emissione del certificato, testa il rinnovo:

sudo certbot renew --dry-run

Se il dry run fallisce, la causa è quasi sempre un problema di reachability HTTP verso il challenge path o una configurazione Nginx non allineata. La verifica utile è leggere il log di Certbot e, se serve, fare un curl -I http://monitor.example.com/.well-known/acme-challenge/test per capire se il traffico arriva al server.

Primo accesso e configurazione iniziale

A questo punto apri il dominio nel browser. Uptime Kuma mostra la procedura guidata iniziale per creare l’account amministratore e definire le impostazioni di base. Qui conviene scegliere una password robusta e, se possibile, limitare l’accesso con ulteriori barriere a monte, come VPN o allowlist IP, soprattutto se il pannello non deve essere pubblico.

Le prime cose da impostare sono il fuso orario corretto, la lingua se necessaria e i canali di notifica. Il valore operativo non sta solo nei monitor, ma nella qualità degli alert: una notifica ben configurata è molto più utile di dieci monitor lasciati con parametri generici.

Monitor da creare per primi

Per partire con criterio, crea subito monitor semplici e rappresentativi: homepage del sito, endpoint healthcheck dell’applicazione, DNS pubblico del dominio e connettività verso il database solo se ha senso nel tuo contesto. Evita di partire con una lista troppo lunga: meglio pochi segnali affidabili che una foresta di alert difficili da leggere.

Un approccio sensato è questo:

  1. Un monitor HTTP per la home page, così intercetti errori 5xx e tempi di risposta anomali.
  2. Un monitor TCP su una porta critica, se vuoi verificare la raggiungibilità del servizio a basso livello.
  3. Un monitor DNS per il dominio principale, utile quando vuoi separare problemi di risoluzione da problemi applicativi.
  4. Un monitor keyword o stringa, se devi controllare una pagina che può restituire HTTP 200 ma contenuto errato.

Per ogni monitor definisci il timeout con criterio. Un timeout troppo aggressivo genera falsi positivi; uno troppo largo rende inutile il rilevamento. La metrica da osservare dopo l’attivazione è il tasso di errori reali rispetto ai falsi allarmi nelle prime 24–48 ore.

Backup e manutenzione operativa

Il dato importante di Uptime Kuma non è nella configurazione di sistema, ma nel suo stato applicativo: database interno, impostazioni, monitor e storico. Prima di aggiornare o migrare, individua il percorso dati del progetto e includilo nei backup. Se hai installato tutto in /opt/uptime-kuma, il contenuto utile è tipicamente dentro la directory dell’applicazione, ma va verificato sul server perché la struttura può cambiare con le release.

Prima di un aggiornamento, ferma il servizio, fai una copia del percorso dati e salva anche la configurazione del reverse proxy. Il rollback minimo consiste nel ripristino della directory applicativa e del file di unità systemd, poi nel riavvio del servizio. Se usi snapshot del volume, il ripristino è ancora più semplice, ma va testato almeno una volta in ambiente di prova.

Per aggiornare il codice applicativo senza cambiare schema operativo, il flusso tipico è:

sudo systemctl stop uptime-kuma
cd /opt/uptime-kuma
sudo -u uptimekuma git pull
sudo -u uptimekuma npm install
sudo systemctl start uptime-kuma

Questo è un cambiamento controllato con blast radius limitato, ma non va trattato come banale: se il pull introduce una release incompatibile, il rollback richiede di tornare al commit precedente o a una copia del filesystem. Prima di farlo in produzione, annota il commit attuale con git rev-parse HEAD.

Verifiche finali dopo l’installazione

Una volta completata la configurazione, fai una verifica minima su tre livelli: servizio, proxy e accesso esterno. Sul server, systemctl status uptime-kuma deve mostrare il servizio attivo; Nginx deve passare il traffico senza errori in error.log; dal browser il pannello deve aprirsi in HTTPS con certificato valido.

Se qualcosa non torna, il primo punto da leggere è il journal dell’applicazione. In pratica, la sequenza giusta è questa: controlli il servizio locale, poi il proxy, poi il DNS pubblico. Saltare direttamente al browser spesso fa perdere tempo, perché un errore visibile fuori può nascere molto prima nella catena.

Una checklist finale utile è questa:

  • Servizio: systemctl is-active uptime-kuma restituisce active.
  • Backend: curl -I http://127.0.0.1:3001 risponde correttamente.
  • Proxy: nginx -t è OK e il reload non produce errori.
  • TLS: il dominio apre in HTTPS e il rinnovo certbot renew --dry-run passa.
  • Backup: esiste una copia del percorso dati e del file di unità systemd.

Con questa base Uptime Kuma resta semplice da gestire e abbastanza robusto per un uso serio su Ubuntu 22.04 LTS. La parte davvero importante non è solo installarlo, ma mantenerlo leggibile, aggiornabile e recuperabile quando qualcosa cambia.