Como instalar o PostHog em uma VPS

Pré-requisitos

A auto-hospedagem do PostHog não é uma demonstração com dois contêineres. O conjunto de serviços executa cerca de 10 contêineres (PostgreSQL, ClickHouse, Kafka, Zookeeper, Redis, MinIO, Caddy e outros). Os requisitos mínimos oficiais são 4 vCPU, 16 GB de RAM e mais de 30 GB de disco. Use Ubuntu 22.04 ou 24.04, IP público, SSH e um domínio dedicado, como posthog.example.com.

Espere administrar o armazenamento do banco de dados, o armazenamento de objetos, os processos de trabalho em segundo plano, as atualizações e os backups. Um servidor temporário de avaliação é útil para aprender, mas a análise de dados em produção exige armazenamento monitorado e um plano de recuperação.

Etapa 1, conectando-se ao servidor

Conecte-se e aplique as atualizações ao servidor:

ssh root@SERVER_IP
apt update && apt upgrade -y
apt install -y ca-certificates curl git
mkdir -p /opt/posthog
cd /opt/posthog
chmod 750 /opt/posthog

Mantenha as portas 80 e 443 disponíveis para o proxy. Não instale neste servidor um banco de dados ou serviço de fila sem relação com o PostHog, a menos que a documentação do PostHog dê suporte explícito a essa configuração.

Etapa 2, instalando o Docker e o Docker Compose

Instale o Docker Engine e o plugin Compose seguindo as instruções oficiais do Docker para Ubuntu. Confira o ambiente de execução e os limites de recursos:

docker --version
docker compose version
docker system df
systemctl enable --now docker

Não execute um comando docker run inventado para o PostHog. O aplicativo depende de um conjunto coordenado de serviços e variáveis de ambiente.

Etapa 3, executando o instalador Hobby oficial do PostHog

O PostHog recomenda seu instalador Hobby de uma linha para implantações auto-hospedadas (o Helm foi descontinuado e arquivos Compose escritos manualmente não têm suporte). Execute-o como root a partir de /opt/posthog:

curl -fsSL https://posthog.com/deploy-hobby | bash

O instalador solicita o nome do domínio, obtém a definição Compose, gera segredos, cria o arquivo .env e inicia o conjunto de serviços. A primeira inicialização leva vários minutos enquanto os bancos de dados são migrados e as imagens são baixadas.

Variáveis de ambiente necessárias

Defina estes valores no arquivo de ambiente criado pelo instalador antes de iniciar o conjunto de serviços (ou edite-o depois e reinicie):

Variável	Descrição	Como gerar
SECRET_KEY	Segredo criptográfico do Django	openssl rand -hex 32
SITE_URL	URL completa da sua instância do PostHog	https://posthog.example.com
IS_BEHIND_PROXY	Defina como True se estiver atrás do seu próprio proxy reverso	True
TRUSTED_PROXIES	Faixa CIDR dos proxies confiáveis	0.0.0.0/0

SECRET_KEY é obrigatório para o aplicativo Django. SITE_URL precisa ser a URL pública completa, incluindo o protocolo. IS_BEHIND_PROXY=True e TRUSTED_PROXIES=0.0.0.0/0 são necessários quando você coloca seu próprio Nginx ou Traefik na frente do proxy Caddy incluído.

Aviso: O PostHog auto-hospedado não tem suporte oficial, não há cobertura de CVEs nem recuperação de perda de dados. Os recursos pagos e o suporte empresarial estão disponíveis somente na nuvem.

Etapa 4, configurando o proxy reverso

O instalador Hobby inclui o Caddy com TLS automático. Por padrão, o Caddy escuta nas portas 80 e 443 e provisiona certificados do Let's Encrypt automaticamente. Essa é a configuração recomendada para a maioria das pessoas.

Se você colocar seu próprio Nginx ou Traefik na frente, DEVE definir IS_BEHIND_PROXY=True e TRUSTED_PROXIES=0.0.0.0/0 no arquivo de ambiente. Seu proxy precisa encaminhar corretamente os cabeçalhos X-Forwarded-For e X-Forwarded-Proto, caso contrário o PostHog entrará em loops de redirecionamento.

Encaminhe posthog.example.com para o serviço web público do conjunto, nunca para um banco de dados ou processo de trabalho interno. Encerre o HTTPS, preserve o WebSocket e os cabeçalhos do protocolo encaminhado quando necessário e mantenha as portas internas privadas.

Permita somente SSH, 80 e 443 no firewall público. Confirme que o domínio resolve para a VPS e que o certificado cobre exatamente o nome do domínio. Teste o endpoint de integridade e a interface do navegador por HTTPS antes de adicionar um SDK de produção.

Etapa 5, primeiro acesso e configuração inicial

Acesse https://posthog.example.com, crie a primeira organização e a conta de administrador e altere todos os valores temporários. Crie um projeto de teste, configure o SDK com uma chave de teste que não seja de produção e envie um evento de um ambiente descartável.

Confirme que o evento aparece, que os horários usam o fuso esperado e que os controles de ativação de funcionalidades funcionam conforme documentado. Revise a retenção de dados, as permissões dos usuários e as configurações de privacidade antes de convidar o restante da equipe.

Manutenção

Siga as notas de versão e o procedimento de atualização do PostHog. Faça backup de todos os armazenamentos persistentes exigidos pelo conjunto atual de serviços, incluindo o armazenamento de objetos e os segredos. Teste uma restauração antes de atualizar e mantenha espaço em disco suficiente para migrações e imagens temporárias.

Monitore CPU, memória, profundidade da fila, integridade do banco de dados, armazenamento de objetos e ingestão de eventos. Se um componente não estiver saudável, colete os logs dele e o status do projeto Compose antes de reiniciar. Para cargas de trabalho de produção maiores, compare o custo operacional da auto-hospedagem com a opção gerenciada antes de se comprometer com essa arquitetura.