2026'da Fathom Lite Nasıl Self-Host Edilir: Tracking Script, SQLite ve Gizlilik

“Fathom Lite çalıştırmanın” iki farklı versiyonu vardır: Bir container'ın mevcut olması veya servisin gerçek görevini tamamlaması. Önemli olan yalnızca ikincisidir. Buradaki kanıt; bir site eklemek, tracking script'i bir test sayfasında çalıştırmak, ziyaretler oluşturmak ve dashboard'un bunları cookie kullanmadan kaydettiğini doğrulamaktır.

Fathom Lite tam olarak şu amaca hizmet eder: cookie kullanmayan, self-hosted page-view analytics. Deployment, bu davranışın arkasındaki parçaları korumalıdır; bir port, bir volume ve bir certificate girdidir, sonuç değildir.

Credentials, roller ve dışa açık yüzeyler

Fathom Lite için değerli yüzey mutlaka landing page değildir. En büyük hata, örnek bir secret'ı yeniden kullanmak veya admin login'ini TLS olmadan dışa açmaktır. Buna bilinçli şekilde karşı koyun: analytics login'ini koruyun, application secret'ı sabit tutun ve script'i yalnızca beklenen HTTPS host üzerinden yayınlayın.

FATHOM_SECRET değerini Fathom Lite içindeki rolüne uygun şekilde yönetin: hassas değerleri Git dışında tutun, rotation etkilerini belgeleyin ve production'da hiçbir zaman herkese açık bir örneği kullanmayın. Image destekliyorsa unprivileged bir container user kullanın ve ilgisiz hiçbir credential'ı mount etmeyin. Güvenilmeyen işlerin page-view write rate, database indexes, retention ve ziyaretçi browser'larından gelen network path üzerinde tüketim oluşturabileceği ingress katmanında rate veya size limitleri uygulayın.

Fathom Lite'ı dependency'lerinden ayırın

Sorumlu bir Fathom Lite topology'sinin en küçük hali; 8080 üzerinde tek bir private listener, bir ingress route ve belgelenmiş bir state boundary içerir. Fathom Lite için network contract, SQLite veya desteklenen bir external database ve doğru client-site script placement'tır. Private endpoint'leri internal DNS üzerinde tutun, yalnızca gerekli outbound çağrılara izin verin ve Fathom Lite'a kapsamı sınırlı bir service credential verin.

Topology'yi doğrulamak için temiz bir client'tan site eklemesini, tracking script'i bir test sayfasında çalıştırmasını, ziyaretler oluşturmasını ve dashboard'un bunları cookie kullanmadan kaydettiğini doğrulamasını isteyin. Çalışırken page-view write rate'i, database indexes'i, retention'ı ve ziyaretçi browser'larından gelen network path'i izleyin. Sonuç, bir sonraki iyileştirmenin rastgele container boyutlandırmasını teşvik etmek yerine memory, storage, networking veya ayrı bir worker katmanında yapılıp yapılmayacağını gösterir.

Fathom Lite için bir Docker baseline'ı

Minimal bir komut, platformun ileride neyi yöneteceğini ortaya çıkardığında faydalıdır.

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

Burada 8080 host üzerinde private kalır ve gerekli her path açıkça belirtilir. SQLite veya desteklenen bir external database için gözden geçirilmiş connection settings'i ve doğru client-site script placement'ı ekleyin; private servisler için private isimler kullanın. Startup'ı hem log'larla hem de application-specific kanıtla doğrulayın: bir site ekleyin, tracking script'i bir test sayfasında çalıştırın, ziyaretler oluşturun ve dashboard'un bunları cookie kullanmadan kaydettiğini doğrulayın. Doğrulamanın ardından image version'ını sabitleyin; böylece rutin bir replacement davranışı sessizce değiştirmez.

Fathom Lite deployment'ını uçtan uca kanıtlayın

Küçük ve disposable bir Fathom Lite fixture'ı oluşturun ve bunu her release için saklayın. Fixture gerçek workflow'u çalıştırmalıdır: bir site ekleyin, tracking script'i bir test sayfasında çalıştırın, ziyaretler oluşturun ve dashboard'un bunları cookie kullanmadan kaydettiğini doğrulayın. Image digest'ini, external hostname'i, dependency address'i ve beklenen sonucu kaydedin; böylece daha sonraki bir operator bu rehberi yorumlamak zorunda kalmadan testi tekrarlayabilir.

Fixture'ı üç kez çalıştırın. İlkinde fresh deployment'ı kullanın. İkincisinde durable state'e dokunmadan container'ı replace edin. Üçüncüsünde backup'ı boş bir environment'a restore edin. Üçüncü çalışma yalnızca siteler, user'lar ve geçmiş page view'lar geri geldiğinde ve recovery sonrasında yeni bir test ziyareti göründüğünde başarılıdır. Her çalışma sırasında page-view write rate, database indexes, retention ve ziyaretçi browser'larından gelen network path etrafındaki latency ve resource kullanımını kaydedin; bu, rastgele bir CPU yüzdesi yerine alert'ler için baseline oluşturur.

Son olarak negative path'i bilinçli şekilde test edin: test identity'nin SQLite'a veya desteklenen bir external database'e ve doğru client-site script placement'a erişimini geçici olarak engelleyin. Fathom Lite'ın state'i bozmadan görünür biçimde başarısız olduğunu doğrulayın, doğru koşulu geri yükleyin ve başarılı transaction'ı tekrarlayın. Bu dört sonucu içeren bir release record, dashboard screenshot'larından veya tek seferlik bir curl yanıtından daha güçlü kanıttır.

Internal ve external URL'leri doğru ayırın

Fathom Lite için public boundary; tek bir canonical hostname, automatic TLS ve 8080 üzerindeki tek bir internal target olmalıdır. Server address'i ve tracking script'in kullandığı public HTTPS endpoint'i, client'ların servisin tanıdığı bir adrese geri döneceği şekilde ayarlayın.

Acceptance transaction başarısız olursa ilk hatayı sınıflandırın. DNS, certificate ve 502 sorunları TLS validation checklist kapsamındadır. “Tracking script yanlış hostname'i gösteriyor veya database path ephemeral” durumu ise bir request Fathom Lite'a başarıyla ulaştıktan sonra application tarafına aittir.

Fathom Lite için failure drill'leri

Capacity test'leri / adresine tekrarlanan bir request göndermek yerine page-view write rate'i, database indexes'i, retention'ı ve ziyaretçi browser'larından gelen network path'i çalıştırmalıdır. “Bir site ekle, tracking script'i bir test sayfasında çalıştır, ziyaretler oluştur ve dashboard'un bunları cookie kullanmadan kaydettiğini doğrula” senaryosunu gerçekçi concurrency ile çalıştırın; latency'yi, error rate'i ve storage growth'u kaydedin.

Upgrade planlaması şu riski hesaba katmalıdır: Event'leri sessizce kaybetmemek için Fathom'un database schema'sı ve tracking script'i birlikte test edilmelidir. Yeni release'i temsili input ile test edin, ardından acceptance transaction'ı tekrarlayın ve sonucunu karşılaştırın. Tracking script yanlış hostname'i gösteriyorsa veya database path ephemeral ise başarısız transaction'ı kaydedin ve ingress'in sorumlu olduğunu varsaymak yerine dahil olan ilk boundary'yi inceleyin.

Fathom Lite'ın replacement sonrasında çalıştığını kanıtlayın

Bir container image yeniden indirilebilir; analytics database'i, site configuration'ı ve administrator state'i indirilemez. Bootstrap'tan önce /app'i mount edin, zararsız örnek veriler yazın ve path'in gerçekten persistent olduğunu kanıtlamak için container'ı replace edin. Bir Compose filename'ına güvenmek yerine effective mount'ı inceleyin ve runtime user'ın Fathom Lite'ın ihtiyaç duyduğu konuma yazabildiğini kontrol edin.

Retention ve off-host destination seçin, ardından production'a dokunmadan recovery provası yapın. Drill yalnızca siteler, user'lar ve geçmiş page view'lar geri geldiğinde ve recovery sonrasında yeni bir test ziyareti göründüğünde başarılıdır. Database-backed state için storage snapshot'larını, point-in-time recovery ve snapshot'lar karşılaştırması bölümünde açıklandığı gibi application-consistent export'larla birlikte kullanın.

Fathom Lite'ı Dockup lifecycle'ına bağlayın

Dockup'ın one-click Fathom Lite deployment'ı replacement işlemini güvenli hale getirmelidir: route 8080'i hedeflemeye devam eder, secret'lar image içine gömülmez ve persistent path'ler yeni container'da geri gelir. Aynı deployment Dockup compute üzerinde veya bağlı bir makinede çalışabilir.

SQLite veya desteklenen bir external database ile doğru client-site script placement'ı bağlayıp test ederek application-specific çalışmayı tamamlayın, canonical public address'i uygulayın ve şu acceptance check'i çalıştırın: bir site ekleyin, tracking script'i bir test sayfasında çalıştırın, ziyaretler oluşturun ve dashboard'un bunları cookie kullanmadan kaydettiğini doğrulayın. Gerçek user'lar gelmeden önce restore sonucunu runbook'a ekleyin.

Sık sorulan sorular

Production deployment için Fathom Lite'ın neye ihtiyacı vardır?

Fathom Lite container'ını tek bir HTTPS origin üzerinden 8080 portuna route edin. Supporting network requirement, SQLite veya desteklenen bir external database ve doğru client-site script placement'tır. Bir site ekleyene, tracking script'i bir test sayfasında çalıştırana, ziyaretler oluşturana ve dashboard'un bunları cookie kullanmadan kaydettiğini doğrulayana kadar Fathom Lite'ı hazır kabul etmeyin.

Hangi Fathom Lite verileri backup'a dahil edilmelidir?

/app'i persist edin ve analytics database'ini, site configuration'ını ve administrator state'ini aynı recovery manifest'ine dahil edin. Temiz bir Fathom Lite restore'u yalnızca siteler, user'lar ve geçmiş page view'lar geri geldiğinde ve recovery sonrasında yeni bir test ziyareti göründüğünde başarılıdır.

Reverse proxy arkasında Fathom Lite için HTTPS gerekir mi?

Public Fathom Lite origin için HTTPS kullanın ve 8080 portunu internal route üzerinde tutun. Fathom Lite ayarını doğru uygulayın: server address'i ve tracking script'in kullandığı public HTTPS endpoint'i ayarlayın. Fathom Lite için HTTPS, credentials veya user content'in transit sırasında korunmasını sağlar ve origin'e duyarlı client davranışını tutarlı kılar.

Bir Fathom Lite upgrade'i nasıl test edilmelidir?

Mevcut Fathom Lite state'ini izole bir deployment'a restore edin, candidate version'ı uygulayın ve acceptance transaction'ını tekrarlayın. Fathom'un database schema'sı ve tracking script'i event'leri sessizce kaybetmemek için birlikte test edilmesi gerektiğinden özellikle dikkatli olun. Data-migration ve rollback boundary'si anlaşılana kadar önceki Fathom Lite image'ını saklayın.