Easy and privacy-compliant analytics with Fathom

Julien Tanguy, . Tagged

I recently read an article by Nick Rempel about De-Googling his life. In this article, he talks about Fathom, a privacy-compliant analytics solution.

This solution offers a simpler and easier alternative to Google Analytics, si I decided to give it a try.

Installation on Clever Cloud

By looking at Fathom’s github repo, I saw that there are three ways to deploy fathom:

  1. Build it from source, using the provided Makefile, with Go and Node.
  2. Using the Pre-built docker image
  3. Using a dirty hack I remembered from reading ClĂ©ment Delafargue’s blog on deploying haskell apps before they were natively supported.

I was not sure about the first option, since I don’t know anything about deploying Go apps, and the makefile route looked potentially difficult. Using docker is a better alternative, but the third option offers a cheaper alternative for a really low-traffic site.

The setup

First, let’s create our app and postgresql addon

clever create fathom -t node
clever scale --flavor pico
clever addon create postgresql-addon -l fathom

Now let’s hack into the build

clever env set CC_PRE_BUILD_HOOK "wget https://github.com/usefathom/fathom/releases/download/v1.2.1/fathom_1.2.1_linux_amd64.tar.gz"

Let’s create a simple package.json that unzips the tarball on install, and runs the server on start.

  "name": "fathom",
  "version": "1.0.0",
  "description": "Fathom dummy package",
  "scripts": {
    "install": "tar -xzf ./fathom_1.2.1_linux_amd64.tar.gz",
    "start": "./fathom server"
  "author": "Julien Tanguy <julien.tanguy@jhome.fr>",
  "license": "MIT"

Now here is the catch: fathom does not read its config from the environment, but from a .env file. Fortunately, we can hack around this by generating the .env using another clever hook.

clever env set CC_PRE_RUN_HOOK "./hydrate.sh"

We also commit the necessary file, that creates a .env from the environment. Note that we run this hook on each run, in case we decide later to link this to a different addon or something.

#! /bin/sh
# hydrate.sh
# Create a .env file with the env vars,
# since fathom does not seem to use the environment
cat <<EOF > .env

Now we set a secret for fathom’s session cookies chosen by fair dice roll, guaranteed to be random

clever env set FATHOM_SECRET "something very secret and random, like 4"

Now let’s deploy

clever deploy

Setting up the first user

Let’s setup the first user by running fathom locally with the correct .env pointing to Clever Cloud

./fathom user add --email=<email> --password=<password>


Now log in to our new instance

clever open

Profit !

We can now add a new website and use our simple analytics tool.