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.2.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.2.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

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

docker exec -it fathom ./fathom user add --email="[email protected]" --password="your-secure-password"

3. Log in with the credentials you just created
4. 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.

Related

• Plausible vs Fathom Lite: Privacy Analytics
• Plausible vs Fathom Lite: Privacy Analytics Compared
• Best Self-Hosted Analytics
• Plausible vs Umami: Which Analytics to Self-Host?
• Plausible vs Matomo: Full-Featured vs Privacy-First
• Self-Hosted Alternatives to Google Analytics
• How to Self-Host Plausible
• How to Self-Host Umami
• Docker Compose Basics
• Reverse Proxy Setup
• Backup Strategy