Come eseguire il self-hosting di Uptime Kuma nel 2026: avvisi, TLS e dati persistenti

La maggior parte delle note sull'installazione di Uptime Kuma si ferma al primo caricamento della pagina. È troppo presto: il volume dati è in sola lettura oppure il DNS del container non riesce a risolvere gli host monitorati. Un test di produzione utile è più impegnativo: crea monitor HTTP e TCP, forza un errore controllato e ricevi l'avviso e la notifica di ripristino tramite il provider scelto.

Il ruolo di Uptime Kuma è semplice: monitorare servizi esistenti con avvisi verso più di 90 destinazioni. Il suo perimetro operativo comprende più del solo processo web, quindi dipendenza, stato persistito e route pubblica devono essere indicati esplicitamente prima che arrivino dati reali.

Definisci prima cosa significa successo per Uptime Kuma

Un diagramma utile di Uptime Kuma mostra la route pubblica, la porta privata 3001, il perimetro dello stato e ogni requisito di supporto. Indica quali frecce trasportano credenziali e quali rappresentano il normale traffico degli utenti. Il requisito esterno di Uptime Kuma è l'accesso in uscita a ogni endpoint monitorato e a ogni provider di avvisi. Testa il DNS in uscita, il TLS e il comportamento del provider senza pubblicare un altro servizio in ingresso.

Dimostra il diagramma con un'azione reale: crea monitor HTTP e TCP, forza un errore controllato e ricevi l'avviso e la notifica di ripristino tramite il provider scelto. Il carico probabile deriva dall'intervallo dei monitor, dal numero di tentativi, dal traffico della status page e dal numero di probe in uscita eseguiti nello stesso secondo; monitora questo percorso invece di trattare tutte le richieste HTTP allo stesso modo.

Gestisci Uptime Kuma tenendo conto del suo vero collo di bottiglia

La prima metrica operativa utile per Uptime Kuma indica se riesce a creare monitor HTTP e TCP, forzare un errore controllato e ricevere l'avviso e la notifica di ripristino tramite il provider scelto. Affiancala ai segnali di saturazione relativi all'intervallo dei monitor, al numero di tentativi, al traffico della status page e al numero di probe in uscita eseguiti nello stesso secondo. Un probe che controlla solo il processo non dovrebbe chiamare dipendenze costose né riavviare il container perché un upstream è temporaneamente non disponibile.

Tratta gli aggiornamenti come modifiche ai dati, perché le migrazioni SQLite e le modifiche ai provider di notifiche possono trasformare un rapido pull dell'immagine in un aggiornamento di un'applicazione stateful. Fissa le versioni, prova la procedura sullo stato ripristinato e conserva l'immagine precedente finché il rollback resta valido. Quando il volume dati è in sola lettura oppure il DNS del container non riesce a risolvere gli host monitorati, conserva i log precedenti al riavvio: di solito contengono il messaggio che indica la causa.

Registra una distribuzione Uptime Kuma di riferimento

Per Uptime Kuma, definisci una transazione di riferimento prima del lancio: crea monitor HTTP e TCP, forza un errore controllato e ricevi l'avviso e la notifica di ripristino tramite il provider scelto. Inserisci i prerequisiti, la risposta attesa e i passaggi di pulizia nel version control, senza valori segreti. Fissa l'immagine utilizzata per stabilire questo riferimento.

Usa la transazione per validare una sostituzione e un ripristino indipendente. Il servizio ripristinato è accettabile solo quando ricompaiono la cronologia dei monitor, le credenziali delle notifiche e le finestre di manutenzione e un avviso di test viene ancora recapitato. Allo stesso tempo, osserva l'intervallo dei monitor, il numero di tentativi, il traffico della status page e il numero di probe in uscita eseguiti nello stesso secondo, quindi trasforma la parte più lenta o più soggetta a vincoli in un avviso a livello di servizio.

Il gate deve includere anche un caso negativo: nega temporaneamente il percorso di test utilizzato per l'accesso in uscita a ogni endpoint monitorato e a ogni provider di avvisi. Verifica che Uptime Kuma produca un errore utilizzabile senza perdere dati, ripristina la condizione valida e ripeti la transazione di riferimento. Conservare entrambi i risultati impedisce che un health endpoint superficiale diventi l'unica prova disponibile in produzione.

Impostazioni del container da verificare

Usa il container come runtime sostituibile, non come sede della verità.

docker run -d \
  --name uptime-kuma \
  --restart unless-stopped \
  -p 127.0.0.1:3001:3001 \
  -v uptime-kuma-data:/app/data \
  -e UPTIME_KUMA_PORT=3001 \
  louislam/uptime-kuma:1

Consenti e verifica il percorso in uscita o lato client necessario per raggiungere ogni endpoint monitorato e ogni provider di avvisi. Controlla l'utente del container, i percorsi scrivibili e il listener associato prima di esporlo. Esegui l'azione completa — crea monitor HTTP e TCP, forza un errore controllato e ricevi l'avviso e la notifica di ripristino tramite il provider scelto — e salva il riferimento esatto all'immagine che ha prodotto il risultato.

Ripristina Uptime Kuma su un host vuoto

Proteggi lo stato di Uptime Kuma prima di ottimizzare il container. Il set necessario comprende il database SQLite e gli asset caricati in /app/data. Monta /app/data prima del bootstrap, scrivi dati di esempio innocui e sostituisci il container per dimostrare che quel percorso è effettivamente persistente. Se più storage devono restare coerenti, documenta l'ordine in cui mettere in pausa le scritture ed eseguire i backup.

Conserva copie esterne al server di deployment e cifra il materiale che contiene credenziali o contenuti privati. Il ripristino ha esito positivo quando ricompaiono la cronologia dei monitor, le credenziali delle notifiche e le finestre di manutenzione e un avviso di test viene ancora recapitato. La distinzione tra un mount persistente e una copia indipendente è illustrata nella guida a storage persistente e snapshot.

Assegna a Uptime Kuma un indirizzo canonico

Pubblica un'unica origine HTTPS stabile tramite il reverse proxy. Invia l'hostname scelto alla porta 3001 del container, inoltra l'host originale e lo schema HTTPS ed evita di pubblicare una seconda origine diretta.

Testa Uptime Kuma da un client esterno pulito. Distingui un errore di ingresso dal perimetro applicativo noto — il volume dati è in sola lettura oppure il DNS del container non riesce a risolvere gli host monitorati. Un errore di certificato, DNS o 502 appartiene al routing; una richiesta che raggiunge Uptime Kuma e fallisce in seguito riguarda lo stato dell'applicazione, la capacità o un suo requisito di supporto. La guida al TLS automatico per domini personalizzati tratta il primo gruppo.

Decisioni di sicurezza specifiche per Uptime Kuma

Il rischio di sicurezza specifico dell'applicazione consiste nell'eseguire la configurazione del primo utente su un'istanza esposta pubblicamente. La risposta operativa è completare la configurazione del primo utente in privato, quindi proteggere separatamente le dashboard e l'amministrazione della status page. Completa il bootstrap tramite una route riservata e rimuovi immediatamente dopo l'accesso temporaneo alla configurazione.

UPTIME_KUMA_PORT controlla il comportamento, non la riservatezza; verifica il tipo e il valore e conserva separatamente le vere credenziali di Uptime Kuma. Concedi al processo Uptime Kuma solo i mount e le route verso le dipendenze documentati; evita l'accesso a root dell'host e al socket Docker. Registra i tentativi di autenticazione falliti e gli errori di configurazione, ma oscura token, connection string e contenuti degli utenti.

Anche un deployment Dockup richiede un acceptance test per Uptime Kuma

Routing, certificati, sostituzione del servizio e storage collegato sono obiettivi ragionevoli per l'automazione. Dockup li gestisce per Uptime Kuma e può effettuare il provisioning del database gestito correlato oppure connettersi ai servizi presenti sul server del cliente.

Non dovrebbe però inventare la trust policy di Uptime Kuma. Dopo il deployment, pubblica un'unica origine HTTPS stabile tramite il reverse proxy, applica questo perimetro — completa la configurazione del primo utente in privato, quindi proteggi separatamente le dashboard e l'amministrazione della status page — e verifica il risultato di questo scenario: crea monitor HTTP e TCP, forza un errore controllato e ricevi l'avviso e la notifica di ripristino tramite il provider scelto. Il risultato è un'infrastruttura one-click con un acceptance test specifico per l'applicazione.

Domande frequenti

Di cosa ha bisogno Uptime Kuma per un deployment in produzione?

Instrada il container Uptime Kuma sulla porta 3001 attraverso un'unica origine HTTPS. Il requisito esterno per la consegna è l'accesso in uscita a ogni endpoint monitorato e a ogni provider di avvisi. Non considerare Uptime Kuma pronto finché non puoi creare monitor HTTP e TCP, forzare un errore controllato e ricevere l'avviso e la notifica di ripristino tramite il provider scelto.

Quali dati di Uptime Kuma devono essere inclusi in un backup?

Rendi persistente /app/data e includi nello stesso recovery manifest il database SQLite e gli asset caricati in /app/data. Un ripristino pulito di Uptime Kuma è riuscito solo quando ricompaiono la cronologia dei monitor, le credenziali delle notifiche e le finestre di manutenzione e un avviso di test viene ancora recapitato.

Uptime Kuma richiede HTTPS dietro un reverse proxy?

Usa HTTPS per l'origine pubblica di Uptime Kuma e mantieni la porta 3001 sulla route interna. Applica correttamente l'impostazione di Uptime Kuma: pubblica un'unica origine HTTPS stabile tramite il reverse proxy. Per Uptime Kuma, HTTPS protegge durante il transito le credenziali o i contenuti degli utenti e mantiene coerente il comportamento del client sensibile all'origine.

Come si deve testare un aggiornamento di Uptime Kuma?

Ripristina lo stato corrente di Uptime Kuma in un deployment isolato, applica la versione candidata e ripeti la relativa transazione di accettazione. Presta particolare attenzione perché le migrazioni SQLite e le modifiche ai provider di notifiche possono trasformare un rapido pull dell'immagine in un aggiornamento di un'applicazione stateful. Conserva l'immagine precedente di Uptime Kuma finché non avrai compreso i limiti della migrazione dei dati e del rollback.