Så självhostar du Fathom Lite 2026: tracking-script, SQLite och integritet

Det finns två versioner av att ”köra Fathom Lite”: en container existerar, eller så utför tjänsten faktiskt sitt jobb. Det är bara det senare som spelar roll. Här är beviset att lägga till en webbplats, läsa in tracking-scriptet på en testsida, generera besök och bekräfta att instrumentpanelen registrerar dem utan cookies.

Fathom Lite är avsett för detta: cookie-fri, självhostad analys av sidvisningar. Driftsättningen måste bevara delarna bakom detta beteende; en port, en volym och ett certifikat är förutsättningar, inte resultatet.

Autentiseringsuppgifter, roller och exponerade ytor

För Fathom Lite är den värdefulla exponeringsytan inte nödvändigtvis landningssidan. Det vanligaste misstaget är att återanvända ett exempel på en secret eller exponera admininloggningen utan TLS. Motverka detta medvetet: skydda analysinloggningen, håll applikationens secret stabil och publicera bara scriptet från den förväntade HTTPS-värden.

Hantera FATHOM_SECRET utifrån dess roll i Fathom Lite: håll känsliga värden borta från Git, dokumentera effekterna av rotation och ersätt aldrig ett publikt exempel i produktion. Använd en containeranvändare utan privilegier när imagen stöder det och montera inga orelaterade autentiseringsuppgifter. Tillämpa rate- eller storleksbegränsningar vid ingress där opålitlig trafik kan förbruka skrivtakten för sidvisningar, databasindex, retention och nätverksvägen från besökarnas webbläsare.

Separera Fathom Lite från dess beroenden

Den minsta ansvarsfulla topologin för Fathom Lite innehåller en privat listener på 8080, en ingress-route och en dokumenterad gräns för persistent state. Nätverkskontraktet för Fathom Lite är SQLite eller en extern databas som stöds samt korrekt placering av scriptet på klientsidan. Behåll privata endpoints i intern DNS, tillåt endast nödvändiga utgående anrop och ge Fathom Lite en service credential med begränsad omfattning.

Validera topologin genom att be en ren klient att lägga till en webbplats, läsa in tracking-scriptet på en testsida, generera besök och bekräfta att instrumentpanelen registrerar dem utan cookies. Övervaka skrivtakten för sidvisningar, databasindex, retention och nätverksvägen från besökarnas webbläsare medan den körs. Resultatet visar om nästa förbättring hör hemma i minne, lagring, nätverk eller en separat worker, i stället för att uppmuntra till godtycklig dimensionering av containern.

En Docker-baseline för Fathom Lite

Ett minimalt kommando är användbart när det tydliggör vad plattformen senare kommer att hantera.

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

Här förblir port 8080 privat på värden och alla nödvändiga sökvägar är uttryckliga. Lägg till de granskade anslutningsinställningarna för SQLite eller en extern databas som stöds samt korrekt placering av scriptet på klientsidan; använd privata namn för privata tjänster. Verifiera uppstarten med både loggar och det applikationsspecifika beviset: lägg till en webbplats, läs in tracking-scriptet på en testsida, generera besök och bekräfta att instrumentpanelen registrerar dem utan cookies. När detta är verifierat låser du image-versionen så att ett rutinmässigt byte inte i tysthet ändrar beteendet.

Bevisa Fathom Lite-driftsättningen från början till slut

Skapa en liten, tillfällig testmiljö för Fathom Lite och behåll den för varje release. Testmiljön ska köra igenom det verkliga arbetsflödet: lägga till en webbplats, läsa in tracking-scriptet på en testsida, generera besök och bekräfta att instrumentpanelen registrerar dem utan cookies. Dokumentera image-digest, extern hostname, beroendeadress och förväntat resultat så att en senare operatör kan upprepa testet utan att behöva tolka den här guiden.

Kör testmiljön tre gånger. Använd först den nya driftsättningen. Byt sedan ut containern utan att röra persistent state. Återställ slutligen säkerhetskopian till en tom miljö. Den tredje körningen godkänns bara när webbplatser, användare och historiska sidvisningar återkommer och ett nytt testbesök syns efter återställningen. Samla under varje körning in latens och resursanvändning kring skrivtakten för sidvisningar, databasindex, retention och nätverksvägen från besökarnas webbläsare; detta blir baslinjen för larm i stället för en godtycklig CPU-procent.

Testa slutligen den negativa vägen medvetet: neka tillfälligt testidentiteten åtkomst till SQLite eller en extern databas som stöds samt korrekt placering av scriptet på klientsidan. Bekräfta att Fathom Lite misslyckas tydligt utan att korrupta state, återställ rätt förutsättning och upprepa den lyckade transaktionen. En releasepost som innehåller dessa fyra resultat är starkare bevis än skärmbilder av en instrumentpanel eller ett engångssvar från curl.

Håll interna och externa URL:er åtskilda

Den publika gränsen för Fathom Lite bör vara ett kanoniskt hostname, automatisk TLS och ett internt mål på 8080. Ange serveradressen och den publika HTTPS-endpoint som tracking-scriptet använder, så att klienterna återvänder till en adress som tjänsten känner igen.

Om acceptanstestet misslyckas ska du klassificera det första felet. DNS-, certifikat- och 502-problem hör hemma i checklistan för TLS-validering. Villkoret ”tracking-scriptet pekar på fel hostname eller databassökvägen är ephemeral” hör till applikationssidan efter att en request har nått Fathom Lite utan problem.

Felövningar för Fathom Lite

Kapacitetstester ska belasta skrivtakten för sidvisningar, databasindex, retention och nätverksvägen från besökarnas webbläsare – inte skicka upprepade requests till /. Kör scenariot ”lägg till en webbplats, läs in tracking-scriptet på en testsida, generera besök och bekräfta att instrumentpanelen registrerar dem utan cookies” med realistisk samtidighet och dokumentera latens, felprocent och lagringstillväxt.

Planeringen inför uppgraderingar måste ta hänsyn till den här risken: Fathoms databasschema och tracking-script bör testas tillsammans för att undvika att händelser försvinner i tysthet. Testa den nya releasen med representativ input, kör sedan acceptanstestet igen och jämför resultatet. Om tracking-scriptet pekar på fel hostname eller databassökvägen är ephemeral ska du dokumentera den misslyckade transaktionen och undersöka den första berörda gränsen i stället för att anta att ingressen är orsaken.

Bevisa att Fathom Lite överlever ett byte

En container-image kan laddas ned igen; analysdatabasen, webbplatskonfigurationen och administratörstillståndet kan inte det. Montera /app före bootstrap, skriv ofarliga exempeldata och byt ut containern för att bevisa att sökvägen faktiskt är persistent. Kontrollera den effektiva mounten i stället för att lita på ett Compose-filnamn, och verifiera att runtime-användaren kan skriva där Fathom Lite förväntar sig det.

Välj retention och en destination utanför värden, och öva sedan på återställning utan att röra produktionen. Övningen är godkänd först när webbplatser, användare och historiska sidvisningar återkommer och ett nytt testbesök syns efter återställningen. För databaserat state ska du kombinera lagringssnapshots med applikationskonsistenta exporter enligt beskrivningen i point-in-time recovery jämfört med snapshots.

Koppla Fathom Lite till Dockups livscykel

Dockups one-click-driftsättning av Fathom Lite bör göra byten säkra: routen fortsätter att peka på 8080, secrets byggs inte in i imagen och persistenta sökvägar återkommer i den nya containern. Samma driftsättning kan köras på Dockup compute eller på en ansluten maskin.

Slutför det applikationsspecifika arbetet genom att ansluta och testa SQLite eller en extern databas som stöds samt korrekt placering av scriptet på klientsidan, ange den kanoniska publika adressen och köra denna kontroll: lägg till en webbplats, läs in tracking-scriptet på en testsida, generera besök och bekräfta att instrumentpanelen registrerar dem utan cookies. Lägg till resultatet från återställningen i runbooken innan riktiga användare börjar använda tjänsten.

Vanliga frågor

Vad behöver Fathom Lite för en produktionsdriftsättning?

Routa Fathom Lite-containern på port 8080 via en HTTPS-origin. Det kompletterande nätverkskravet är SQLite eller en extern databas som stöds samt korrekt placering av scriptet på klientsidan. Förklara inte Fathom Lite redo förrän du kan lägga till en webbplats, läsa in tracking-scriptet på en testsida, generera besök och bekräfta att instrumentpanelen registrerar dem utan cookies.

Vilka Fathom Lite-data ska ingå i en säkerhetskopia?

Gör /app persistent och inkludera analysdatabasen, webbplatskonfigurationen och administratörstillståndet i samma återställningsmanifest. En ren återställning av Fathom Lite är godkänd först när webbplatser, användare och historiska sidvisningar återkommer och ett nytt testbesök syns efter återställningen.

Kräver Fathom Lite HTTPS bakom en reverse proxy?

Använd HTTPS för den publika Fathom Lite-originen och behåll port 8080 på den interna routen. Tillämpa Fathom Lite-inställningen korrekt: ange serveradressen och den publika HTTPS-endpoint som tracking-scriptet använder. För Fathom Lite skyddar HTTPS autentiseringsuppgifter eller användarinnehåll under överföring och gör origin-känsligt klientbeteende konsekvent.

Hur bör en uppgradering av Fathom Lite testas?

Återställ aktuell Fathom Lite-state till en isolerad driftsättning, tillämpa kandidatversionen och kör acceptanstestet igen. Var särskilt uppmärksam eftersom Fathoms databasschema och tracking-script bör testas tillsammans för att undvika att händelser försvinner i tysthet. Behåll den tidigare Fathom Lite-imagen tills gränserna för datamigrering och rollback är förstådda.