Come fare il self-hosting di Fathom Lite nel 2026: script di tracking, SQLite e privacy

Esistono due versioni del “far girare Fathom Lite”: esiste un container oppure il servizio svolge effettivamente il suo compito. Solo la seconda conta. In questo caso, la prova consiste nell'aggiungere un sito, caricare lo script di tracking su una pagina di test, generare visite e verificare che la dashboard le registri senza cookie.

Fathom Lite serve proprio a questo: analytics delle visualizzazioni di pagina senza cookie e in self-hosting. Il deployment deve preservare gli elementi alla base di questo comportamento; una porta, un volume e un certificato sono input, non il risultato.

Credenziali, ruoli e superfici esposte

Per Fathom Lite, la superficie più importante non è necessariamente la landing page. L'errore principale consiste nel riutilizzare un secret di esempio o nell'esporre il login amministrativo senza TLS. Contrastalo intenzionalmente: proteggi il login degli analytics, mantieni stabile il secret dell'applicazione e pubblica lo script solo dall'host HTTPS previsto.

Tratta FATHOM_SECRET in base al suo ruolo in Fathom Lite: mantieni i valori sensibili fuori da Git, documenta gli effetti della rotazione e non sostituire mai un esempio pubblico in produzione. Usa un utente non privilegiato per il container quando l'immagine lo supporta e non montare credenziali non correlate. Applica limiti di rate o di dimensione all'ingress, dove il lavoro non attendibile può consumare il rate di scrittura delle visualizzazioni di pagina, gli indici del database, la retention e il percorso di rete dai browser dei visitatori.

Separa Fathom Lite dalle sue dipendenze

La topologia minima responsabile di Fathom Lite comprende un unico listener privato sulla porta 8080, una route di ingress e un confine di stato documentato. Il contratto di rete per Fathom Lite è SQLite o un database esterno supportato e il corretto posizionamento dello script lato client del sito. Mantieni gli endpoint privati su DNS interno, consenti solo le chiamate outbound necessarie e assegna a Fathom Lite una credenziale di servizio con scope limitato.

Valida la topologia chiedendo a un client pulito di aggiungere un sito, caricare lo script di tracking su una pagina di test, generare visite e verificare che la dashboard le registri senza cookie. Durante l'esecuzione, osserva il rate di scrittura delle visualizzazioni di pagina, gli indici del database, la retention e il percorso di rete dai browser dei visitatori. Il risultato indica se il prossimo miglioramento riguarda memoria, storage, networking o un worker separato, invece di incoraggiare un dimensionamento arbitrario del container.

Una configurazione Docker di base per Fathom Lite

Un comando minimale è utile quando mostra ciò che la piattaforma gestirà in seguito.

docker run -d \
  --name fathom-lite \
  --restart unless-stopped \
  -p 127.0.0.1:8080:8080 \
  -v fathom-lite-data:/app \
  -e FATHOM_SECRET=replace-with-a-long-random-value \
  -e FATHOM_SERVER_ADDR=:8080 \
  -e FATHOM_DATABASE_DRIVER=sqlite3 \
  -e FATHOM_DATABASE_NAME=/app/fathom.db \
  usefathom/fathom:latest

Qui la porta 8080 resta privata sull'host e ogni percorso necessario è esplicito. Aggiungi le impostazioni di connessione verificate per SQLite o per un database esterno supportato e il corretto posizionamento dello script lato client del sito; usa nomi privati per i servizi privati. Verifica l'avvio sia con i log sia con la prova specifica dell'applicazione: aggiungi un sito, carica lo script di tracking su una pagina di test, genera visite e conferma che la dashboard le registri senza cookie. Dopo la verifica, blocca la versione dell'immagine affinché una sostituzione ordinaria non modifichi silenziosamente il comportamento.

Dimostra il funzionamento end-to-end del deployment di Fathom Lite

Crea un fixture Fathom Lite piccolo e temporaneo e conservalo per ogni release. Il fixture deve eseguire il workflow reale: aggiungere un sito, caricare lo script di tracking su una pagina di test, generare visite e verificare che la dashboard le registri senza cookie. Registra il digest dell'immagine, l'hostname esterno, l'indirizzo della dipendenza e il risultato atteso, così un operatore potrà ripetere il test in seguito senza dover interpretare questa guida.

Esegui il fixture tre volte. Per prima cosa, usa il deployment appena creato. In secondo luogo, sostituisci il container senza modificare lo stato durevole. Infine, ripristina il backup in un ambiente vuoto. La terza esecuzione ha esito positivo solo quando siti, utenti e visualizzazioni di pagina storiche tornano disponibili e una nuova visita di test compare dopo il recovery. Durante ogni esecuzione, raccogli latenza e utilizzo delle risorse relativi al rate di scrittura delle visualizzazioni di pagina, agli indici del database, alla retention e al percorso di rete dai browser dei visitatori; questo diventa la baseline per gli alert, anziché una percentuale arbitraria della CPU.

Infine, testa intenzionalmente il percorso negativo: nega temporaneamente all'identità di test l'accesso a SQLite o a un database esterno supportato e al corretto posizionamento dello script lato client del sito. Conferma che Fathom Lite fallisca in modo visibile senza corrompere lo stato, ripristina la condizione corretta e ripeti la transazione con esito positivo. Un record della release contenente questi quattro risultati è una prova più solida degli screenshot di una dashboard o di una risposta curl eseguita una sola volta.

Mantieni distinti gli URL interni ed esterni

Il confine pubblico di Fathom Lite dovrebbe essere costituito da un unico hostname canonico, TLS automatico e un unico target interno sulla porta 8080. Imposta l'indirizzo del server e l'endpoint HTTPS pubblico utilizzato dallo script di tracking, così i client torneranno a un indirizzo riconosciuto dal servizio.

Se la transazione di accettazione fallisce, classifica il primo errore. I problemi di DNS, certificato e 502 appartengono alla checklist di convalida TLS. La condizione “lo script di tracking punta all'hostname sbagliato oppure il percorso del database è effimero” appartiene al lato applicativo, dopo che una richiesta ha raggiunto correttamente Fathom Lite.

Esegui failure drill per Fathom Lite

I test di capacità devono esercitare il rate di scrittura delle visualizzazioni di pagina, gli indici del database, la retention e il percorso di rete dai browser dei visitatori, non una richiesta ripetuta a /. Esegui lo scenario “aggiungere un sito, caricare lo script di tracking su una pagina di test, generare visite e verificare che la dashboard le registri senza cookie” con una concorrenza realistica e registra latenza, tasso di errore e crescita dello storage.

La pianificazione degli upgrade deve tenere conto di questo rischio: lo schema del database di Fathom e lo script di tracking devono essere testati insieme per evitare di perdere silenziosamente gli eventi. Testa la nuova release con input rappresentativi, poi ripeti la transazione di accettazione e confrontane il risultato. Se lo script di tracking punta all'hostname sbagliato oppure il percorso del database è effimero, acquisisci la transazione fallita e analizza il primo confine coinvolto invece di presumere che la responsabilità sia dell'ingress.

Dimostra che Fathom Lite sopravvive a una sostituzione

Un'immagine del container può essere scaricata di nuovo; il database degli analytics, la configurazione dei siti e lo stato dell'amministratore no. Monta /app prima del bootstrap, scrivi dati di esempio innocui e sostituisci il container per dimostrare che quel percorso è realmente persistente. Ispeziona il mount effettivo invece di fidarti del nome di un file Compose e verifica che l'utente runtime possa scrivere nel percorso previsto da Fathom Lite.

Scegli una retention e una destinazione off-host, poi fai una prova di recovery senza toccare la produzione. Il test ha esito positivo solo quando siti, utenti e visualizzazioni di pagina storiche tornano disponibili e una nuova visita di test compare dopo il recovery. Per lo stato basato su database, abbina snapshot dello storage a export coerenti con l'applicazione, come descritto in recovery point-in-time rispetto agli snapshot.

Collega Fathom Lite al ciclo di vita di Dockup

Il deployment one-click di Fathom Lite su Dockup dovrebbe rendere sicura la sostituzione: la route continua a puntare alla porta 8080, i secret non sono incorporati nell'immagine e i percorsi persistenti tornano disponibili nel nuovo container. Lo stesso deployment può essere eseguito sul compute di Dockup o su una macchina collegata.

Completa il lavoro specifico dell'app collegando e testando SQLite o un database esterno supportato e il corretto posizionamento dello script lato client del sito, applicando l'indirizzo pubblico canonico ed eseguendo questo controllo di accettazione: aggiungi un sito, carica lo script di tracking su una pagina di test, genera visite e conferma che la dashboard le registri senza cookie. Aggiungi il risultato del restore al runbook prima dell'arrivo degli utenti reali.

Domande frequenti

Di cosa ha bisogno Fathom Lite per un deployment in produzione?

Instrada il container Fathom Lite sulla porta 8080 attraverso un'unica origine HTTPS. Il requisito di rete di supporto è SQLite o un database esterno supportato e il corretto posizionamento dello script lato client del sito. Non considerare Fathom Lite pronto finché non puoi aggiungere un sito, caricare lo script di tracking su una pagina di test, generare visite e confermare che la dashboard le registri senza cookie.

Quali dati di Fathom Lite devono essere inclusi in un backup?

Rendi persistente /app e includi il database degli analytics, la configurazione dei siti e lo stato dell'amministratore nello stesso manifest di recovery. Un restore pulito di Fathom Lite ha esito positivo solo quando siti, utenti e visualizzazioni di pagina storiche tornano disponibili e una nuova visita di test compare dopo il recovery.

Fathom Lite richiede HTTPS dietro un reverse proxy?

Usa HTTPS per l'origine pubblica di Fathom Lite e mantieni la porta 8080 sulla route interna. Applica correttamente l'impostazione di Fathom Lite: configura l'indirizzo del server e l'endpoint HTTPS pubblico utilizzato dallo script di tracking. Per Fathom Lite, HTTPS protegge le credenziali o i contenuti degli utenti durante il transito e mantiene coerente il comportamento dei client sensibile all'origine.

Come si deve testare un upgrade di Fathom Lite?

Ripristina lo stato attuale di Fathom Lite in un deployment isolato, applica la versione candidata e ripeti la relativa transazione di accettazione. Presta particolare attenzione perché lo schema del database di Fathom e lo script di tracking devono essere testati insieme per evitare di perdere silenziosamente gli eventi. Conserva la precedente immagine di Fathom Lite finché non avrai compreso i confini della migrazione dei dati e del rollback.