Come installare Fathom Web Analytics su Debian 12

Fathom su Debian 12: scelta architetturale

Fathom Web Analytics è una piattaforma di analytics leggera, pensata per chi vuole metriche essenziali senza caricare il sito con script pesanti o dipendere da stack complessi. Su Debian 12 conviene installarlo come servizio dedicato, con database PostgreSQL o MySQL/MariaDB, dietro reverse proxy TLS, separando bene i ruoli: applicazione, database e front-end web.

La strada più pulita in produzione è questa: creare un utente dedicato, installare il binario o il pacchetto disponibile per la versione scelta, configurare il database, avviare Fathom come servizio systemd e pubblicarlo solo tramite HTTPS. Se hai già un reverse proxy come Nginx o Apache, Fathom può restare in ascolto su localhost.

Prima di partire, verifica di avere accesso root o sudo, un DNS già pronto per il nome host che userai, e un server Debian 12 aggiornato.

Prerequisiti sul server

Assumi un sistema Debian 12 minimale. Aggiorna i pacchetti e installa gli strumenti base:

sudo apt update
sudo apt upgrade -y
sudo apt install -y curl ca-certificates gnupg lsb-release ufw

Se userai PostgreSQL:

sudo apt install -y postgresql

Se preferisci MariaDB/MySQL, installa il relativo server. In ogni caso, per una piccola installazione Fathom, PostgreSQL è spesso la scelta più lineare in termini di affidabilità e manutenzione.

Decidi anche il nome host pubblico, ad esempio analytics.example.com, e assicurati che il record DNS A o AAAA punti al server corretto. Se il DNS non è ancora propagato, la parte HTTPS e i test con il browser saranno fuorvianti.

Creazione utente e directory di servizio

È buona pratica evitare l’esecuzione come root. Crea un utente di sistema senza shell interattiva:

sudo useradd --system --home /var/lib/fathom --create-home --shell /usr/sbin/nologin fathom

Prepara le directory per dati e log, con permessi coerenti:

sudo mkdir -p /etc/fathom /var/lib/fathom /var/log/fathom
sudo chown -R fathom:fathom /var/lib/fathom /var/log/fathom

Se prevedi di usare un file di configurazione, tienilo in /etc/fathom con permessi stretti:

sudo chown -R root:fathom /etc/fathom
sudo chmod 750 /etc/fathom

Questo limita l’esposizione accidentale di credenziali e variabili sensibili.

Database: PostgreSQL come opzione consigliata

Su Debian 12, PostgreSQL è una scelta robusta e semplice da automatizzare. Installa il server se non è già presente e crea database e utente dedicati.

sudo -u postgres psql

Nel prompt SQL:

CREATE USER fathom WITH PASSWORD 'SOSTITUISCI_CON_PASSWORD_FORTE';
CREATE DATABASE fathom OWNER fathom;

Se preferisci evitare di digitare la password in chiaro nella shell, puoi usare un file temporaneo protetto o un secret manager. Non lasciare password nel history del terminale.

Verifica la connettività locale al database:

psql -h 127.0.0.1 -U fathom -d fathom -c 'SELECT 1;'

Esito atteso: una riga con 1. Se fallisce, controlla autenticazione, metodo pg_hba.conf e servizio PostgreSQL.

Installazione del binario Fathom

La distribuzione di Fathom può variare in base alla versione e al metodo scelto. In pratica hai due strade: usare un binario rilasciato upstream o un pacchetto mantenuto dalla tua organizzazione. Se non hai un repository ufficiale già validato, il binario upstream è spesso la via più veloce.

Scarica l’archivio o il binario dalla release ufficiale corrispondente alla tua architettura, ad esempio amd64. Il comando esatto dipende dalla release corrente, quindi qui il punto importante è la verifica della firma, dell’hash e della provenienza. Non saltare questo passaggio in produzione.

Una volta ottenuto il binario, posizionalo in una directory standard, ad esempio /usr/local/bin:

sudo install -m 0755 fathom /usr/local/bin/fathom

Controlla che sia eseguibile:

fathom --help

Se il comando non è riconosciuto, il problema è il path o il nome del binario. Se stampa l’help, la parte eseguibile è a posto.

Configurazione iniziale di Fathom

La configurazione dipende dalla versione, ma il concetto resta uguale: definire database, porta di ascolto, dominio pubblico e segreti applicativi. Mantieni la configurazione in /etc/fathom e usa un file dedicato, ad esempio /etc/fathom/fathom.env.

Un esempio di impostazione basata su variabili d’ambiente:

FATHOM_DATABASE_DRIVER=postgres
FATHOM_DATABASE_DSN=host=127.0.0.1 port=5432 user=fathom password=SOSTITUISCI_CON_PASSWORD_FORTE dbname=fathom sslmode=disable
FATHOM_SERVER_ADDR=127.0.0.1:8080
FATHOM_BASE_URL=https://analytics.example.com

Il nome esatto delle variabili può cambiare tra versioni: confrontalo con la documentazione della release che hai scaricato. Questo è un punto in cui non bisogna improvvisare. Se il tuo pacchetto usa un file di configurazione diverso, adatta il percorso ma mantieni gli stessi principi: binding su localhost, database esterno, URL pubblico corretto.

Proteggi il file:

sudo chown root:fathom /etc/fathom/fathom.env
sudo chmod 640 /etc/fathom/fathom.env

Service systemd

Per un’installazione stabile su Debian 12, crea un’unità systemd. In questo modo hai avvio automatico, restart controllato e log integrati con journald.

File: /etc/systemd/system/fathom.service

[Unit]
Description=Fathom Web Analytics
After=network-online.target postgresql.service
Wants=network-online.target

[Service]
User=fathom
Group=fathom
EnvironmentFile=/etc/fathom/fathom.env
WorkingDirectory=/var/lib/fathom
ExecStart=/usr/local/bin/fathom server
Restart=on-failure
RestartSec=5
NoNewPrivileges=true
PrivateTmp=true

[Install]
WantedBy=multi-user.target

Ricarica systemd e abilita il servizio:

sudo systemctl daemon-reload
sudo systemctl enable --now fathom

Verifica subito lo stato:

systemctl status fathom --no-pager

Esito atteso: active (running). Se è failed, guarda i log con:

journalctl -u fathom -n 100 --no-pager

Gli errori più comuni sono DSN errato, database non raggiungibile, porta già occupata o variabili d’ambiente non lette correttamente.

Reverse proxy con Nginx

È preferibile esporre Fathom solo dietro Nginx con TLS. Installa Nginx:

sudo apt install -y nginx

Crea un virtual host, ad esempio /etc/nginx/sites-available/analytics.example.com:

server {
    listen 80;
    server_name analytics.example.com;

    location / {
        return 301 https://$host$request_uri;
    }
}

server {
    listen 443 ssl http2;
    server_name analytics.example.com;

    ssl_certificate /etc/letsencrypt/live/analytics.example.com/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/analytics.example.com/privkey.pem;

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

Attiva il sito e verifica la sintassi:

sudo ln -s /etc/nginx/sites-available/analytics.example.com /etc/nginx/sites-enabled/
sudo nginx -t
sudo systemctl reload nginx

Se usi solo HTTP per il test iniziale, lascia temporaneamente il blocco 80 e aggiungi TLS dopo. In produzione, però, HTTPS va completato subito.

Certificato TLS con Let’s Encrypt

Installa Certbot:

sudo apt install -y certbot python3-certbot-nginx

Richiedi il certificato per il tuo host:

sudo certbot --nginx -d analytics.example.com

Verifica il rinnovo automatico:

sudo systemctl status certbot.timer --no-pager
sudo certbot renew --dry-run

Esito atteso: rinnovo simulato completato senza errori. Se fallisce, controlla DNS pubblico, reachability della porta 80 verso il server e configurazione del virtual host.

Prima inizializzazione dell’applicazione

A seconda della versione, Fathom può richiedere la creazione dell’utente amministratore via interfaccia web o tramite comando CLI. Se la tua release espone un wizard web, visita https://analytics.example.com e completa i campi richiesti. Se invece prevede un comando di bootstrap, eseguilo seguendo la documentazione della versione installata.

Per non inventare il comando esatto, il controllo corretto è questo: leggi l’help locale del binario e la documentazione della release:

fathom --help
strings /usr/local/bin/fathom | grep -i version

In caso di dubbi, la presenza di una pagina iniziale o di un errore applicativo nei log di journald ti dirà se il binario è partito ma manca la fase di setup.

Verifiche funzionali

Prima di considerare l’installazione conclusa, verifica questi punti in modo oggettivo:

1. Servizio attivo: systemctl is-active fathom deve restituire active.
2. Porta in ascolto: ss -ltnp | grep 8080 deve mostrare il processo Fathom su localhost.
3. Reverse proxy: curl -I https://analytics.example.com deve restituire un HTTP/2 200, 301 o comunque una risposta coerente con la tua inizializzazione.
4. Log puliti: journalctl -u fathom -n 50 non deve mostrare panic, errori di DB o binding.

Se il sito risponde ma la dashboard non carica, la causa più probabile è un problema di base URL, proxy headers o configurazione database.

Hardening minimo

Per un uso serio, applica almeno queste misure:

• Fathom in ascolto solo su 127.0.0.1.
• Firewall che espone solo 80 e 443, non la porta applicativa.
• Utente di sistema dedicato senza shell.
• Permessi stretti su config e segreti.
• Backup del database pianificato con retention adeguata.

Se usi UFW:

sudo ufw allow OpenSSH
sudo ufw allow 80/tcp
sudo ufw allow 443/tcp
sudo ufw enable

Controlla con attenzione che non ci siano porte esposte inutilmente:

sudo ss -ltnp

Se vedi Fathom su 0.0.0.0:8080, correggi il binding prima di andare in produzione.

Backup e manutenzione

La parte che spesso viene dimenticata è la protezione del database. Pianifica backup giornalieri con pg_dump e verifica periodicamente il restore. Un backup non testato è solo un file in più.

pg_dump -h 127.0.0.1 -U fathom fathom | gzip > /var/backups/fathom-$(date +%F).sql.gz

Metti il comando in cron o in un timer systemd e conserva copie fuori dal server se i dati hanno valore operativo. Se il volume di dati è ridotto, anche un dump compresso è sufficiente nella maggior parte dei casi.

Per gli aggiornamenti, procedi in modo conservativo: snapshot o backup, stop del servizio, sostituzione del binario o upgrade del pacchetto, riavvio, verifica log e accesso web. Non aggiornare mai senza avere un rollback semplice, soprattutto se il database o il formato di configurazione cambiano tra versioni.

Problemi tipici e come riconoscerli

Se la pagina mostra errore 502, il reverse proxy non raggiunge Fathom: controlla systemctl status fathom, ss -ltnp e proxy_pass. Se hai timeout, spesso il servizio è avviato ma bloccato sul database.

Se vedi pagina bianca o asset mancanti, il problema è di solito il BASE_URL o gli header del proxy. Se il login fallisce subito, controlla il database e i permessi dell’utente applicativo. Se il certificato non si rinnova, il punto debole è quasi sempre il DNS o la reachability della porta 80 verso Let’s Encrypt.

Quando qualcosa non torna, la triade da guardare è sempre la stessa: log del servizio, stato del database, e risposta HTTP dal proxy. Questo riduce il tempo perso su ipotesi sbagliate.

Chiusura operativa

Su Debian 12, Fathom funziona bene se lo tratti come un servizio vero: utente dedicato, database separato, proxy TLS, log controllati e backup del database. La parte più importante non è l’installazione in sé, ma la disciplina nel mantenerla semplice e verificabile.

Se devi adattare questa procedura a una release specifica di Fathom, il punto da chiudere è la sintassi esatta delle variabili d’ambiente o del comando di bootstrap: verifica sempre con la documentazione della release e con fathom --help prima di mettere in produzione.