O que é PostHog e por que hospedar localmente?
No cenário atual de privacidade de dados, muitas empresas estão migrando de soluções SaaS tradicionais para infraestruturas product analytics self-hosted. O PostHog se destaca como uma plataforma completa de análise de produto, oferecendo funcionalidades que vão desde o rastreamento de eventos até funis, retenção e gravações de sessão (session replay), tudo em um único painel unificado.
Diferente do Plausible ou Matomo, que focam predominantemente em métricas de tráfego e conformidade com LGPD/GDPR sem entrar profundamente na jornada do usuário dentro da aplicação, o PostHog permite uma análise comportamental granular. Ao optar por um analytics vps, você mantém o controle total sobre seus dados, evita vazamentos de PII (Informações Pessoais Identificáveis) e reduz custos em escala, especialmente quando o volume de eventos cresce exponencialmente.
Neste tutorial, vamos guiar você através da instalação completa do PostHog em um servidor Linux. Utilizaremos a stack oficial baseada em Docker Compose, que é a maneira recomendada pela comunidade para ambientes self-hosted, garantindo estabilidade e facilidade de manutenção.
Pré-requisitos de Infraestrutura
Antes de iniciar o processo de install posthog linux, é fundamental preparar o ambiente. O PostHog é uma aplicação pesada que consome recursos significativos, especialmente durante a indexação de dados e execução de queries analíticas.
Especificações Recomendadas
Para um ambiente de produção estável ou desenvolvimento sério, recomendamos:
- CPU: Mínimo de 4 vCPUs. O processo de ingestão e agregação é intensivo em processamento.
- RAM: 16 GB são o padrão mínimo confortável. Menos que isso resultará em instabilidade do PostgreSQL e Kafka.
- Armazenamento: SSD NVMe é altamente recomendado para I/O de banco de dados. Comece com pelo menos 40 GB, expandindo conforme a retenção de dados aumentar.
Sistema Operacional
O tutorial assume o uso de uma distribuição baseada em Debian/Ubuntu (como Ubuntu 22.04 LTS ou 24.04 LTS), que é o ambiente mais testado e documentado pela equipe do PostHog.
Passo 1: Preparação do Servidor Linux
A primeira etapa envolve atualizar o sistema operacional e instalar as dependências básicas necessárias para gerenciar containers e repositórios Git.
Acesse seu servidor via SSH e execute os comandos abaixo com privilégios de root ou sudo:
sudo apt update && sudo apt upgrade -y
sudo apt install curl git unzip -yEm seguida, vamos instalar o Docker Engine. A maneira mais limpa é usar o repositório oficial da Docker:
curl -fsSL https://get.docker.com -o get-docker.sh
sudo sh get-docker.sh
sudo usermod -aG docker $USERApós a instalação, execute o comando abaixo para garantir que o serviço Docker está ativo e configurado para iniciar com o boot do sistema:
sudo systemctl enable --now dockerAgora, instale o Docker Compose V2 (que é um plugin binário moderno e mais rápido que a versão antiga via pip):
sudo apt install docker-compose-plugin -y
docker compose versionPasso 2: Configuração do Ambiente e Variáveis de Segurança
O PostHog requer diversas variáveis de ambiente para configurar o banco de dados, filas de mensagens (Kafka) e a aplicação principal. Criar um arquivo de variáveis dedicado facilita atualizações futuras.
Crie um diretório para sua instalação:
mkdir -p ~/posthog && cd ~/posthogCrie o arquivo .env que conterá as configurações sensíveis. É crucial definir uma senha forte para o banco de dados e um segredo de assinatura.
nano .envDentro do arquivo, insira o seguinte conteúdo (ajuste os valores conforme necessário):
# Configurações do Banco de Dados
POSTHOG_DB_NAME=posthogdb
POSTHOG_DB_USER=posthoguser
POSTHOG_DB_PASSWORD=SenhaMuitoForte123!
DATABASE_URL=postgres://posthoguser:SenhaMuitoForte123!@localhost:5432/posthogdb
# Segredos da Aplicação
SECRET_KEY=UmaChaveAleatoriaComplexaGeradaPeloPython
POSTHOG_LICENSE_DATA={} # Deixe vazio se não tiver licença paga
# Configurações de Email (Opcional para envio real, mas necessário para configuração)
EMAIL_URL=smtp://localhost:1025
DASHBOARD_COLLABORATION_ENABLED=true
# Modo de Deploy
DEPLOY_ENV=production
Dica de Segurança: Nunca compartilhe o arquivo .env. Se estiver usando Git, adicione-o ao seu .gitignore.
Passo 3: Instalação do PostHog via Docker Compose
O PostHog disponibiliza um docker-compose.yml oficial que orquestra todos os microsserviços necessários: PostgreSQL, Kafka, Zookeeper, Redis, ClickHouse e a aplicação web.
Baixe o arquivo de configuração direto do repositório oficial:
wget https://raw.githubusercontent.com/PostHog/posthog/master/docker-compose.ymlAgora, vamos iniciar os containers. Este processo pode levar alguns minutos na primeira execução, pois ele baixa as imagens e executa as migrações de banco de dados.
docker compose up -d --buildO flag --build garante que você esteja usando a versão mais recente dos containers. Se quiser apenas iniciar sem reconstruir, use docker compose up -d.
Verificando o Status
Acompanhe os logs para garantir que não há erros críticos:
docker compose logs -f posthogSe você vir mensagens indicando que o servidor web está rodando e conectado ao banco de dados, a instalação foi bem-sucedida. O PostHog estará disponível na porta 8000 do seu servidor.
Passo 4: Configuração de Acesso e Primeiro Login
Por padrão, o PostHog expõe a interface web na porta 8000. Se você estiver testando localmente, acesse http://localhost:8000. Para produção, é necessário configurar um proxy reverso (Nginx ou Caddy) para expor a aplicação na porta 80/443 com SSL.
Crie uma conta de superusuário (Superuser) para acessar o painel administrativo:
docker compose exec posthog python manage.py createsuperuserSiga as instruções no terminal para definir nome de usuário, email e senha. Após a criação, acesse o painel em http://SEU_IP:8000/login/ e faça login.
Passo 5: Integração com o Frontend (Captura de Dados)
Agora que a infraestrutura está pronta, precisamos configurar o frontend do seu site ou aplicação para enviar dados ao PostHog hospedado. Isso substitui o script padrão do PostHog SaaS.
No código HTML da sua aplicação, substitua o snippet padrão pelo seguinte, ajustando o api_host:
<script>
!function(t,e){var o,n,p,r;e.__SV||(window.posthog=e,e._i=[],e.init=function(i,s,a){function g(t,e){var o=e.split(".");2==o.length&&(t=t[o[0]],e=o[1]),t[e]=function(){t.push([e].concat(Array.prototype.slice.call(arguments,0)))}}(p=t.createElement("script")).type="text/javascript",p.async=!0,p.src=s.api_host+"/static/array.js",(r=t.getElementsByTagName("script")[0]).parentNode.insertBefore(p,r);var u=e;for(void 0!==a?u=e[a]=[]:a="posthog",u.people=u.people||[],u.toString=function(t){var e="posthog";return"posthog"!==u&&(e+="."+u),t||(e+=" (stub)"),e},u.people.toString=function(){return u.toString(1)+".people (stub)"},o="capture identify alias people.set people.set_once set_config register register_once unregister opt_out_capturing has_opted_out_capturing opt_in_capturing reset isFeatureEnabled on_pageleave killExperimentCallback load".split(" "),n=0;n<o.length;n++)g(u,o[n]);e._i.push([i,s,a])},e.__SV=1)}(document,window.posthog||[]);
posthog.init('PUBLIC_API_KEY_AQUI', {
api_host: 'http://SEU_IP:8000'
})
</script>Importante: A PUBLIC_API_KEY pode ser gerada no painel do PostHog, em "Project Settings" > "Project Tokens". Use o token padrão do projeto.
Passo 6: Monitoramento com Grafana e Prometheus
Para manter a saúde do seu grafana dashboard vps, é essencial monitorar os recursos utilizados pelo PostHog. O PostHog expõe métricas de infraestrutura que podem ser consumidas pelo Prometheus.
Adicione o Prometheus e o Grafana ao seu projeto. Uma maneira simples é estender o docker-compose.yml ou criar um arquivo separado para monitoramento.
Crie um arquivo prometheus.yml:
global:
scrape_interval: 15s
scrape_configs:
- job_name: 'posthog'
static_configs:
- targets: ['posthog:8000'] # Ajuste conforme a porta de métricas exposta
No painel do Grafana, importe o dashboard oficial do PostHog (ID: 12748 ou busque por "PostHog" na biblioteca). Isso permitirá visualizar QPS (Queries por segundo), latência de ingestão e uso de memória dos containers.
Passo 7: Backup e Manutenção
A persistência de dados é crítica. O PostHog armazena eventos em tempo real que, se perdidos, não podem ser recuperados facilmente. Configure backups automáticos do PostgreSQL e do diretório de volumes.
Backup do Banco de Dados
Crie um script simples para fazer dump diário do banco:
#!/bin/bash
BACKUP_DIR="/backups/posthog"
DATE=$(date +%F)
mkdir -p $BACKUP_DIR
docker compose exec postgres pg_dump -U posthoguser posthogdb > $BACKUP_DIR/posthog_$DATE.sql.gz
# Mantenha apenas os últimos 7 dias
find $BACKUP_DIR -name "posthog_*.sql.gz" -mtime +7 -deleteAdicione esta tarefa ao crontab do servidor:
crontab -e
0 2 * * * /root/scripts/posthog-backup.shAtualizações
Para atualizar o PostHog, basta rodar:
docker compose pull
docker compose up -d --buildSempre verifique a documentação oficial antes de grandes atualizações de versão, pois podem haver mudanças nas variáveis de ambiente.
Conclusão: Por que escolher esta abordagem?
Hospedar o PostHog em sua própria VPS oferece uma vantagem competitiva significativa. Você obtém um product analytics self-hosted robusto, sem limites de eventos pagos e com total soberania sobre os dados. Embora a configuração inicial exija conhecimento técnico superior ao uso de ferramentas SaaS simples como o Plausible ou até mesmo o Matomo em modo simplificado, o retorno em flexibilidade e profundidade analítica é incomparável.
A combinação de data privacy tools locais com a capacidade de criar dashboards customizados no Grafana transforma seu servidor em um centro de inteligência real. Lembre-se sempre de monitorar o uso de disco, pois os eventos podem crescer rapidamente; planeje a escalabilidade do armazenamento desde o início.
Agora que você tem o sistema rodando, explore as funcionalidades de session replay e cohorting para entender melhor seu usuário. A análise de dados não precisa ser uma caixa preta; com o PostHog self-hosted, ela se torna um ativo transparente e controlado.
