Come eseguire il self-hosting di Homarr nel 2026: dashboard, segreti e tile live

Un container Homarr può risultare attivo mentre l'attività che interessa agli utenti è interrotta. Nel caso di Homarr, questo problema nascosto consiste solitamente nell'impossibilità per i widget di raggiungere i servizi perché utilizzano indirizzi locali dell'host. Questa guida considera come test di accettazione la sequenza “creare una board, aggiungere una tile di servizio, configurare un'integrazione con credenziali e verificare lo stato live e la ricerca dopo un riavvio”, quindi progetta il deployment a ritroso partendo da questo risultato.

Homarr svolge un ruolo specifico nello stack: una dashboard ricercabile con tile live per i servizi self-hosted. La domanda da porsi in produzione non è quindi se la porta 7575 risponda una volta, ma se stato, dipendenze e indirizzo pubblico continuino a essere coerenti dopo un riavvio, un aggiornamento e un ripristino.

Definisci prima il risultato atteso per Homarr

Non lasciare che l'immagine di Homarr determini per caso l'architettura di produzione. L'immagine fornisce un processo sulla porta 7575; storage, routing e requisiti esterni richiedono comunque cicli di vita definiti intenzionalmente. Il requisito del runtime locale consiste in dati applicativi persistenti e credenziali per le integrazioni live. Questo deve rientrare nel piano di capacità e dei mount, con un responsabile e un limite misurabile.

Il deployment è pronto per test più approfonditi quando è in grado di creare una board, aggiungere una tile di servizio, configurare un'integrazione con credenziali e verificare lo stato live e la ricerca dopo un riavvio. Segui la transazione nei log e monitora la distribuzione delle richieste dei widget, la latenza delle API downstream, le dimensioni dei dati applicativi e il numero di client dashboard concorrenti. Queste osservazioni mostrano se la topologia attuale isola il componente corretto.

Prova in anticipo la modifica rischiosa a Homarr

Un container attivo è necessario, ma non sufficiente. L'indicatore di servizio è il completamento corretto della sequenza “creare una board, aggiungere una tile di servizio, configurare un'integrazione con credenziali e verificare lo stato live e la ricerca dopo un riavvio”, mentre i principali segnali di pressione sono la distribuzione delle richieste dei widget, la latenza delle API downstream, le dimensioni dei dati applicativi e il numero di client dashboard concorrenti.

Il change control è importante perché le migrazioni dello schema di Homarr e la continuità della chiave di crittografia possono influire sulle credenziali delle integrazioni memorizzate. Conserva la vecchia immagine, testa le migrazioni su una copia dello stato e documenta se il rollback è supportato dopo lo spostamento dello schema. Se i widget non riescono a raggiungere i servizi perché utilizzano indirizzi locali dell'host, individua il primo confine che differisce dall'ambiente funzionante.

Registra un deployment Homarr noto come funzionante

Non usare il traffico del primo utente come test di accettazione per Homarr. Prepara dati di esempio innocui ed esegui l'intera azione “creare una board, aggiungere una tile di servizio, configurare un'integrazione con credenziali e verificare lo stato live e la ricerca dopo un riavvio”. Annota l'URL pubblico esatto, il risultato, il riferimento dell'immagine e l'intervallo dei log associati all'esecuzione.

Sostituisci il container e ripeti l'operazione senza ricreare i dati. Poi esegui il ripristino su un host vuoto; la condizione di ripristino è che board, utenti, integrazioni e asset personalizzati vengano recuperati e che i widget con credenziali si riconnettano. Osserva la distribuzione delle richieste dei widget, la latenza delle API downstream, le dimensioni dei dati applicativi e il numero di client dashboard concorrenti a ogni passaggio e definisci un alert sulla degradazione della transazione, non sulle metriche di un container inattivo.

Un'ultima verifica dovrebbe fallire intenzionalmente: invia un input innocuo vicino al limite di risorse o di formato associato a questo confine: i widget non riescono a raggiungere i servizi perché utilizzano indirizzi locali dell'host. Verifica che il messaggio risultante di Homarr identifichi il confine pertinente invece di avviare l'eliminazione dei dati o un riavvio continuo. Ripristina la condizione valida e conferma che la stessa transazione di esempio vada a buon fine. Mantieni questa breve esercitazione nella checklist di release.

Avvia la prima istanza con una configurazione simile alla produzione

Il primo container deve essere facile da eliminare e ricreare. Mantieni i dati fuori dal writable layer, esponi la porta 7575 solo dove il proxy può raggiungerla e passa la configurazione a runtime.

docker run -d \
  --name homarr \
  --restart unless-stopped \
  -p 127.0.0.1:7575:7575 \
  -v homarr-data:/appdata \
  -e SECRET_ENCRYPTION_KEY=replace-with-a-long-random-value \
  ghcr.io/homarr-labs/homarr:latest

Fissa il riferimento dell'immagine dopo il test iniziale. Leggi il primo errore di avvio invece del messaggio finale di riavvio, verifica ogni mount con docker inspect e segui i log mentre crei una board, aggiungi una tile di servizio, configuri un'integrazione con credenziali e verifichi lo stato live e la ricerca dopo un riavvio. Questa sequenza distingue un comando errato per l'immagine da un problema di dipendenze o permessi.

I volumi sono solo il primo livello di ripristino

Per Homarr, la sicurezza del redeploy inizia da board, utenti, integrazioni, segreti e asset personalizzati. Monta /appdata prima del bootstrap, scrivi dati di esempio innocui e sostituisci il container per dimostrare che quel percorso è effettivamente persistente. Verifica il percorso sostituendo il container mentre i dati di esempio innocui sono presenti; in questo modo puoi individuare mount puntati a una directory troppo in alto o troppo in basso.

Poi testa il disaster recovery su un host vuoto. Se necessario, usa un export del database coerente a livello applicativo e verifica che board, utenti, integrazioni e asset personalizzati vengano recuperati e che i widget con credenziali si riconnettano. La guida ai backup del database verificati con un ripristino offre un obiettivo più solido del semplice controllo dell'esistenza di un file di archivio.

Impedisci che il successo del proxy mascheri un problema applicativo

Browser, client API e Homarr devono concordare su un'unica origin. Per ottenere questo risultato, configura l'hostname HTTPS esterno e le origin consentite. Mantieni host e protocollo originali, lasciando la porta 7575 non disponibile come indirizzo pubblico alternativo.

La guida alla risoluzione dei problemi quando il sito è irraggiungibile aiuta a distinguere una route non raggiungibile da un'applicazione che risponde. Questa distinzione è importante: i widget non riescono a raggiungere i servizi perché utilizzano indirizzi locali dell'host. Solo il primo problema si risolve modificando l'ingress; il secondo richiede l'analisi dei log, dello stato o del workload di Homarr.

Chiudi gli accessi temporanei di configurazione

Un deployment Homarr sicuro inizia dalla rimozione dei privilegi. Evita di modificare la chiave di crittografia dopo aver memorizzato i segreti delle integrazioni; mantieni invece stabile SECRET_ENCRYPTION_KEY, proteggi la modifica delle board e limita le credenziali di ogni widget all'ambito necessario.

Genera SECRET_ENCRYPTION_KEY una sola volta, non inserirla in Git e conservarla nel manifest di ripristino, perché modificarla può invalidare lo stato applicativo crittografato o firmato. Limita le route amministrative, usa DNS privato per le dipendenze e verifica ogni bind mount. Quando i log vengono inviati a un sistema centralizzato, filtra segreti e contenuti privati prima che lascino il server.

Sposta in Dockup il lavoro infrastrutturale ripetibile

Per Homarr, Dockup è più utile al confine tra un'immagine e un servizio durevole. Mantiene associati al servizio la route verso la porta 7575, TLS, i valori dei segreti e lo storage durante le sostituzioni dei container, indipendentemente dal fatto che il compute appartenga a Dockup o al tuo server collegato.

Concludi con le attività specifiche dell'applicazione: configura l'hostname HTTPS esterno e le origin consentite; conferma il requisito del runtime locale — dati applicativi persistenti e credenziali per le integrazioni live — ed esegui questa verifica: crea una board, aggiungi una tile di servizio, configura un'integrazione con credenziali e conferma lo stato live e la ricerca dopo un riavvio. Conserva il risultato come controllo di deployment, in modo che il prossimo aggiornamento dell'immagine venga valutato in base al comportamento e non allo stato del container.

Domande frequenti

Di cosa ha bisogno Homarr per un deployment in produzione?

Instrada il container Homarr sulla porta 7575 attraverso un'unica origin HTTPS. Il requisito del runtime locale consiste in dati applicativi persistenti e credenziali per le integrazioni live. Non considerare Homarr pronto finché non puoi creare una board, aggiungere una tile di servizio, configurare un'integrazione con credenziali e confermare lo stato live e la ricerca dopo un riavvio.

Quali dati di Homarr devono essere inclusi in un backup?

Rendi persistente /appdata e includi board, utenti, integrazioni, segreti e asset personalizzati nello stesso manifest di ripristino. Un ripristino pulito di Homarr è riuscito solo quando board, utenti, integrazioni e asset personalizzati vengono recuperati e i widget con credenziali si riconnettono.

Homarr richiede HTTPS dietro un reverse proxy?

Usa HTTPS per l'origin pubblica di Homarr e mantieni la porta 7575 nella route interna. Applica correttamente l'impostazione di Homarr: configura l'hostname HTTPS esterno e le origin consentite. Per Homarr, HTTPS protegge le credenziali o i contenuti degli utenti durante il transito e mantiene coerente il comportamento del client sensibile all'origin.

Come si deve testare un aggiornamento di Homarr?

Ripristina lo stato attuale di Homarr in un deployment isolato, applica la versione candidata e ripeti la relativa transazione di accettazione. Presta particolare attenzione perché le migrazioni dello schema di Homarr e la continuità della chiave di crittografia possono influire sulle credenziali delle integrazioni memorizzate. Conserva la versione precedente dell'immagine di Homarr finché non avrai compreso i limiti della migrazione dei dati e del rollback.