Come aggiornare Uptime Kuma su Debian 12

Su Debian 12, aggiornare Uptime Kuma non è un’operazione unica: dipende da come lo hai installato. La differenza reale è tra una gestione con systemd + git, una installazione dentro Docker o un deploy manuale in una directory dedicata. Se salti questo passaggio, rischi di fare l’update nel posto sbagliato e di rompere il servizio invece di aggiornarlo.

La regola pratica è semplice: prima identifichi il metodo di installazione, poi fai un backup minimo ma utile, quindi aggiorni con una procedura reversibile, infine controlli che il servizio risponda e che i dati storici siano ancora lì. Uptime Kuma salva configurazione e storico in un database SQLite, quindi la parte critica non è il binario in sé, ma il file dati e il servizio che lo espone.

Capire come è installato prima di toccare nulla

La prima cosa da verificare è se Uptime Kuma gira come servizio systemd, come container Docker, oppure come processo lanciato a mano. Senza questa informazione, l’aggiornamento diventa un tentativo alla cieca.

Se usi systemd, cerca l’unità e il percorso dell’installazione:

systemctl status uptime-kuma --no-pager
systemctl cat uptime-kuma

Nel file dell’unità ti interessa soprattutto la riga ExecStart: di solito mostra il path del binario o dello script di avvio. Se vedi riferimenti a una directory tipo /opt/uptime-kuma, molto probabilmente stai usando la modalità classica con repository git.

Se invece sospetti Docker, controlla i container attivi:

docker ps --format 'table {{.Names}}	{{.Image}}	{{.Status}}'

Se compare un container di Uptime Kuma, l’aggiornamento passa dall’immagine e non dal codice locale. Questo cambia completamente la procedura.

Se non trovi né systemd né Docker, cerca il processo e la directory di lavoro:

ps aux | grep -i uptime-kuma | grep -v grep
pwdx <PID>

Questo ti dice dove vive davvero l’applicazione. Il punto non è essere eleganti: è evitare di aggiornare una copia morta mentre il servizio vero gira altrove.

Backup minimo: file dati, unità e versione attuale

Prima di aggiornare, salva almeno tre cose: il database SQLite, l’unità systemd se esiste, e il commit o tag attuale. Se qualcosa va storto, il rollback deve essere rapido e senza ambiguità.

Nel caso più comune con installazione in /opt/uptime-kuma, il file dati è spesso sotto data/. Verifica il contenuto della directory:

cd /opt/uptime-kuma
ls -lah
find . -maxdepth 2 -type f | sort

Se trovi un file come kuma.db o un database SQLite simile, quello è il pezzo da preservare con cura. Un backup rapido ma sensato può essere fatto così:

sudo systemctl stop uptime-kuma
sudo cp -a /opt/uptime-kuma/data /root/backup-uptime-kuma-data-$(date +%F)
sudo systemctl start uptime-kuma

Se vuoi fare un backup più pulito e ridurre il rischio di corruzione, fermare il servizio prima della copia è la scelta corretta. Se il servizio è molto usato e non puoi fermarlo a lungo, devi valutare una finestra di manutenzione o un backup con snapshot del filesystem, ma lì dipende dallo storage e non si improvvisa.

Salva anche la configurazione del servizio:

sudo cp -a /etc/systemd/system/uptime-kuma.service /root/backup-uptime-kuma.service.$(date +%F)

Infine annota la versione attuale. Se l’installazione è da repository git, basta:

cd /opt/uptime-kuma
git rev-parse --short HEAD
git status --short

Se git status mostra modifiche locali, non ignorarle: potrebbero essere personalizzazioni operative o tentativi precedenti di update. In quel caso il rollback va pensato con più attenzione.

Aggiornamento con installazione systemd + git

Questa è la strada più comune su Debian 12 quando Uptime Kuma è installato in una directory dedicata e avviato da un’unità systemd. L’idea è: fermi il servizio, aggiorni il repository, reinstalli le dipendenze se necessario, poi riavvii.

Procedura base:

1. Ferma il servizio.
2. Entra nella directory di installazione.
3. Scarica gli aggiornamenti dal repository remoto.
4. Installa o riallinea le dipendenze.
5. Riavvia il servizio e controlla i log.

Esempio pratico:

sudo systemctl stop uptime-kuma
cd /opt/uptime-kuma
git fetch --all --tags

git status --short
git pull --ff-only

npm ci --omit=dev
sudo systemctl start uptime-kuma

Il comando git pull --ff-only è importante: evita merge automatici poco chiari. Se fallisce, hai un segnale utile: il ramo locale non è in uno stato lineare e devi capire perché invece di forzare. npm ci --omit=dev riallinea le dipendenze in modo ripetibile, ma funziona bene solo se il progetto è in uno stato coerente. Se la tua installazione usa un metodo diverso, segui quello previsto dal pacchetto o dal repository ufficiale dell’istanza.

Dopo l’avvio, controlla subito i log:

sudo journalctl -u uptime-kuma -n 100 --no-pager

Qui cerchi tre cose: errori di startup, problemi di porta occupata e errori legati al database. Se il servizio parte ma l’interfaccia non risponde, il log di systemd è il primo posto da guardare, non il browser.

Aggiornamento se Uptime Kuma gira in Docker

Se l’istanza è containerizzata, l’update non si fa con git pull nella directory host, ma con il refresh dell’immagine e la ricreazione del container. La logica resta la stessa: preservi i volumi, aggiorni l’immagine, riavvii il servizio contenitore.

Prima identifica nome container, immagine e volume montato:

docker inspect uptime-kuma --format '{{json .Mounts}}' | jq

docker inspect uptime-kuma --format '{{.Config.Image}}'

Se non hai jq, puoi leggere il JSON grezzo, ma con jq è più veloce capire dove sta il volume. Il dato importante è il mount persistente: senza quello, ogni ricreazione rischia di perdere configurazione e storico.

Update tipico:

docker stop uptime-kuma

docker pull louislam/uptime-kuma:latest

docker rm uptime-kuma

docker run -d \
  --name uptime-kuma \
  -p 3001:3001 \
  -v /opt/uptime-kuma/data:/app/data \
  --restart=always \
  louislam/uptime-kuma:latest

Qui il rischio principale è il volume sbagliato. Se il path host non punta a /app/data, oppure se il container precedente usava un nome diverso, potresti avviare una nuova istanza “vuota” e credere che l’update abbia cancellato i dati. In realtà hai solo montato il posto sbagliato.

Se usi Docker Compose, è ancora meglio aggiornare con un file versionato. In quel caso la sequenza è:

docker compose pull
docker compose up -d

Se il servizio è dietro reverse proxy, verifica anche che la porta interna e il nome servizio non siano cambiati. Un container sano ma non raggiungibile sembra spesso un problema dell’app, ma è solo un problema di routing.

Controlli dopo l’update: non fidarti solo della home page

Il controllo serio non è “la pagina si apre”. Devi verificare che il processo sia attivo, che il database sia leggibile e che almeno un monitor sia in stato coerente. Se hai un ambiente di produzione, controlla anche il comportamento delle notifiche e degli intervalli di polling.

Controlli minimi con systemd:

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

Se la risposta è active ma l’interfaccia non risponde, fai una prova locale:

curl -I http://127.0.0.1:3001

Atteso: un HTTP/1.1 200 OK o comunque una risposta coerente con l’endpoint. Se ottieni Connection refused, il servizio non sta ascoltando. Se ottieni un 5xx, il problema è più in alto, spesso applicativo o legato al database.

Controlla anche che il file dati esista e abbia una dimensione sensata:

ls -lh /opt/uptime-kuma/data

Se il database è improvvisamente a zero byte o manca, non andare avanti a tentoni: fermati e ripristina il backup. In SQLite, un file danneggiato o troncato non si sistema con un riavvio.

Rollback: quando fermarsi e tornare indietro

Il rollback va fatto subito se dopo l’update vedi errori di startup, database non leggibile, interfaccia vuota con log pieni di eccezioni, o perdita di monitor e impostazioni. Non aspettare che “si stabilizzi”.

Per installazione git/systemd, il rollback più pulito è tornare al commit precedente noto buono. Se hai preso nota del commit prima dell’update, puoi fare:

sudo systemctl stop uptime-kuma
cd /opt/uptime-kuma
git log --oneline -n 5
git checkout <commit_precedente>
npm ci --omit=dev
sudo systemctl start uptime-kuma

Se hai una release taggata, preferisci quella. Il vantaggio del tag è che riduce l’ambiguità: sai esattamente quale versione stai rimettendo in produzione.

Per Docker, il rollback consiste nel ripuntare all’immagine precedente:

docker stop uptime-kuma
docker rm uptime-kuma
docker run -d \
  --name uptime-kuma \
  -p 3001:3001 \
  -v /opt/uptime-kuma/data:/app/data \
  --restart=always \
  louislam/uptime-kuma:<tag_precedente>

Se non hai un tag precedente, è già un problema di processo, non di update. In produzione bisogna sapere in anticipo da dove si torna indietro.

Errori tipici su Debian 12 e come leggerli

Su Debian 12 i problemi più comuni non sono misteriosi. Cambiano i sintomi, ma il pattern è quasi sempre lo stesso.

• Porta occupata: il servizio non parte e nei log compare che la 3001 è già in uso. Verifica con ss -ltnp | grep 3001.
• Permessi sbagliati: il processo non può leggere o scrivere in /opt/uptime-kuma/data. Controlla owner e permessi con ls -ld e namei -l.
• Dipendenze incoerenti: dopo il pull, l’app crasha o resta in loop. Guarda journalctl e confronta il commit aggiornato con il precedente.
• Volume Docker errato: il container parte, ma l’interfaccia è vuota. Qui il problema è quasi sempre il mount persistente.

Un controllo utile sui permessi, se usi installazione locale:

namei -l /opt/uptime-kuma/data

Questo comando ti fa vedere tutti i passaggi di directory e i permessi effettivi. È più utile di un semplice ls quando il problema è un parent directory troppo restrittivo.

Routine consigliata per aggiornamenti futuri

Se vuoi evitare incidenti ripetuti, formalizza una routine. Non serve complicarla: basta che sia sempre la stessa e che lasci tracce verificabili.

1. Controlla il metodo di installazione e annota la versione attuale.
2. Fai backup del database e della configurazione del servizio.
3. Ferma il servizio in una finestra breve.
4. Aggiorna solo con metodo coerente con l’installazione reale.
5. Riavvia e verifica log, porta in ascolto e accesso web.
6. Conserva commit/tag precedente per un rollback immediato.

Se vuoi essere ancora più rigoroso, conserva in un file operativo interno il path dell’istanza, il nome del servizio, il volume Docker e il commit di riferimento. La manutenzione diventa molto più lineare quando non devi ricostruire tutto ogni volta.

Assunzione: l’istanza è su Debian 12 con privilegi amministrativi limitati al necessario, e l’obiettivo è aggiornare senza perdere storico, monitor e configurazione.