docker-compose-cookbooks/posthog_dev/README.md

PostHog

Overview

PostHog is a self-hosted product analytics platform offering event tracking, session recording, feature flags, and experimentation. This Docker Compose stack deploys PostHog with PostgreSQL, Redis, ClickHouse, and Kafka.

Note: PostHog is resource-intensive. Minimum 4GB RAM, 8GB+ recommended.

Project Details

• Project Repository: PostHog
• Container Image: Docker Hub
• Compose Example: Official Hobby Compose
• Documentation: Self-Host Docs
• Reverse Proxy Port: 8000

Getting Started

1. Copy sample.env to .env and edit all values (especially POSTHOG_SECRET_KEY)
2. Start the stack: docker compose up -d (first startup will run migrations — this can take several minutes)
3. Open http://localhost:8000 in your browser
4. Create your admin account on first visit

Environment Variable Notes

Compose

• VOL_PATH – base path for persistent data (default: /data)
• POSTHOG_IMAGE – image tag (default: posthog/posthog:latest)
• POSTHOG_RESTART – restart policy (default: unless-stopped)

Core

• POSTHOG_SITE_URL – public URL of your PostHog instance (required)
• POSTHOG_SECRET_KEY – Django secret key for session encryption (required, set to a long random string)

Database

• POSTHOG_DB_NAME – PostgreSQL database name (default: posthog)
• POSTHOG_DB_USER – PostgreSQL user (default: posthog)
• POSTHOG_DB_PASSWORD – PostgreSQL password (required)

ClickHouse

• POSTHOG_CLICKHOUSE_DB – ClickHouse database name (default: posthog)
• POSTHOG_CLICKHOUSE_USER – ClickHouse user (default: clickhouse)
• POSTHOG_CLICKHOUSE_PASSWORD – ClickHouse password (required)

Email (optional)

• POSTHOG_EMAIL_HOST – SMTP server host
• POSTHOG_EMAIL_USER – SMTP username
• POSTHOG_EMAIL_PASSWORD – SMTP password
• POSTHOG_EMAIL_PORT – SMTP port (default: 587)
• POSTHOG_EMAIL_TLS – enable TLS (default: true)

Volume Notes

• ${VOL_PATH:-/data}/posthog/postgres – PostgreSQL data
• ${VOL_PATH:-/data}/posthog/redis – Redis data
• ${VOL_PATH:-/data}/posthog/clickhouse – ClickHouse analytics data
• ${VOL_PATH:-/data}/posthog/kafka – Kafka message queue data
• ${VOL_PATH:-/data}/posthog/data – PostHog app data (uploads, exports)
• ${VOL_PATH:-/data}/posthog/logs – application logs

Network Notes

• Requires the external proxy network for reverse proxy access.
• All backend services communicate over the internal network.

Docker Run

PostHog requires multiple interdependent services. Use the Docker Compose stack rather than individual docker run commands.

Additional Notes / Gotchas

• Resource heavy. PostHog needs at least 4GB RAM and 10GB disk. ClickHouse and Kafka are memory-intensive.
• First startup is slow. Migrations run on initial deploy and can take 5–10 minutes. Check logs with docker compose logs -f posthog.
• SECRET_KEY must be set. Generate one with openssl rand -hex 32 and set it in .env.
• Kafka runs without authentication on the internal network only.
• This is a simplified dev deployment. For production, see the official hobby compose which includes additional services (plugins, ingestion pipelines, object storage, etc.).
• Port 8000 is the internal web port. Proxy it through Nginx Proxy Manager on the proxy network.

Dockhand Stack, Deploy from Git

Cookbooks Repository stackname: posthog Compose file path: posthog_dev/compose.yaml Additional env file (optional): posthog_dev/sample.env

Then "Load" posthog_dev/sample.env into the Environmental variables in dockhand

Create the Stack