Comment auto-héberger Fathom Lite en 2026 : script de suivi, SQLite et confidentialité

Il existe deux façons de « faire fonctionner Fathom Lite » : disposer d’un container, ou faire en sorte que le service remplisse réellement sa fonction. Seule la seconde compte. La preuve consiste à ajouter un site, charger le script de suivi sur une page de test, générer des visites et vérifier que le dashboard les enregistre sans cookies.

Fathom Lite répond à ce besoin : fournir des analytics de pages vues sans cookies et auto-hébergés. Le déploiement doit préserver les éléments qui permettent ce fonctionnement ; un port, un volume et un certificat sont des prérequis, pas le résultat.

Identifiants, rôles et surfaces exposées

Pour Fathom Lite, la surface sensible n’est pas nécessairement la landing page. L’erreur principale consiste à réutiliser un secret d’exemple ou à exposer la connexion d’administration sans TLS. Prévenez ce problème de manière délibérée : protégez la connexion aux analytics, conservez le secret applicatif stable et publiez le script uniquement depuis l’hôte HTTPS attendu.

Traitez FATHOM_SECRET conformément à son rôle dans Fathom Lite : gardez les valeurs sensibles hors de Git, documentez les effets d’une rotation et ne remplacez jamais une valeur d’exemple publique en production. Utilisez un utilisateur de container non privilégié lorsque l’image le permet et ne montez aucun identifiant sans rapport. Appliquez des limites de débit ou de taille au niveau de l’ingress, là où des requêtes non fiables peuvent consommer le débit d’écriture des pages vues, les index de la base de données, la rétention et le chemin réseau entre les navigateurs des visiteurs.

Séparer Fathom Lite de ses dépendances

La topologie Fathom Lite responsable la plus réduite comprend un listener privé sur le port 8080, une route d’ingress et une limite d’état documentée. Le contrat réseau de Fathom Lite repose sur SQLite ou une base de données externe prise en charge, ainsi que sur le placement correct du script côté site client. Conservez les endpoints privés dans un DNS interne, n’autorisez que les appels sortants nécessaires et fournissez à Fathom Lite un identifiant de service aux permissions limitées.

Validez la topologie en demandant à un client vierge d’ajouter un site, de charger le script de suivi sur une page de test, de générer des visites et de vérifier que le dashboard les enregistre sans cookies. Surveillez le débit d’écriture des pages vues, les index de la base de données, la rétention et le chemin réseau entre les navigateurs des visiteurs pendant l’exécution. Le résultat vous indique si la prochaine amélioration concerne la mémoire, le stockage, le réseau ou un worker séparé, plutôt que de vous inciter à dimensionner arbitrairement le container.

Une base Docker pour Fathom Lite

Une commande minimale est utile lorsqu’elle révèle ce que la plateforme gérera ensuite.

docker run -d \
  --name fathom-lite \
  --restart unless-stopped \
  -p 127.0.0.1:8080:8080 \
  -v fathom-lite-data:/app \
  -e FATHOM_SECRET=replace-with-a-long-random-value \
  -e FATHOM_SERVER_ADDR=:8080 \
  -e FATHOM_DATABASE_DRIVER=sqlite3 \
  -e FATHOM_DATABASE_NAME=/app/fathom.db \
  usefathom/fathom:latest

Ici, le port 8080 reste privé sur l’hôte et chaque chemin requis est explicite. Ajoutez les paramètres de connexion validés pour SQLite ou une base de données externe prise en charge, ainsi que le placement correct du script côté site client ; utilisez des noms privés pour les services privés. Vérifiez le démarrage à la fois dans les logs et avec la preuve propre à l’application : ajoutez un site, chargez le script de suivi sur une page de test, générez des visites et vérifiez que le dashboard les enregistre sans cookies. Une fois le fonctionnement vérifié, verrouillez la version de l’image afin qu’un remplacement standard ne modifie pas silencieusement le comportement.

Prouver le fonctionnement de bout en bout du déploiement Fathom Lite

Créez un petit environnement de test Fathom Lite jetable et conservez-le pour chaque release. Ce test doit couvrir le workflow réel : ajouter un site, charger le script de suivi sur une page de test, générer des visites et vérifier que le dashboard les enregistre sans cookies. Notez le digest de l’image, le hostname externe, l’adresse de la dépendance et le résultat attendu afin qu’un autre opérateur puisse reproduire le test sans devoir interpréter ce guide.

Exécutez le test trois fois. D’abord avec le déploiement fraîchement créé. Ensuite, remplacez le container sans toucher à l’état durable. Enfin, restaurez la sauvegarde dans un environnement vide. Le troisième test ne réussit que si les sites, les utilisateurs et l’historique des pages vues sont restaurés et qu’une nouvelle visite de test apparaît après la récupération. À chaque exécution, mesurez la latence et l’utilisation des ressources autour du débit d’écriture des pages vues, des index de la base de données, de la rétention et du chemin réseau entre les navigateurs des visiteurs ; ces données constituent la baseline des alertes, plutôt qu’un pourcentage de CPU arbitraire.

Enfin, testez volontairement le chemin d’échec : refusez temporairement à l’identité de test l’accès à SQLite ou à une base de données externe prise en charge, ainsi qu’au placement correct du script côté site client. Vérifiez que Fathom Lite échoue de manière visible sans corrompre l’état, rétablissez la configuration correcte et répétez la transaction réussie. Un compte rendu de release contenant ces quatre résultats constitue une preuve plus solide que des captures d’écran du dashboard ou qu’une réponse curl ponctuelle.

Bien distinguer les URL internes et externes

La frontière publique de Fathom Lite doit reposer sur un hostname canonique, un TLS automatique et une cible interne unique sur le port 8080. Configurez l’adresse du serveur et l’endpoint HTTPS public utilisé par le script de suivi afin que les clients reviennent vers une adresse reconnue par le service.

Si la transaction d’acceptation échoue, classez la première erreur rencontrée. Les problèmes de DNS, de certificat et de 502 relèvent de la checklist de validation TLS. La condition « le script de suivi pointe vers le mauvais hostname ou le chemin de la base de données est éphémère » relève de l’application, une fois qu’une requête a bien atteint Fathom Lite.

Tests de défaillance pour Fathom Lite

Les tests de capacité doivent couvrir le débit d’écriture des pages vues, les index de la base de données, la rétention et le chemin réseau entre les navigateurs des visiteurs, et non envoyer une requête répétée vers /. Exécutez le scénario « ajouter un site, charger le script de suivi sur une page de test, générer des visites et vérifier que le dashboard les enregistre sans cookies » avec une concurrence réaliste, puis mesurez la latence, le taux d’erreur et la croissance du stockage.

La planification des upgrades doit tenir compte de ce risque : le schéma de base de données de Fathom et le script de suivi doivent être testés ensemble pour éviter de perdre silencieusement des événements. Testez la nouvelle release avec des données représentatives, puis répétez la transaction d’acceptation et comparez le résultat. Si le script de suivi pointe vers le mauvais hostname ou si le chemin de la base de données est éphémère, capturez la transaction en échec et examinez la première limite concernée au lieu de supposer que l’ingress est responsable.

Prouver que Fathom Lite survit à un remplacement

Une image de container peut être téléchargée à nouveau ; la base de données d’analytics, la configuration des sites et l’état de l’administrateur, eux, ne peuvent pas l’être. Montez /app avant l’initialisation, écrivez quelques données de test inoffensives et remplacez le container pour prouver que ce chemin est réellement persistant. Inspectez le montage effectif au lieu de vous fier au nom d’un fichier Compose, et vérifiez que l’utilisateur d’exécution peut écrire à l’emplacement attendu par Fathom Lite.

Choisissez une politique de rétention et une destination hors hôte, puis répétez la récupération sans toucher à la production. Le test ne réussit que si les sites, les utilisateurs et l’historique des pages vues sont restaurés et qu’une nouvelle visite de test apparaît après la récupération. Pour les états stockés dans une base de données, associez des snapshots du stockage à des exports cohérents au niveau applicatif, comme indiqué dans récupération à un instant donné ou snapshots.

Intégrer Fathom Lite au cycle de vie de Dockup

Le déploiement Fathom Lite en un clic de Dockup doit rendre les remplacements sûrs : la route continue de cibler le port 8080, les secrets ne sont pas intégrés à l’image et les chemins persistants sont réutilisés par le nouveau container. Le même déploiement peut fonctionner sur le compute de Dockup ou sur une machine connectée.

Terminez les étapes propres à l’application en configurant et en testant SQLite ou une base de données externe prise en charge, ainsi que le placement correct du script côté site client, en appliquant l’adresse publique canonique et en exécutant cette vérification d’acceptation : ajoutez un site, chargez le script de suivi sur une page de test, générez des visites et vérifiez que le dashboard les enregistre sans cookies. Ajoutez le résultat de la restauration au runbook avant l’arrivée des vrais utilisateurs.

Foire aux questions

De quoi Fathom Lite a-t-il besoin pour un déploiement en production ?

Acheminez le container Fathom Lite sur le port 8080 via une origine HTTPS unique. La configuration réseau requise repose sur SQLite ou une base de données externe prise en charge, ainsi que sur le placement correct du script côté site client. Ne considérez pas Fathom Lite comme prêt tant que vous ne pouvez pas ajouter un site, charger le script de suivi sur une page de test, générer des visites et vérifier que le dashboard les enregistre sans cookies.

Quelles données Fathom Lite doivent figurer dans une sauvegarde ?

Rendez /app persistant et incluez la base de données d’analytics, la configuration des sites et l’état de l’administrateur dans le même manifest de récupération. Une restauration Fathom Lite propre ne réussit que si les sites, les utilisateurs et l’historique des pages vues sont restaurés et qu’une nouvelle visite de test apparaît après la récupération.

Fathom Lite nécessite-t-il HTTPS derrière un reverse proxy ?

Utilisez HTTPS pour l’origine publique de Fathom Lite et conservez le port 8080 sur la route interne. Appliquez correctement le paramètre Fathom Lite : configurez l’adresse du serveur et l’endpoint HTTPS public utilisé par le script de suivi. Pour Fathom Lite, HTTPS protège les identifiants ou le contenu utilisateur pendant leur transport et garantit un comportement cohérent des clients dépendant de l’origine.

Comment tester une mise à niveau de Fathom Lite ?

Restaurez l’état actuel de Fathom Lite dans un déploiement isolé, appliquez la version candidate et répétez sa transaction d’acceptation. Soyez particulièrement attentif, car le schéma de base de données de Fathom et le script de suivi doivent être testés ensemble pour éviter de perdre silencieusement des événements. Conservez l’ancienne image Fathom Lite jusqu’à ce que les limites de migration des données et de rollback soient bien comprises.