Knowledgebase

Fathom Analytics is a self-hosted open-source application that helps you understand web application users focusing on privacy and simplicity. Ranked as an alternative to Google analytics, Fathom Analytics offers a straightforward dashboard that works with every content management system and web application framework.

This article explains how to install Fathom Analytics on a Ubuntu 20.04 cloud server running a LEMP stack and configure Nginx as a reverse proxy. This simplifies hosting multiple websites and SSL certificates on a single server.

Prerequisites

• An existing Ubuntu 20.04 Rcs Server
• An active domain or subdomain name pointed to your server
• SSH to the server as a regular user with sudo privileges
• Install the LEMP Stack
• Update the server

Step 1: Create a New MySQL Database

1. Log in to MySQL.

    $ mysql -u root -p

2. Create a new Fathom database.

    mysql> CREATE DATABASE fathomdb;

3. Create a new user with a strong password.

    mysql> CREATE USER 'fathomuser’@’localhost' IDENTIFIED BY 'STRONG-PASSWORD';

4. Grant the user full permissions to the Fathom database.

    mysql> GRANT ALL PRIVILEGES ON Fathomdb.* TO 'fathomuser’@’localhost';

5. Reload privileges and exit the console.

    mysql>  FLUSH PRIVILEGES;
   
    mysql> EXIT

Step 2: Install Fathom Analytics

1. Change to your home directory.

    $ cd ~

2. Download the latest Fathom Analytics tarball from its GitHub page.

    $ wget https://github.com/usefathom/fathom/releases/download/v1.2.1/fathom_1.2.1_linux_amd64.tar.gz

3. Create the directory.

    $ mkdir fathom-files

4. Extract files from the tar archive.

    $ tar -xvf fathom_1.2.1_linux_amd64.tar.gz -C fathom-files

5. Change to the files directory.

    $ cd fathom-files

6. Check the current Fathom version.

    $ sudo ./fathom --version

   Output

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

Step 3: Configure Fathom Analytics

Fathom requires a database to store tables and metadata necessary for all registered websites. Database information has to be entered in a .env file. Create one inside the Fathom files directory.

1. In your favorite editor, create and edit the file .env.

    $ nano /fathom-files/.env

2. Paste the following configuration codes. This configures Fathom Analytics to run on port 8080, then connect to MySQL as the database server with your database name, username, and password you created in Step 1 of this guide.

    FATHOM_SERVER_ADDR=9000
    FATHOM_GZIP=true
    FATHOM_DEBUG=true
    FATHOM_DATABASE_DRIVER="mysql"
    FATHOM_DATABASE_NAME="fathomdb"
    FATHOM_DATABASE_USER="fathomuser"
    FATHOM_DATABASE_PASSWORD="STRONG-PASSWORD"
    FATHOM_DATABASE_HOST="localhost"
    FATHOM_SECRET="random-secret-string"

3. Save and close the file.

4. Register the first administrator user account by running fathom with user add arguments.

   Replace user@example.com with your actual email, then assign a strong password to make your Fathom installation as secure as possible.

    $ sudo ./fathom user add --email="user@example.com" --password="strong-password"

   Output

    INFO[0000] Fathom version 1.2.1, commit 8f7c6d2e45ebb28651208e2a7320e29948ecdb2c, built at 2018-11-30T09:21:37Z 
    INFO[0000] Configuration file: /home/example/fathom-files/.env 
    INFO[0000] Connected to mysql database: fathomdb on localhost 
    INFO[0001] Applied 24 database migrations!              
    INFO[0001] Created user user@example.com  

Configure Nginx to serve Fathom files on a specific subdomain, or full domain name pointed to your server. As an example, this guide uses the subdomain analytics.example.com. Replace this with your domain name.

1. In your favorite editor, create a new Nginx virtual host configuration file (server blocks) in the /etc/nginx/sites-available/ directory.

    $ sudo nano /etc/nginx/sites-available/fathomweb.conf

2. Paste the following configuration code.

    server {
   
        server_name  analytics.example.com;
   
        access_log  /var/log/nginx/fathom.access.log;
        error_log   /var/log/nginx/fathom.error.log;
   
        location / {
        proxy_pass http://localhost:9000;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $remote_addr;
        proxy_set_header Host $host;
    }
    }

3. Save and close the file.

4. Enable the configuration file by creating a link to /etc/nginx/sites-enabled/.

    $ sudo ln -s /etc/nginx/sites-available/fathomweb.conf /etc/nginx/sites-enabled/

5. Test your Nginx configuration.

    $ sudo nginx -t

6. Restart Nginx.

    $ sudo service nginx restart

7. Allow port 9000 on your firewall.

    $ sudo ufw allow 9000/tcp

Step 4: Setup Fathom Analytics as a System service

Because Fathom analytics runs as a self-hosted application, it is safe to run it as a system-wide service that starts at system boot without any manual restarts. Create a new systemd service file under /etc/systemd/system and point to both the Fathom directory and application script.

1. In your favorite editor, create and edit the file fathom.service.

    $ sudo nano /etc/systemd/system/fathom.service

2. Paste the following commands:

    [Unit]
    Description=Fathom Analytics Server
    Requires=network.target
    After=network.target
   
    [Service]
    Type=simple
    User=fathom
    Group=fathom
    Restart=always
    RestartSec=3
    WorkingDirectory=/usr/local/bin/fathom-files
    ExecStart=/usr/local/bin/fathom-files/fathom server
   
    [Install]
    WantedBy=multi-user.target

3. Save and close the file.

The systemd service file describes that Fathom runs with user account fathom, and group fathom.

1. Create the new user and group to avoid any potential run time errors.

    $ sudo adduser --system --group --home /usr/local/bin/fathom-files/ fathom

   A new user 'fathom' and group will be added to the server, and /usr/local/bin/fathom-files will be created as the home directory with no login access since a password has not been specified.

2. Copy all Fathom files to the new home directory /usr/local/bin/fathom-files/.

    $ sudo mv ~/fathom-files/.*  /usr/local/bin/fathom-files

3. Grant the user fathom full ownership to the /usr/local/bin/fathom-files/ directory.

    $ sudo chown -R fathom:fathom /usr/local/bin/fathom-files

4. Restart the systemd daemon.

    $ sudo systemctl daemon-reload

5. Enable the Fathom service.

    $ sudo systemctl enable fathom

6. Start the Fathom service.

    $ sudo systemctl start fathom

7. Check the status. Make sure it's running with no errors.

    $ sudo systemctl status fathom

Step 5: Test Fathom Analytics

Now that Fathom is running, visit your server in a web browser to launch the main application dashboard.

    http://analytics.example.com

Log in with the administrator password and email created on Step 2 of this guide. Then, start using your new Fathom Analytics application.

To link websites, copy the listed Javascript code to your website's head section to automatically add it to your dashboard.

Conclusion

You have successfully installed Fathom Analytics on a Ubuntu 20.04 cloud server running the LEMP Stack. You can link your existing websites without any limitations on traffic or the number of web applications you can add.

To secure your installation with SSL, install a free Let's Encrypt certificate on your Ubuntu 20.04 server for your Fathom Analytics domain name.