Como fazer self-host do Fathom Lite em 2026: script de tracking, SQLite e privacidade

Há duas versões de “executar o Fathom Lite”: existe um container ou o serviço cumpre sua função de fato. Apenas a segunda importa. Aqui, a comprovação consiste em adicionar um site, carregar o script de tracking em uma página de teste, gerar visitas e confirmar que o dashboard as registra sem cookies.

O Fathom Lite serve para isso: analytics de page views sem cookies e com self-hosting. A implantação precisa preservar os componentes por trás desse comportamento; uma porta, um volume e um certificado são insumos, não o resultado.

Credenciais, funções e superfícies expostas

No Fathom Lite, a superfície valiosa não é necessariamente a landing page. O principal erro é reutilizar um secret de exemplo ou expor o login de administrador sem TLS. Evite isso deliberadamente: proteja o login do analytics, mantenha o secret da aplicação estável e publique o script somente pelo host HTTPS esperado.

Trate FATHOM_SECRET de acordo com sua função no Fathom Lite: mantenha valores sensíveis fora do Git, documente os efeitos da rotação e nunca substitua um exemplo público em produção. Use um usuário de container sem privilégios quando a imagem oferecer suporte e não monte credenciais que não tenham relação com o serviço. Aplique limites de taxa ou de tamanho no ingress, onde trabalho não confiável pode consumir a taxa de gravação de page views, índices do banco de dados, retenção e o caminho de rede entre os browsers dos visitantes.

Separe o Fathom Lite das dependências

A topologia mínima e responsável do Fathom Lite contém um único listener privado na porta 8080, uma rota de ingress e um limite de estado documentado. O contrato de rede do Fathom Lite é o SQLite ou um banco de dados externo compatível, além do posicionamento correto do script no site cliente. Mantenha endpoints privados em DNS interno, permita somente as chamadas de saída necessárias e forneça ao Fathom Lite uma credencial de serviço com escopo limitado.

Valide a topologia pedindo a um cliente limpo que adicione um site, carregue o script de tracking em uma página de teste, gere visitas e confirme que o dashboard as registra sem cookies. Monitore a taxa de gravação de page views, os índices do banco de dados, a retenção e o caminho de rede entre os browsers dos visitantes durante a execução. O resultado indicará se a próxima melhoria deve ser feita em memória, armazenamento, rede ou em um worker separado, em vez de incentivar um dimensionamento arbitrário do container.

Uma configuração básica do Fathom Lite com Docker

Um comando mínimo é útil quando revela o que a plataforma gerenciará posteriormente.

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

Aqui, a porta 8080 permanece privada no host e todos os caminhos necessários são explícitos. Adicione as configurações de conexão revisadas para SQLite ou um banco de dados externo compatível, além do posicionamento correto do script no site cliente; use nomes privados para serviços privados. Verifique a inicialização tanto pelos logs quanto pela comprovação específica da aplicação: adicione um site, carregue o script de tracking em uma página de teste, gere visitas e confirme que o dashboard as registra sem cookies. Depois de verificar, fixe a versão da imagem para que uma substituição de rotina não altere o comportamento silenciosamente.

Comprove a implantação do Fathom Lite de ponta a ponta

Crie um fixture pequeno e descartável do Fathom Lite e mantenha-o para cada release. O fixture deve exercitar o workflow real: adicionar um site, carregar o script de tracking em uma página de teste, gerar visitas e confirmar que o dashboard as registra sem cookies. Registre o digest da imagem, o hostname externo, o endereço da dependência e o resultado esperado para que outro operador possa repetir o teste posteriormente sem precisar interpretar este guia.

Execute o fixture três vezes. Primeiro, use a implantação nova. Depois, substitua o container sem alterar o estado persistente. Por fim, restaure o backup em um ambiente vazio. A terceira execução só será bem-sucedida quando sites, usuários e page views históricos retornarem e uma nova visita de teste aparecer após a recuperação. Durante cada execução, capture a latência e o uso de recursos relacionados à taxa de gravação de page views, aos índices do banco de dados, à retenção e ao caminho de rede entre os browsers dos visitantes; isso se tornará a baseline dos alertas, em vez de uma porcentagem arbitrária de CPU.

Por fim, teste deliberadamente o caminho negativo: negue temporariamente à identidade de teste o acesso ao SQLite ou a um banco de dados externo compatível e ao posicionamento correto do script no site cliente. Confirme que o Fathom Lite falha de forma visível sem corromper o estado, restaure a condição correta e repita a transação bem-sucedida. Um registro de release contendo esses quatro resultados é uma evidência mais forte do que screenshots de um dashboard ou uma resposta única de curl.

Mantenha as URLs internas e externas organizadas

O limite público do Fathom Lite deve ser um único hostname canônico, TLS automático e um único destino interno na porta 8080. Configure o endereço do servidor e o endpoint HTTPS público usado pelo script de tracking para que os clientes retornem a um endereço reconhecido pelo serviço.

Se a transação de aceitação falhar, classifique o primeiro erro. Problemas de DNS, certificado e 502 pertencem ao checklist de validação de TLS. A condição “o script de tracking aponta para o hostname errado ou o caminho do banco de dados é efêmero” pertence ao lado da aplicação, depois que uma requisição chega corretamente ao Fathom Lite.

Simulações de falhas do Fathom Lite

Os testes de capacidade devem exercitar a taxa de gravação de page views, os índices do banco de dados, a retenção e o caminho de rede entre os browsers dos visitantes, e não uma requisição repetida a /. Execute o cenário “adicionar um site, carregar o script de tracking em uma página de teste, gerar visitas e confirmar que o dashboard as registra sem cookies” com concorrência realista e registre a latência, a taxa de erros e o crescimento do armazenamento.

O planejamento de upgrades precisa considerar este risco: o schema do banco de dados do Fathom e o script de tracking devem ser testados em conjunto para evitar a perda silenciosa de eventos. Teste a nova release com dados representativos, repita a transação de aceitação e compare o resultado. Se o script de tracking apontar para o hostname errado ou o caminho do banco de dados for efêmero, capture a transação com falha e inspecione o primeiro limite envolvido, em vez de presumir que o ingress é responsável.

Comprove que o Fathom Lite sobrevive à substituição

Uma imagem de container pode ser baixada novamente; o banco de dados de analytics, a configuração dos sites e o estado do administrador, não. Monte /app antes do bootstrap, grave dados de exemplo inofensivos e substitua o container para comprovar que esse caminho é realmente persistente. Inspecione o mount efetivo em vez de confiar no nome de um arquivo do Compose e verifique se o usuário de runtime consegue gravar onde o Fathom Lite espera.

Defina a retenção e um destino fora do host, depois ensaie a recuperação sem tocar na produção. A simulação só será aprovada quando sites, usuários e page views históricos retornarem e uma nova visita de teste aparecer após a recuperação. Para estados baseados em banco de dados, combine snapshots de armazenamento com exports consistentes com a aplicação, conforme descrito em recuperação point-in-time versus snapshots.

Conecte o Fathom Lite ao ciclo de vida do Dockup

A implantação do Fathom Lite em um clique no Dockup deve tornar a substituição segura: a rota continua apontando para a porta 8080, os secrets não são incorporados à imagem e os caminhos persistentes retornam no novo container. A mesma implantação pode ser executada no compute do Dockup ou em uma máquina conectada.

Conclua o trabalho específico da aplicação conectando e testando o SQLite ou um banco de dados externo compatível e o posicionamento correto do script no site cliente, aplicando o endereço público canônico e executando esta verificação de aceitação: adicione um site, carregue o script de tracking em uma página de teste, gere visitas e confirme que o dashboard as registra sem cookies. Adicione o resultado da restauração ao runbook antes da chegada dos usuários reais.

Perguntas frequentes

Do que o Fathom Lite precisa para uma implantação em produção?

Direcione o container do Fathom Lite na porta 8080 por uma única origem HTTPS. O requisito de rede de suporte é o SQLite ou um banco de dados externo compatível, além do posicionamento correto do script no site cliente. Não considere o Fathom Lite pronto até conseguir adicionar um site, carregar o script de tracking em uma página de teste, gerar visitas e confirmar que o dashboard as registra sem cookies.

Quais dados do Fathom Lite devem fazer parte de um backup?

Persista /app e inclua o banco de dados de analytics, a configuração dos sites e o estado do administrador no mesmo manifesto de recuperação. Uma restauração limpa do Fathom Lite só será aprovada quando sites, usuários e page views históricos retornarem e uma nova visita de teste aparecer após a recuperação.

O Fathom Lite exige HTTPS atrás de um reverse proxy?

Use HTTPS para a origem pública do Fathom Lite e mantenha a porta 8080 na rota interna. Aplique corretamente a configuração do Fathom Lite: defina o endereço do servidor e o endpoint HTTPS público usado pelo script de tracking. No Fathom Lite, o HTTPS protege credenciais ou conteúdo de usuários em trânsito e mantém consistente o comportamento do cliente sensível à origem.

Como um upgrade do Fathom Lite deve ser testado?

Restaure o estado atual do Fathom Lite em uma implantação isolada, aplique a versão candidata e repita sua transação de aceitação. Preste atenção especial, pois o schema do banco de dados do Fathom e o script de tracking devem ser testados em conjunto para evitar a perda silenciosa de eventos. Mantenha a imagem anterior do Fathom Lite até entender os limites de migração de dados e rollback.