Learn how to – Install Fathom analytics on Ubuntu/Debian/CentOS

Learn how to – Install Fathom analytics on Ubuntu/Debian/CentOS.

In this blog post, you’ll learn to install and use the Fathom Analytics tool on Linux – Ubuntu/Debian/CentOS/Arch e.t.c. Fathom Analytics is an open source, easy to use and more privacy-focused alternative to Google Analytics.

This tool will help you collect information on the internet about any web service, can be for service/content improvement, historical analytics e.t.c. Your data and all users’ privacy are kept private by this free tool. Furthermore, Fathom respects the privacy of your users and does not collect any personally identifiable information.

Install Fathom website analytics tool on Linux

Install wget and curl tools:

### Ubuntu / Debian ###
sudo apt update
sudo apt install curl wget

### Fedora / CentOS ###
sudo yum -y install curl wget

Download the latest release of Fathom with wget

VER=$(curl -s https://api.github.com/repos/usefathom/fathom/releases/latest|grep tag_name|cut -d '"' -f 4|sed 's/v//')
wget https://github.com/usefathom/fathom/releases/download/v${VER}/fathom_${VER}_linux_amd64.tar.gz

Extract the downloaded file:

tar xvf fathom_${VER}_linux_amd64.tar.gz

Make the file executable

chmod +x fathom

Move the binary file to  /usr/local/bin directory:

sudo mv fathom /usr/local/bin

Use option--help to print help page.

$ fathom --help
INFO[0000] Fathom version 1.2.1, commit 8f7c6d2e45ebb28651208e2a7320e29948ecdb2c, built at 2018-11-30T09:21:37Z
NAME:
   Fathom - simple & transparent website analytics

USAGE:
   fathom [global options] command [command options] [arguments...]

VERSION:
   1.2.1, commit 8f7c6d2e45ebb28651208e2a7320e29948ecdb2c, built at 2018-11-30T09:21:37Z

COMMANDS:
     server, s  start the fathom web server
     user       manage registered admin users
     stats      view stats
     help, h    Shows a list of commands or help for one command

GLOBAL OPTIONS:
   --config FILE, -c FILE  Load configuration from FILE (default: ".env")
   --help, -h              show help
   --version, -v           print the version

How to use Fathom Analytics tool

Before you can start using Fathom, you need to register your user account

$ fathom register --email=<email> --password=<password>

Sample output

NFO[0000] Fathom 1.2.1                                 
WARN[0000] Error reading configuration. File `.env` does not exist. 
INFO[0000] Connected to sqlite3 database: /home/jmutai/fathom.db?_loc=auto 
INFO[0000] Created user useremail@example.com

Read more about Fathom Configuration file to understand all possible configuration values.

Starting the Fathom web server

Create a  .env configuration file named with the following contents.

FATHOM_SERVER_ADDR=9000
FATHOM_DEBUG=true
FATHOM_DATABASE_DRIVER="sqlite3"
FATHOM_DATABASE_NAME="fathom.db"
FATHOM_SECRET="random-secret-string"

Once you have Fathom configured, you can start Fathom web server using the command fathom server.

fathom server

This should start serving up a website on port 9000 using an SQLite database file named fathom.db.

Manage Service with systemd

To ensure the Fathom web server starts on the system reboot, we should use Systemd.

Create a new file called /etc/systemd/system/fathom.service with the following contents. Replace $USER with your actual username.

sudo tee /etc/systemd/system/fathom.service<<EOF
[Unit]
Description=Fathom server management service unit
Requires=network.target
After=network.target

[Service]
Type=simple
User=$USER
Restart=always
RestartSec=3
WorkingDirectory=/home/$USER
ExecStart=/usr/local/bin/fathom server

[Install]
WantedBy=multi-user.target
EOF

Reload the Systemd configuration and enable the service start on boot.

sudo systemctl daemon-reload
sudo systemctl enable fathom.service

Start Fathom web server by issuing the following command.

sudo systemctl start fathom.service

The service should start and switch to a running status.

Open the link http://server-ip-address-here:9000 to access Fathom dashboard.

Running Fathom with NGINX

Install nginx on CentOS

sudo yum install epel-release
sudo yum install nginx

Install nginx  on Ubuntu / Debian

sudo apt install nginx

Install nginx Arch

sudo pacman -S nginx

We then use NGINX to redirect all traffic for a certain domain to our Fathom application running on port 8080 by using the directiveproxy_pass.

$ sudo ss -tunelp | grep 8080
tcp   LISTEN 0      4096               *:8080             *:*    users:(("fathom",pid=31420,fd=5)) uid:1000 ino:59315 sk:a cgroup:/system.slice/fathom.service v6only:0 <->

Create the following file in /etc/nginx/conf.d/fathom.conf

sudo vim /etc/nginx/conf.d/fathom.conf

Add:

server {
	server_name fathomsite.com;

	location / {
		proxy_set_header X-Real-IP $remote_addr;
		proxy_set_header X-Forwarded-For $remote_addr;
		proxy_set_header Host $host;
		proxy_pass http://127.0.0.1:8080; 
	}
}

Test configuration syntax and restart nginx

sudo nginx -t
sudo systemctl enable nginx
sudo systemctl restart nginx

Open the link http://fathomsite.com to access the Fathom dashboard.

Login with the configured email address and password

Tracking snippet

To start tracking, include the following JavaScript on your site and replace yourfathom.com with the URL to your Fathom instance.

<!-- Fathom - simple website analytics - https://github.com/usefathom/fathom -->
<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, '//yourfathom.com/tracker.js', 'fathom');
fathom('trackPageview');
</script>
<!-- / Fathom -->

For a WordPress website, use Fathom WordPress Plugin

1. In your WordPress admin panel, go to Plugins > New Plugin, search for Fathom Analytics and click “Install now“

2. Alternatively, download the plugin and upload the contents of fathom-analytics.zip to your plugins directory, which usually is /wp-content/plugins/.

After installing and activating this plugin, go to Settings > General and enter the URL to your Fathom instance in the text field near the bottom.

After a few minutes, the analytics should start showing.

Thanks for using our guide to setup your personal analytics engine powered by Fathom. For any query drop a comment and I’ll be happy to respond.