Fathom Lite Documentation

Fathom is designed to track no personally identifiable information (PII).

Tracking Logic:

• Unique Visitors: Visitors are assigned a random string to identify unique pageviews.
• Session Processing: If a visitor moves to another page, the previous pageview is processed and deleted within 1 minute. If the visitor leaves the site, the pageview is processed and deleted when the session ends (after 30 minutes).
• Do Not Track (DNT): Fathom respects the navigator.doNotTrack setting in user browsers. If DNT is enabled, Fathom will not track that visitor.

To run Fathom as a background service that automatically restarts on server reboots (on Ubuntu 16.04 or later), create a service configuration file at /etc/systemd/system/fathom.service. Ensure the fathom binary is installed and available in your $PATH.

[Unit]
Description=Starts the fathom server
Requires=network.target
After=network.target

[Service]
Type=simple
User=$USER
Restart=always
RestartSec=6
WorkingDirectory=/etc/fathom # (or where fathom should store its files)
ExecStart=fathom server

[Install]
WantedBy=multi-user.target

It is recommended to use NGINX to handle multiple sites and SSL certificates. Create an NGINX configuration file (e.g., in /etc/nginx/sites-enabled/) to proxy requests to the Fathom server running on 127.0.0.1:9000.

After creating the configuration, test and reload NGINX.

# Create config in /etc/nginx/sites-enabled/my-fathom-site
server {
	server_name my-fathom-site.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:9000; 
	}
}

# Test and reload
nginx -t
service nginx reload

To run a development version of Fathom Lite, ensure you have Go and NPM installed, then follow these steps:

1. Clone the repository into your GOPATH: git clone https://github.com/usefathom/fathom.git $GOPATH/src/github.com/usefathom/fathom
2. Compile the project: make build
3. (Optional) Configure custom values as per the configuration documentation.
4. (Required) Create an initial user account using the CLI.
5. Start the webserver and access the dashboard at http://localhost:8080.

git clone https://github.com/usefathom/fathom.git $GOPATH/src/github.com/usefathom/fathom
make build
./fathom user add --email=<email> --password=<password>
./fathom server

To ensure the Fathom server restarts automatically on system reboot, create a Systemd service file at /etc/systemd/system/my-fathom-site.service.

Ensure you replace $USER with your actual username and set the WorkingDirectory to the directory containing your .env file.

After creating the file, reload the daemon, enable the service, and start it.

# Create /etc/systemd/system/my-fathom-site.service
[Unit]
Description=Starts the fathom server
Requires=network.target
After=network.target

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

[Install]
WantedBy=multi-user.target

# Apply changes
systemctl daemon-reload
systemctl enable my-fathom-site
systemctl start my-fathom-site

Instead of individual database settings, you can use FATHOM_DATABASE_URL to provide a single connection string.

When using specific drivers, ensure you include the following parameters in your DSN:

• MySQL: Include ?parseTime=true&loc=Local.
• SQLite: Include ?_loc=auto.

Example for MySQL:

FATHOM_DATABASE_DRIVER=mysql
FATHOM_DATABASE_URL=root:@tcp/fathom1?loc=Local&parseTime=true

After deploying Fathom to Heroku, you need to create your first user via the Heroku CLI to access the dashboard. Use the fathom user add command.

heroku run fathom user add --email="test@test.com" --password="test_password"

After creating your /etc/systemd/system/fathom.service file, follow these steps to manage the service:

1. Reload systemd: Run sudo systemctl daemon-reload to load the new configuration.
2. Enable at boot: Run sudo systemctl enable fathom to ensure the service starts automatically when the system boots.
3. Disable at boot: Run sudo systemctl disable fathom to prevent the service from starting automatically at boot.
4. Manual control:
   • Start: sudo systemctl start fathom
   • Stop: sudo systemctl stop fathom

After updating the Fathom binary, you must restart the running web server process for changes to take effect.

If using Systemd (standard installation): Use systemctl to restart your specific Fathom service: systemctl restart <your-fathom-service>

Manual method: Alternatively, you can stop the server by killing all running Fathom processes: pkill fathom

systemctl restart my-fathom-site
# OR
pkill fathom