How to Self-Host Fathom Lite with Docker Compose

What Is Fathom Lite?

Fathom Lite is an open-source, privacy-focused web analytics tool that gives you simple, useful website stats without tracking personal data. It replaces Google Analytics for anyone who wants clean metrics without cookies, consent banners, or GDPR headaches. The commercial Fathom Analytics grew from this project, but the Lite version remains free and self-hostable under the MIT license.

Prerequisites

A Linux server (Ubuntu 22.04+ recommended)
Docker and Docker Compose installed (guide)
512 MB of free RAM (minimal footprint)
1 GB of free disk space
A domain name (optional, for remote access)

Docker Compose Configuration

Create a docker-compose.yml file:

services:
  fathom:
    image: usefathom/fathom:version-1.3.1
    container_name: fathom
    ports:
      - "8080:8080"
    environment:
      - FATHOM_SERVER_ADDR=:8080
      - FATHOM_DATABASE_DRIVER=sqlite3
      - FATHOM_DATABASE_NAME=/data/fathom.db?_loc=auto
      - FATHOM_SECRET=change-this-to-a-random-64-char-string
      - FATHOM_GZIP=true
      - FATHOM_DEBUG=false
    volumes:
      - fathom_data:/data
    restart: unless-stopped
    healthcheck:
      test: ["CMD", "wget", "--quiet", "--tries=1", "--spider", "http://localhost:8080/health"]
      interval: 30s
      timeout: 5s
      retries: 3

volumes:
  fathom_data:

Generate a strong secret for FATHOM_SECRET:

openssl rand -hex 32

Replace change-this-to-a-random-64-char-string with the output.

Start the stack:

docker compose up -d

MySQL Configuration (Optional)

For higher-traffic sites, use MySQL instead of SQLite:

services:
  fathom:
    image: usefathom/fathom:version-1.3.1
    container_name: fathom
    ports:
      - "8080:8080"
    environment:
      - FATHOM_SERVER_ADDR=:8080
      - FATHOM_DATABASE_DRIVER=mysql
      - FATHOM_DATABASE_NAME=fathom
      - FATHOM_DATABASE_USER=fathom
      - FATHOM_DATABASE_PASSWORD=change-this-strong-password
      - FATHOM_DATABASE_HOST=fathom-db:3306
      - FATHOM_SECRET=change-this-to-a-random-64-char-string
      - FATHOM_GZIP=true
      - FATHOM_DEBUG=false
    depends_on:
      fathom-db:
        condition: service_healthy
    restart: unless-stopped
    healthcheck:
      test: ["CMD", "wget", "--quiet", "--tries=1", "--spider", "http://localhost:8080/health"]
      interval: 30s
      timeout: 5s
      retries: 3

  fathom-db:
    image: mysql:8.0
    container_name: fathom-db
    environment:
      - MYSQL_DATABASE=fathom
      - MYSQL_USER=fathom
      - MYSQL_PASSWORD=change-this-strong-password
      - MYSQL_ROOT_PASSWORD=change-this-root-password
    volumes:
      - fathom_mysql:/var/lib/mysql
    restart: unless-stopped
    healthcheck:
      test: ["CMD", "mysqladmin", "ping", "-h", "localhost"]
      interval: 10s
      timeout: 5s
      retries: 5

volumes:
  fathom_mysql:

Initial Setup

Open http://your-server-ip:8080 in your browser
Create an admin account by running:

docker exec -it fathom ./fathom user add --email="admin@example.com" --password="your-secure-password"

Log in with the credentials you just created
Add your first site and copy the tracking snippet

Configuration

Tracking Snippet

Add this JavaScript to every page you want to track, just before </body>:

<script>
(function(f, a, t, h, o, m){
  a[h]=a[h]||function(){
    (a[h].q=a[h].q||[]).push(arguments)
  };
  o=f.createElement('script'),
  m=f.getElementsByTagName('script')[0];
  o.async=1; o.src=t; o.id='fathom-script';
  m.parentNode.insertBefore(o,m)
})(document, window, '//your-server:8080/tracker.js', 'fathom');
fathom('trackPageview');
</script>

Replace your-server:8080 with your actual Fathom URL.

Environment Variables

Variable	Default	Description
`FATHOM_SERVER_ADDR`	`:8080`	Address and port to listen on
`FATHOM_DATABASE_DRIVER`	`sqlite3`	Database driver: `sqlite3`, `mysql`, or `postgres`
`FATHOM_SECRET`	(none)	Required. Session cookie signing key
`FATHOM_GZIP`	`false`	Enable gzip compression
`FATHOM_DEBUG`	`false`	Verbose logging

PostgreSQL Configuration

If you prefer PostgreSQL:

FATHOM_DATABASE_DRIVER=postgres
FATHOM_DATABASE_NAME=fathom
FATHOM_DATABASE_USER=fathom
FATHOM_DATABASE_PASSWORD=your-password
FATHOM_DATABASE_HOST=postgres:5432
FATHOM_DATABASE_SSLMODE=disable

Reverse Proxy

For production, put Fathom behind a reverse proxy with SSL. Example Nginx Proxy Manager configuration:

Scheme: http
Forward Hostname: fathom (or container IP)
Forward Port: 8080
SSL: Request a Let’s Encrypt certificate

See Reverse Proxy Setup for detailed instructions.

Backup

Back up Fathom data:

# SQLite
docker run --rm -v fathom_data:/data -v $(pwd):/backup alpine \
  cp /data/fathom.db /backup/fathom-backup-$(date +%Y%m%d).db

# MySQL
docker exec fathom-db mysqldump -u fathom -p fathom > fathom-backup-$(date +%Y%m%d).sql

See Backup Strategy for a comprehensive approach.

Troubleshooting

Dashboard Shows No Data

Symptom: Tracking snippet is installed but no pageviews appear. Fix: Check that your tracking snippet URL matches your Fathom server address exactly, including the protocol. If using a reverse proxy, the URL in the snippet should use your public domain, not the internal address.

SQLite Database Locked Errors

Symptom: database is locked errors under moderate traffic. Fix: Switch to MySQL or PostgreSQL. SQLite handles concurrent writes poorly. For sites over ~1,000 daily visitors, use a proper database backend.

Container Won’t Start — Missing Secret

Symptom: Container exits immediately with no useful logs. Fix: Ensure FATHOM_SECRET is set. This variable is required and has no default. Generate one with openssl rand -hex 32.

MySQL Connection Refused

Symptom: dial tcp: connect: connection refused on startup. Fix: The MySQL container needs time to initialize. The depends_on with health check in the Docker Compose above handles this. If using an external MySQL, verify the host and port are correct and append ?parseTime=true&loc=Local to the database name.

Resource Requirements

RAM: ~30 MB idle, ~80 MB under load (SQLite). Add ~200 MB for MySQL.
CPU: Minimal — single-digit percentage on modern hardware
Disk: ~50 MB for the application, plus database growth (~1 KB per 1,000 pageviews with SQLite)

Verdict

Fathom Lite is the simplest self-hosted analytics you can run. If you want basic pageview metrics — visitors, page views, referrers, bounce rate — without the complexity of Matomo or the cost of commercial Fathom, it’s excellent. The trade-off is that it’s in maintenance-only mode — no new features coming. For most small sites, that’s fine. For advanced needs like custom events, user segmentation, or real-time dashboards, look at Plausible or Umami instead.

Frequently Asked Questions

Is Fathom Lite still maintained?

Fathom Lite is in maintenance-only mode. The commercial Fathom Analytics grew from this open-source version but is now a separate product. The Lite codebase receives critical bug fixes but no new features. For actively developed alternatives, look at Plausible or Umami.

Does Fathom Lite use cookies?

No. Fathom Lite is cookieless and doesn’t store any personal data about visitors. This means you don’t need cookie consent banners or GDPR popups. Visitors are counted using anonymized fingerprinting that can’t identify individuals.

Can Fathom Lite handle high-traffic sites?

With SQLite, it handles up to ~1,000 daily visitors well. Above that, SQLite’s write locking becomes a bottleneck under concurrent writes. Switch to MySQL or PostgreSQL for higher-traffic sites. The MySQL configuration above can handle tens of thousands of daily visitors.

How does Fathom Lite compare to Plausible?

Plausible is actively maintained with more features: real-time dashboard, UTM tracking, goals/events, custom properties, and an API. Fathom Lite is simpler and lighter — it tracks pageviews, referrers, and basic metrics. Choose Plausible for a production analytics platform; choose Fathom Lite for dead-simple stats on a low-traffic site.

Can I track multiple websites with one Fathom Lite instance?

Yes. You can add multiple sites in the dashboard, each with its own tracking snippet. All data is stored in the same database and accessible from the same admin UI.

Does Fathom Lite support custom events or goals?

No. Fathom Lite only tracks pageviews and basic metrics (referrers, browser, screen size). For event tracking and goals, use Plausible or Umami.