Cómo instalar PostHog en un VPS

Requisitos previos

PostHog autoalojado no es una demo de dos contenedores. Su stack ejecuta unos 10 contenedores (PostgreSQL, ClickHouse, Kafka, Zookeeper, Redis, MinIO, Caddy y otros). Los mínimos oficiales son 4 vCPU, 16 GB RAM, 30+ GB disco. Usa Ubuntu 22.04 o 24.04, IP pública, SSH y un dominio dedicado como posthog.example.com.

Tendrás que gestionar almacenamiento de bases de datos, object storage, workers, upgrades y backups. Un servidor desechable sirve para aprender, pero la analítica de producción necesita monitorización y un plan de recuperación.

Paso 1, Conectarte a tu servidor

Conéctate y actualiza el host:

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

Deja libres 80 y 443 para el proxy. No instales otra base de datos o cola salvo que la documentación del despliegue lo permita explícitamente.

Paso 2, Instalar Docker y Docker Compose

Instala Docker Engine y Compose desde las instrucciones oficiales para Ubuntu. Comprueba el runtime y el consumo inicial:

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

No uses un docker run inventado para PostHog. La aplicación depende de servicios coordinados y variables relacionadas.

Paso 3, Ejecutar el instalador Hobby oficial de PostHog

PostHog recomienda su instalador Hobby de una línea para despliegues autoalojados (Helm está obsoleto y los archivos Compose escritos a mano no tienen soporte). Ejecútalo como root desde /opt/posthog:

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

El instalador pide el hostname, descarga la definición Compose, genera secretos, crea el archivo .env e inicia el stack. El primer arranque tarda varios minutos mientras las bases de datos migran y las imágenes se descargan.

Variables de entorno requeridas

Establece estos valores en el archivo de entorno creado por el instalador (edítalo antes de iniciar el stack si necesitas un despliegue no interactivo):

Variable	Descripción	Cómo generar
SECRET_KEY	Secreto criptográfico de Django	openssl rand -hex 32
SITE_URL	URL completa de tu instancia PostHog	https://posthog.example.com
IS_BEHIND_PROXY	True si usas tu propio proxy inverso	True
TRUSTED_PROXIES	Rango CIDR de proxies de confianza	0.0.0.0/0

SECRET_KEY es obligatorio para la aplicación Django. SITE_URL debe ser la URL pública completa con protocolo. IS_BEHIND_PROXY=True y TRUSTED_PROXIES=0.0.0.0/0 son necesarios cuando pones Nginx o Traefik delante del proxy Caddy incluido.

Aviso: PostHog autoalojado no tiene soporte oficial — no hay cobertura de CVE ni recuperación ante pérdida de datos. Las funcionalidades de pago y el soporte empresarial son solo Cloud.

Paso 4, Configurar el proxy inverso

El instalador Hobby incluye Caddy con auto-TLS. Por defecto Caddy escucha en los puertos 80 y 443 y obtiene certificados Let's Encrypt automáticamente. Esta es la configuración recomendada para la mayoría de usuarios.

Si colocas tu propio Nginx o Traefik delante, DEBES establecer IS_BEHIND_PROXY=True y TRUSTED_PROXIES=0.0.0.0/0 en el archivo de entorno. Tu proxy debe reenviar las cabeceras X-Forwarded-For y X-Forwarded-Proto correctamente, o PostHog producirá bucles de redirección.

Envía posthog.example.com al servicio web público del stack, nunca a una base de datos o worker interno. Termina HTTPS, conserva WebSocket y las cabeceras de protocolo reenviadas cuando hagan falta y mantén privados los puertos internos.

En el firewall público permite solo SSH, 80 y 443. Confirma que el dominio resuelve al VPS y que el certificado cubre exactamente el hostname. Prueba la interfaz por HTTPS antes de conectar un SDK de producción.

Paso 5, Primer acceso y configuración inicial

Abre https://posthog.example.com, crea la organización y el administrador y cambia los valores temporales. Crea un proyecto de prueba, configura el SDK con una clave de test y envía un evento desde un entorno desechable.

Comprueba que el evento aparece, que la zona horaria es la esperada y que los feature flags se evalúan correctamente. Revisa retención, permisos y privacidad antes de invitar al equipo.

Mantenimiento

Sigue las notas de versión y el procedimiento de actualización de PostHog. Haz backup de todos los stores persistentes, incluidos object storage y secretos. Prueba una restauración antes de actualizar y conserva disco libre para migraciones e imágenes temporales.

Monitoriza CPU, memoria, colas, base de datos, object storage y llegada de eventos. Si un componente falla, guarda sus logs y el estado del proyecto Compose antes de reiniciar. Para cargas serias, compara el coste operativo con la opción gestionada antes de fijar la arquitectura.