Come eseguire il self-hosting di Homepage nel 2026: host consentiti, widget e configurazione

Esistono due versioni del “funzionamento di Homepage”: esiste un container oppure il servizio svolge effettivamente il proprio lavoro. Solo la seconda è importante. In questo caso, la verifica consiste nel caricare servizi e bookmark, chiamare diversi widget live, testare la ricerca e riavviare il servizio dopo aver modificato un file di configurazione YAML.

Homepage serve a questo scopo: è una start page con widget live per i servizi self-hosted. Il deployment deve preservare gli elementi alla base di questo comportamento; una porta, un volume e un certificato sono input, non il risultato.

Scegliere la topologia minima funzionante per Homepage

Un diagramma utile di Homepage mostra il percorso pubblico, la porta privata 3000, il confine dei dati persistenti e ogni requisito di supporto. Indica quali frecce trasportano credenziali e quali rappresentano il normale traffico utente. Il requisito esterno di Homepage è una configurazione in sola lettura più le credenziali per i widget opzionali dei servizi. Testa DNS in uscita, TLS e il comportamento dei provider senza pubblicare un altro servizio in ingresso.

Dimostra il diagramma con un'azione reale: carica servizi e bookmark, chiama diversi widget live, testa la ricerca e riavvia il servizio dopo aver modificato un file di configurazione YAML. I principali punti di pressione sono probabilmente il fan-out dei widget, le API downstream lente, la risoluzione DNS e la frequenza di refresh della dashboard nel browser; monitora questo percorso invece di trattare tutte le richieste HTTP allo stesso modo.

Aggiornare Homepage senza procedere alla cieca

La prima metrica operativa utile per Homepage indica se è in grado di caricare servizi e bookmark, chiamare diversi widget live, testare la ricerca e riavviarsi dopo la modifica di un file di configurazione YAML. Affiancala ai segnali di saturazione relativi al fan-out dei widget, alle API downstream lente, alla risoluzione DNS e alla frequenza di refresh della dashboard nel browser. Un probe che verifica solo il processo non dovrebbe chiamare dipendenze costose né riavviare il container perché un upstream è temporaneamente indisponibile.

Considera gli aggiornamenti come modifiche ai dati, perché le chiavi di configurazione e le integrazioni dei widget possono cambiare; valida quindi YAML e comportamento dei provider prima di aggiornare l'immagine. Fissa le versioni, prova la procedura su uno stato ripristinato e conserva l'immagine precedente finché il rollback non rimane valido. Quando l'host viene rifiutato o l'indentazione YAML impedisce il caricamento della configurazione, conserva i log precedenti al riavvio: di solito contengono il messaggio causale.

Una procedura di accettazione in produzione per Homepage

Prima dell'arrivo degli utenti reali, prepara una checklist di release per Homepage. Deve indicare l'immagine fissata, la porta 3000, l'origine canonica, i percorsi persistenti e il responsabile della configurazione in sola lettura più le credenziali per i widget opzionali dei servizi. Allega il risultato atteso di questa transazione: caricare servizi e bookmark, chiamare diversi widget live, testare la ricerca e riavviare il servizio dopo aver modificato un file di configurazione YAML.

Usa la checklist dopo una sostituzione normale e dopo un ripristino pulito. Il ripristino è accettato solo se servizi, bookmark, widget e asset personalizzati tornano disponibili e tutti i widget critici gestiscono in modo visibile i guasti downstream. Raccogli anche una breve traccia delle risorse che copra il fan-out dei widget, le API downstream lente, la risoluzione DNS e la frequenza di refresh della dashboard nel browser; conservala insieme alla release, così i futuri cambiamenti di capacità potranno essere confrontati usando lo stesso carico di lavoro.

Includi un errore controllato: nega temporaneamente il percorso di test usato dalla configurazione in sola lettura più le credenziali per i widget opzionali dei servizi. Verifica che Homepage segnali il problema al confine corretto, ripristina la condizione valida ed esegui nuovamente la transazione. In questo modo verifichi la visibilità degli errori, non solo il successo, evitando che un'interfaccia apparentemente funzionante nasconda un worker, un callback o una connessione al database guasti.

Rendere riproducibile l'avvio di Homepage

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

docker run -d \
  --name homepage \
  --restart unless-stopped \
  -p 127.0.0.1:3000:3000 \
  -v homepage-data:/app/config \
  -e HOMEPAGE_ALLOWED_HOSTS=home.example.com \
  ghcr.io/gethomepage/homepage:latest

Consenti e verifica il percorso in uscita o lato client richiesto dalla configurazione in sola lettura più le credenziali per i widget opzionali dei servizi. Controlla l'utente del container, i percorsi scrivibili e il listener associato prima di esporlo. Esegui l'azione completa — caricare servizi e bookmark, chiamare diversi widget live, testare la ricerca e riavviare il servizio dopo aver modificato un file di configurazione YAML — e salva l'identificativo esatto dell'immagine che ha prodotto il risultato.

Separare i container sostituibili dai dati persistenti

Il set necessario per il ripristino comprende i file di configurazione, i bookmark, i servizi e gli asset personalizzati. Monta /app/config prima del bootstrap, scrivi dati di esempio innocui e sostituisci il container per dimostrare che il percorso è effettivamente persistente. Un volume protegge i dati dalla sostituzione del container, ma non dalla perdita dell'host, dalla cancellazione accidentale o dalla corruzione a livello applicativo.

Esegui backup che comprendano la sorgente dei dati: quando necessario, usa dump logici per i database live e copia i file solo da uno stato coerente. Conserva una copia cifrata lontano dall'host di Homepage. Il criterio di accettazione per un ripristino è specifico: servizi, bookmark, widget e asset personalizzati devono tornare disponibili e tutti i widget critici devono gestire in modo visibile i guasti downstream. La guida ai backup verificati tramite ripristino spiega perché il solo successo del job non è sufficiente.

Domini, header del proxy e porta 3000

Browser, client API e Homepage devono concordare su un'unica origine. Per ottenerlo, imposta gli host consentiti per il dominio esatto e per l'hostname del proxy. Mantieni l'host e il protocollo originali, lasciando la porta 3000 non disponibile come indirizzo pubblico alternativo.

La guida alla risoluzione dei problemi quando il sito è irraggiungibile aiuta a distinguere un percorso irraggiungibile da un'applicazione che risponde. Qui la distinzione è importante: l'host viene rifiutato oppure l'indentazione YAML impedisce il caricamento della configurazione. Solo il primo problema si risolve modificando l'ingress; il secondo richiede un'ispezione dei log, dello stato o del carico di lavoro di Homepage.

Decisioni di sicurezza specifiche per Homepage

Non ereditare le assunzioni di sicurezza di un tutorial locale. Il problema specifico di Homepage è il commit delle API key dei widget in un repository pubblico. In produzione, imposta quindi gli host consentiti in modo preciso e conserva le API key dei widget in variabili d'ambiente o in una configurazione supportata da secret, non in un repository pubblico.

HOMEPAGE_ALLOWED_HOSTS controlla il comportamento, non la riservatezza; valida il tipo e il valore e conserva separatamente le credenziali effettive di Homepage. Limita l'accesso al filesystem e alla rete, proteggi gli endpoint di setup e definisci limiti per upload, richieste o esecuzione intorno al fan-out dei widget, alle API downstream lente, alla risoluzione DNS e alla frequenza di refresh della dashboard nel browser.

In che modo Dockup riduce il lavoro necessario per Homepage

Per Homepage, Dockup è particolarmente utile al confine tra un'immagine e un servizio persistente. Mantiene associati il percorso verso la porta 3000, TLS, i valori dei secret e lo storage durante le sostituzioni dei container, indipendentemente dal fatto che il compute appartenga a Dockup o al server collegato.

Concludi con la conoscenza dell'applicazione: imposta gli host consentiti per il dominio esatto e per l'hostname del proxy; consenti e verifica la configurazione in sola lettura più le credenziali per i widget opzionali dei servizi; quindi esegui questa verifica: carica servizi e bookmark, chiama diversi widget live, testa la ricerca e riavvia il servizio dopo aver modificato un file di configurazione YAML. Conserva il risultato come controllo del deployment, così il prossimo aggiornamento dell'immagine verrà valutato in base al comportamento e non allo stato del container.

Domande frequenti

Di cosa ha bisogno Homepage per un deployment in produzione?

Instrada il container di Homepage sulla porta 3000 attraverso un'unica origine HTTPS. Il requisito esterno per la delivery è una configurazione in sola lettura più le credenziali per i widget opzionali dei servizi. Non considerare Homepage pronto finché non puoi caricare servizi e bookmark, chiamare diversi widget live, testare la ricerca e riavviare il servizio dopo aver modificato un file di configurazione YAML.

Quali dati di Homepage devono essere inclusi in un backup?

Rendi persistente /app/config e includi file di configurazione, bookmark, servizi e asset personalizzati nello stesso manifest di ripristino. Un ripristino pulito di Homepage è riuscito solo quando servizi, bookmark, widget e asset personalizzati tornano disponibili e tutti i widget critici gestiscono in modo visibile i guasti downstream.

Homepage richiede HTTPS dietro un reverse proxy?

Usa HTTPS per l'origine pubblica di Homepage e mantieni la porta 3000 nel percorso interno. Applica correttamente l'impostazione di Homepage: configura gli host consentiti per il dominio esatto e per l'hostname del proxy. Per Homepage, HTTPS protegge le credenziali o i contenuti dell'utente durante il transito e mantiene coerente il comportamento del client sensibile all'origine.

Come va testato un aggiornamento di Homepage?

Ripristina lo stato corrente di Homepage in un deployment isolato, applica la versione candidata e ripeti la relativa transazione di accettazione. Presta particolare attenzione al fatto che le chiavi di configurazione e le integrazioni dei widget possono cambiare; valida quindi YAML e comportamento dei provider prima di aggiornare l'immagine. Conserva l'immagine precedente di Homepage finché non avrai compreso i confini della migrazione dei dati e del rollback.