How to Self-Host Fathom Lite in 2026: Tracking Script, SQLite and Privacy

There are two versions of “running Fathom Lite”: a container exists, or the service completes its real job. Only the second matters. Here the proof is to add a site, load the tracking script on a test page, generate visits and confirm the dashboard records them without cookies.

Fathom Lite serves this purpose: cookie-free, self-hosted page-view analytics. The deployment has to preserve the pieces behind that behavior; a port, a volume and a certificate are inputs, not the result.

Credentials, roles and exposed surfaces

For Fathom Lite, the valuable surface is not necessarily the landing page. The main mistake is reusing an example secret or exposing the admin login without TLS. Counter it deliberately: protect the analytics login, keep the application secret stable and publish the script only from the expected HTTPS host.

Treat FATHOM_SECRET according to its Fathom Lite role: keep sensitive values out of Git, document rotation effects and never substitute a public example in production. Use an unprivileged container user when the image supports it and mount no unrelated credentials. Apply rate or size limits at ingress where untrusted work can consume page-view write rate, database indexes, retention and the network path from visitor browsers.

Separate Fathom Lite from its dependencies

The smallest responsible Fathom Lite topology contains one private listener on 8080, an ingress route and a documented state boundary. The network contract for Fathom Lite is SQLite or a supported external database and correct client-site script placement. Keep private endpoints on internal DNS, permit only required outbound calls and give Fathom Lite a scoped service credential.

Validate the topology by asking a clean client to add a site, load the tracking script on a test page, generate visits and confirm the dashboard records them without cookies. Watch page-view write rate, database indexes, retention and the network path from visitor browsers while it runs. The result tells you whether the next improvement belongs in memory, storage, networking or a separate worker instead of encouraging arbitrary container sizing.

A Docker baseline for Fathom Lite

A minimal command is useful when it reveals what the platform will later manage.

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

Here port 8080 remains host-private and every required path is explicit. Add the reviewed connection settings for SQLite or a supported external database and correct client-site script placement; use private names for private services. Verify startup with both logs and the application-specific proof: add a site, load the tracking script on a test page, generate visits and confirm the dashboard records them without cookies. Once verified, lock the image version so a routine replacement does not silently change behavior.

Prove the Fathom Lite deployment end to end

Create a small, disposable Fathom Lite fixture and keep it for every release. The fixture should exercise the real workflow: add a site, load the tracking script on a test page, generate visits and confirm the dashboard records them without cookies. Record the image digest, external hostname, dependency address and the expected result so a later operator can repeat the test without interpreting this guide.

Run the fixture three times. First, use the fresh deployment. Second, replace the container without touching durable state. Third, restore the backup into an empty environment. The third run passes only when sites, users and historical page views return and a new test visit appears after recovery. During each run, capture latency and resource use around page-view write rate, database indexes, retention and the network path from visitor browsers; this becomes the baseline for alerts rather than an arbitrary CPU percentage.

Finally, test the negative path deliberately: temporarily deny the test identity access to SQLite or a supported external database and correct client-site script placement. Confirm that Fathom Lite fails visibly without corrupting state, restore the correct condition and repeat the successful transaction. A release record containing those four outcomes is stronger evidence than screenshots of a dashboard or a one-time curl response.

Keep internal and external URLs straight

The public boundary for Fathom Lite should be one canonical hostname, automatic TLS and one internal target on 8080. Set the server address and public HTTPS endpoint used by the tracking script so clients return to an address the service recognizes.

If the acceptance transaction fails, classify the first error. DNS, certificate and 502 problems belong to the TLS validation checklist. The condition “the tracking script points at the wrong hostname or database path is ephemeral” belongs to the application side after a request has successfully reached Fathom Lite.

Failure drills for Fathom Lite

Capacity tests should exercise page-view write rate, database indexes, retention and the network path from visitor browsers, not a repeated request to /. Run the scenario “add a site, load the tracking script on a test page, generate visits and confirm the dashboard records them without cookies” at realistic concurrency and record latency, error rate and storage growth.

Upgrade planning must account for this risk: Fathom's database schema and tracking script should be tested together to avoid silently losing events. Test the new release with representative input, then repeat the acceptance transaction and compare its result. If the tracking script points at the wrong hostname or database path is ephemeral, capture the failing transaction and inspect the first boundary involved instead of assuming ingress is responsible.

Prove Fathom Lite survives replacement

A container image can be downloaded again; analytics database, site configuration and administrator state cannot. Mount /app before bootstrap, write harmless sample data and replace the container to prove that path is actually persistent. Inspect the effective mount instead of trusting a Compose filename, and check that the runtime user can write where Fathom Lite expects.

Choose retention and an off-host destination, then rehearse recovery without touching production. The drill passes only when sites, users and historical page views return and a new test visit appears after recovery. For database-backed state, pair storage snapshots with application-consistent exports as described in point-in-time recovery versus snapshots.

Attach Fathom Lite to Dockup's lifecycle

Dockup's one-click Fathom Lite deployment should make replacement safe: the route continues to target 8080, secrets are not baked into the image and persistent paths return on the new container. The same deployment can run on Dockup compute or an attached machine.

Complete the app-specific work by connecting and testing SQLite or a supported external database and correct client-site script placement, applying the canonical public address and running this acceptance check: add a site, load the tracking script on a test page, generate visits and confirm the dashboard records them without cookies. Add the restore result to the runbook before real users arrive.

Frequently asked questions

What does Fathom Lite need for a production deployment?

Route the Fathom Lite container on port 8080 through one HTTPS origin. The supporting network requirement is SQLite or a supported external database and correct client-site script placement. Do not call Fathom Lite ready until you can add a site, load the tracking script on a test page, generate visits and confirm the dashboard records them without cookies.

Which Fathom Lite data belongs in a backup?

Persist /app and include analytics database, site configuration and administrator state in the same recovery manifest. A clean Fathom Lite restore passes only when sites, users and historical page views return and a new test visit appears after recovery.

Does Fathom Lite require HTTPS behind a reverse proxy?

Use HTTPS for the public Fathom Lite origin and keep port 8080 on the internal route. Apply the Fathom Lite setting correctly: set the server address and public HTTPS endpoint used by the tracking script. For Fathom Lite, HTTPS protects credentials or user content in transit and keeps origin-sensitive client behavior consistent.

How should a Fathom Lite upgrade be tested?

Restore current Fathom Lite state into an isolated deployment, apply the candidate version and repeat its acceptance transaction. Pay particular attention because Fathom's database schema and tracking script should be tested together to avoid silently losing events. Keep the previous Fathom Lite image until its data-migration and rollback boundary are understood.