Monitorare i propri servizi con Uptime Kuma
Installa Uptime Kuma con Docker Compose su Debian o Ubuntu, proteggi l'accesso in HTTPS, crea i tuoi monitor e le tue notifiche, poi gestisci aggiornamenti e backup.
In questa pagina
I tuoi valori
Inseriscili una volta: i comandi della guida si aggiornano.
Uptime Kuma è uno strumento di monitoraggio self-hosted. Controlla regolarmente i tuoi siti, le tue porte e i tuoi servizi, conserva lo storico della loro disponibilità e ti avvisa in caso di guasto.
Al termine di questa guida, Uptime Kuma gira in Docker, ascolta solo sull'indirizzo locale del server e risponde in HTTPS dietro Caddy, con un accesso protetto. Avrai creato un primo monitor e una notifica, e saprai aggiornare l'istanza ed eseguirne il backup.
Ordina un Server
Questa guida si applica ai server che amministri tu stesso:
Prerequisiti
- Un server con Debian 12 o 13, oppure Ubuntu 22.04 o 24.04
- Un accesso SSH con un utente che dispone di
sudo - Docker Engine e Docker Compose, installati con la guida Installare Docker Engine e Docker Compose
- Caddy, installato con la guida Caddy come reverse proxy
- Un record A per
uptime.tuo-dominio.comversoIP_DEL_TUO_SERVER - Un disco locale per i dati: le condivisioni di rete come NFS non sono supportate
I comandi docker presuppongono che il tuo utente appartenga al gruppo docker. In caso contrario, aggiungi sudo davanti.
Questa guida usa la versione 2.5.12, l'ultima versione stabile al momento della stesura. Controlla la versione attuale nella pagina delle versioni di Uptime Kuma. Il ramo 3 è ancora in beta: non usarlo in produzione.
Porte utilizzate
| Porta | Direzione | Ruolo | Da aprire |
|---|---|---|---|
| 80/tcp | In entrata | Certificato e reindirizzamento a HTTPS, tramite Caddy | Sì |
| 443/tcp | In entrata | Accesso HTTPS, tramite Caddy | Sì |
| 3001/tcp | Locale | Interfaccia di Uptime Kuma, su 127.0.0.1 |
No |
Il server deve anche poter raggiungere, in uscita, i servizi monitorati e i tuoi servizi di notifica.
Passo 1: creare il progetto Compose
sudo mkdir -p /opt/uptime-kuma
sudo chown "$USER": /opt/uptime-kuma
cd /opt/uptime-kuma
nano compose.yamlIncolla questa configurazione:
services:
uptime-kuma:
image: louislam/uptime-kuma:2.5.12
container_name: uptime-kuma
restart: unless-stopped
ports:
- "127.0.0.1:3001:3001"
volumes:
- ./data:/app/dataAvvia il container:
docker compose config --quiet
docker compose up -d
docker compose psIl container deve risultare avviato (Up). Il suo controllo di integrità può restare nello stato starting durante i primi minuti.
Passo 2: creare l'account tramite un tunnel SSH
Il primo visitatore crea l'account amministratore. Fallo quindi prima di pubblicare il sito. In un terminale sul tuo computer:
ssh -N -L 3001:127.0.0.1:3001 TUO_USER@IP_DEL_TUO_SERVERIl comando resta attivo senza mostrare nulla. Apri poi http://localhost:3001, quindi:
- Scegli la tua lingua.
- Seleziona il database SQLite, adatto a un'installazione di dimensioni contenute.
- Attendi la preparazione del database.
- Crea l'account amministratore con una password lunga e unica.
Passo 3: rafforzare l'account
In Settings (Impostazioni):
| Sezione | Impostazione | Valore |
|---|---|---|
| Security | 2FA Settings | Attiva l'autenticazione a due fattori con un'applicazione TOTP |
| Security | Disable Auth | Non attivarla |
| Reverse Proxy | Trust Proxy | Yes, perché il servizio è raggiungibile solo tramite Caddy |
Trust Proxy permette di mostrare nei log il vero indirizzo dei visitatori. Attiva questa opzione solo se la porta 3001 resta limitata a 127.0.0.1.
Passo 4: pubblicare l'interfaccia con Caddy
Scegli la modalità adatta al tuo utilizzo.
Accesso limitato al tuo indirizzo (consigliato)
Solo il tuo indirizzo IP raggiunge l'interfaccia. Gli URL /api/push/ restano accessibili, così le tue attività pianificate possono inviare i loro segnali. Aggiungi questo sito in /etc/caddy/Caddyfile:
uptime.tuo-dominio.com {
@push path /api/push/*
@allowed client_ip TUO_IP
handle @push {
reverse_proxy 127.0.0.1:3001
}
handle @allowed {
reverse_proxy 127.0.0.1:3001
}
handle {
abort
}
}Se il tuo indirizzo cambia spesso, passa piuttosto da WireGuard o Tailscale.
Accesso pubblico con pagina di stato
Una pagina di stato deve restare visibile ai tuoi utenti. In questo caso, anche l'interfaccia di accesso è raggiungibile: l'autenticazione a due fattori del passo 3 diventa indispensabile.
uptime.tuo-dominio.com {
reverse_proxy 127.0.0.1:3001
}Applicare la configurazione
Caddy inoltra da solo i WebSocket di cui Uptime Kuma ha bisogno. Poiché Caddy è installato sul server e non in Docker, UFW si applica alle sue porte:
sudo ufw allow 80,443/tcp comment 'Caddy'
sudo -u caddy caddy validate --config /etc/caddy/Caddyfile --adapter caddyfile
sudo systemctl reload caddyVerificare il risultato
Puoi chiudere il tunnel con Ctrl+C. Apri https://uptime.tuo-dominio.com: deve comparire la pagina di accesso con un certificato valido. Sul server, controlla la porta:
docker ps --filter name=uptime-kuma --format '{{.Names}} {{.Status}} {{.Ports}}'L'output deve contenere 127.0.0.1:3001->3001/tcp. Da un'altra macchina, la porta 3001 non deve essere aperta:
nmap -Pn -p 3001 IP_DEL_TUO_SERVERCon l'accesso limitato, una connessione da un indirizzo diverso dal tuo deve essere interrotta.
Passo 5: aggiungere un primo monitor
- Clicca su Add New Monitor.
- In Monitor Type, scegli HTTP(s).
- Compila Friendly Name, poi inserisci l'indirizzo da monitorare in URL, ad esempio
https://www.tuo-dominio.com. - Imposta Heartbeat Interval (l'intervallo tra due controlli) e Retries (il numero di nuovi tentativi prima dell'avviso).
- Attiva Certificate Expiry Notification per essere avvisato prima della scadenza del certificato.
- Clicca su Save.
I tipi di monitor più utili:
| Tipo | Utilizzo |
|---|---|
| HTTP(s) | Sito o API, con controllo del codice di risposta |
| HTTP(s) - Keyword | Presenza di una parola nella pagina |
| TCP Port | Servizio in ascolto su una porta, come SSH o un database |
| Ping | Risposta di rete di una macchina |
| DNS | Risoluzione di un nome di dominio |
| Push | Attività pianificata che segnala da sola la propria esecuzione |
Monitorare un'attività pianificata
Crea un monitor Push e copia il suo Push URL. Richiamalo alla fine del tuo script, solo se questo riesce:
/usr/local/bin/mio-backup.sh && curl -fsS -m 10 --retry 3 "https://uptime.tuo-dominio.com/api/push/TUO_TOKEN?status=up&msg=OK"Sostituisci TUO_TOKEN con il valore del tuo URL. Se non arriva alcun segnale entro il tempo previsto, il monitor passa allo stato DOWN. Considera questo URL un segreto.
Passo 6: configurare le notifiche
Apri Settings > Notifications, poi clicca su Set Up Notification. Uptime Kuma supporta numerosi servizi. L'esempio seguente usa Telegram:
- In Telegram, scrivi a @BotFather, invia
/newbote copia il token ottenuto. - Invia un messaggio al tuo nuovo bot.
- In Uptime Kuma, scegli Telegram in Notification Type.
- Incolla il token in Bot Token.
- Clicca su Auto Get per compilare Chat ID.
- Attiva Default enabled per applicarla ai prossimi monitor, e Apply on all existing monitors per quelli già esistenti.
- Clicca su Test. Se il messaggio arriva, clicca su Save.
Per un'e-mail, scegli Email (SMTP) e inserisci i parametri forniti dal tuo servizio di posta, preferibilmente con un account dedicato.
Una notifica funziona solo se è associata al monitor. Verificalo nella colonna Notifications della scheda di ogni monitor.
Creare una pagina di stato
In Status Pages, clicca su New Status Page, scegli un nome e un indirizzo, poi aggiungi i monitor da mostrare. La pagina diventa accessibile su /status/nome-scelto. È pensata per essere pubblica e i suoi dati vengono memorizzati nella cache per 5 minuti.
Con l'accesso limitato del passo 4, sarà visibile solo dal tuo indirizzo. Per renderla pubblica, usa il secondo blocco Caddy.
Aggiornare Uptime Kuma
Esegui prima il backup della cartella data e leggi le note di rilascio. Sostituisci poi il tag in compose.yaml, quindi esegui:
cd /opt/uptime-kuma
nano compose.yaml
docker compose pull
docker compose up -d --force-recreate
docker compose psResta sul ramo 2 finché non hai letto la guida alla migrazione alla versione 3. Questa migrazione modifica il database e non consente di tornare indietro senza un backup.
Backup e ripristino
La cartella data è l'unico elemento di cui eseguire il backup, insieme a compose.yaml. È il metodo supportato dal progetto: la vecchia esportazione JSON è stata rimossa nella versione 2.
cd /opt/uptime-kuma
mkdir -p backups
docker compose stop
sudo tar -czf "backups/uptime-kuma-$(date +%F).tar.gz" data compose.yaml
docker compose start
sudo chmod 600 backups/*.tar.gzL'archivio contiene il database, gli account e i token di notifica. Copialo fuori dal server, in una posizione cifrata.
Per ripristinare un archivio, sostituendo AAAA-MM-GG con la sua data:
cd /opt/uptime-kuma
docker compose down
sudo mv data "data.vecchio-$(date +%F)"
sudo tar -xzf backups/uptime-kuma-AAAA-MM-GG.tar.gz
docker compose up -dUsa la stessa versione dell'immagine del backup, o una versione più recente dello stesso ramo.
In caso di problemi
Cannot connect to the socket server
L'interfaccia non riesce ad aprire la connessione WebSocket. Verifica che il container sia in esecuzione e consulta i suoi log:
docker compose ps
docker compose logs --tail=50 uptime-kumaSe un altro proxy, come Cloudflare, si trova davanti a Caddy, verifica che i WebSocket siano attivati e che il nome di dominio originale venga trasmesso correttamente.
Errore 502 con Caddy
Caddy non raggiunge l'applicazione. Verifica la porta locale:
curl -I http://127.0.0.1:3001
sudo journalctl -u caddy --no-pager -n 50Un monitor indica DOWN anche se il servizio risponde
Il controllo parte dal container, la cui rete è diversa da quella del tuo computer. Prova dal container, adattando l'indirizzo:
docker exec uptime-kuma node -e "fetch('https://www.tuo-dominio.com').then(r => console.log(r.status)).catch(console.error)"Verifica anche che il servizio monitorato non blocchi l'indirizzo del server, ad esempio con un firewall o CrowdSec.
Un monitor IPv6 non riesce
Per impostazione predefinita, la rete Docker del container non usa IPv6. Se il servizio è raggiungibile solo in IPv6, aggiungi una rete con IPv6 a compose.yaml:
services:
uptime-kuma:
networks:
- uptime-kuma-net
networks:
uptime-kuma-net:
enable_ipv6: trueUnisci queste chiavi al tuo servizio esistente, poi riesegui docker compose up -d.
I segnali Push non arrivano
Prova l'URL con curl -i dalla macchina che esegue l'attività. Una connessione interrotta indica generalmente che in Caddy manca il blocco @push. La risposta deve contenere "ok":true.
Non arriva alcuna notifica
Usa il pulsante Test e leggi il messaggio di errore. Verifica poi che la notifica sia attivata sul monitor. Per un invio SMTP, controlla l'host, la porta e l'identificativo presso il tuo servizio di posta.
Password persa o autenticazione a due fattori inaccessibile
Esegui il comando adatto, poi segui le istruzioni mostrate:
docker exec -it uptime-kuma npm run reset-password
docker exec -it uptime-kuma npm run remove-2fadatabase is locked o database danneggiato
Verifica che data si trovi su un disco locale e non su NFS, e che lo spazio su disco sia sufficiente con df -h. Se il database è danneggiato, ripristina il tuo ultimo backup.
port is already allocated
Un altro servizio occupa la porta 3001. Individualo con sudo ss -ltnp | grep ':3001 '. Per cambiare porta, modifica solo la parte sinistra, ad esempio 127.0.0.1:3002:3001, poi adatta Caddy.