Update 2019-05-27: changes to work with the latest version of Fathom (1.2.1).
I recently replaced Google Analytics with Fathom, a new self-hosted website analytics service with a huge focus on privacy and owning your own data.
They offer a Docker image but the documentation on setting it up is a bit sparse. Here are the steps I took to get it up and running with data persistence.
The simplest way to get Fathom running is to run this command:
docker run -d --name=fathom -p 8080:8080 usefathom/fathom:latest
That’s all well and good, but what if you want to persist the data?
Persisting the SQLite Database
Figuring out how to persist the data was a little tricky because of how it’s stored in the image. If you run were to run
ls in a running fathom container, you would see this:
$ docker exec -it fathom /bin/sh /app # ls fathom fathom.db
The working directory of the container is
/app which holds both the fathom executable and the SQLite database. This means that you simply can’t mount a volume from the host initially because mounted volumes from the host overwrite the path inside the container. Meaning, if you were to mount a volume from your host to
/app, the executable would no longer exist and as such fathom would not be able to run.
Using a Docker Volume
You can, however, use a Docker volume instead of mounting a host path. This works because Docker volumes behave a bit differently than mounted host volumes, as they do not overwrite the path within the container.
To use a Docker volume, create a new one named
fathom and mount it to
$ docker volume create fathom $ docker run -d --name=fathom -p 8080:8080 -v fathom:/app usefathom/fathom:latest
Using a Host Volume
What if you’d rather have the database live on the host and not in a Docker volume? That can be achieved by copying the database to the host using
docker cp and then re-running the
docker run command with a volume pointing to only the database.
For these examples, I’ll be using
/host/fathom as the fathom volume path on the host machine.
docker cp fathom:/app/fathom.db /host/fathom/fathom.db
Now you can stop the running container and start it up again with the volume:
$ docker stop fathom $ docker rm fathom $ docker run -d --name=fathom -p 8080:8080 -v /host/fathom/fathom.db:/app/fathom.db usefathom/fathom:latest
If you prefer to use a Docker compose file:
version: '3' services: fathom: image: usefathom/fathom:latest volumes: - /host/fathom/fathom.db:/app/fathom.db ports: - 8080:8080
To use Postgres instead of SQLite, modify your compose file to include a postgres container with your own credentials. Additionally, you’ll need to add some extra environment variables to the fathom container so the app will use your postgres database:
Note: Fathom expects a database named
version: '3' services: fathom: image: usefathom/fathom:latest environment: FATHOM_DATABASE_DRIVER: postgres FATHOM_DATABASE_HOST: postgres FATHOM_DATABASE_PASSWORD: password123 FATHOM_DATABASE_USER: fathom FATHOM_DATABASE_SSLMODE: disable depends_on: - postgres ports: - 8080:8080 postgres: image: postgres:latest volumes: - /host/fathom/data:/var/lib/postgresql/data environment: POSTGRES_DB: "fathom.db" POSTGRES_USER: fathom POSTGRES_PASSWORD: password123
Before you can login to the UI, create an account by running this command:
$ docker exec fathom ./fathom user add --email="[email protected]" --password="yourpassword"
The last step is to include the tracking snippet on your site and you’re ready to go!