Local Development Setup

This guide walks you through setting up PostHog for local development. You’ll be able to run the full stack including Django, React, PostgreSQL, ClickHouse, and Redis.

Prerequisites

System Requirements

macOS or Linux (Windows via WSL2)
16GB RAM minimum (32GB recommended)
20GB free disk space
Docker Desktop (for infrastructure services)

Required Tools

Install these tools before proceeding:

Git - Version control
Docker - For PostgreSQL, ClickHouse, Redis
Node.js 18+ - Frontend tooling
Python 3.11+ - Backend runtime
pnpm - Package manager

Quick Start

The fastest way to get started is using the automated setup:

# Clone the repository
git clone https://github.com/PostHog/posthog.git
cd posthog

# Start infrastructure services (PostgreSQL, ClickHouse, Redis)
docker compose -f docker-compose.dev.yml up -d

# Install dependencies
pnpm install
pip install -r requirements.txt

# Run database migrations
python manage.py migrate
python manage.py migrate_clickhouse

# Start the development server
./bin/start

The ./bin/start script uses mprocs to run all services in parallel. It will automatically install mprocs via Homebrew if not present.

PostHog will be available at:

Frontend: http://localhost:8000
API: http://localhost:8000/api
Dagster (data pipeline): http://localhost:3030

Detailed Setup

1. Environment Setup

Option A: Using Flox (Recommended)

Flox provides a reproducible development environment:

# Install flox (if not already installed)
curl -fsSL https://downloads.flox.dev/by-env/stable/install.sh | bash

# Activate the environment
cd posthog
flox activate

This automatically installs:

Python 3.11 with required packages
Node.js and pnpm
PostgreSQL and ClickHouse clients
All development tools

Option B: Manual Setup

If not using Flox, install dependencies manually:

# Install Homebrew
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

# Install dependencies
brew install python@3.11 node@18 pnpm postgresql clickhouse

# Install Python packages
pip install uv
uv pip install -r requirements.txt

# Install system dependencies
sudo apt update
sudo apt install python3.11 python3.11-dev nodejs npm postgresql-client

# Install pnpm
npm install -g pnpm

# Install Python packages
pip install -r requirements.txt

2. Infrastructure Services

Start PostgreSQL, ClickHouse, and Redis using Docker:

# Start all services
docker compose -f docker-compose.dev.yml up -d

# Check service status
docker compose -f docker-compose.dev.yml ps

# View logs
docker compose -f docker-compose.dev.yml logs -f

Services started:

PostgreSQL on localhost:5432
ClickHouse on localhost:9000 (HTTP: 8123)
Redis on localhost:6379
Kafka on localhost:9092 (for event ingestion)
Object Storage (MinIO) on localhost:19000

If ports are already in use, you can modify them in docker-compose.dev.yml.

3. Database Setup

Initialize both PostgreSQL and ClickHouse:

Create PostgreSQL database

# Create database (first time only)
python manage.py migrate

# Create superuser
python manage.py createsuperuser

Initialize ClickHouse

# Run ClickHouse migrations
python manage.py migrate_clickhouse

Load test data (optional)

# Create demo team and data
python manage.py setup_dev

4. Environment Variables

Create a .env file for local configuration:

# Copy example config
cp .env.example .env

Key environment variables:

# .env
DEBUG=1
SECRET_KEY=your-secret-key-here

# Database
DATABASE_URL=postgres://posthog:posthog@localhost:5432/posthog

# ClickHouse
CLICKHOUSE_HOST=localhost
CLICKHOUSE_DATABASE=posthog
CLICKHOUSE_USER=default
CLICKHOUSE_PASSWORD=

# Redis
REDIS_URL=redis://localhost:6379/

# Object Storage
OBJECT_STORAGE_ENABLED=True
OBJECT_STORAGE_ENDPOINT=http://localhost:19000
OBJECT_STORAGE_ACCESS_KEY_ID=object_storage_root_user
OBJECT_STORAGE_SECRET_ACCESS_KEY=object_storage_root_password

5. Frontend Setup

Install and build frontend assets:

# Install dependencies
pnpm install

# Build once
pnpm --filter=@posthog/frontend build

# Or run in watch mode
pnpm --filter=@posthog/frontend dev

Running PostHog

Using bin/start (Recommended)

The bin/start script runs all services in parallel:

./bin/start

This starts:

Django web server (port 8000)
Celery workers (background tasks)
Celery beat (scheduled tasks)
Frontend dev server (hot reload)
Plugin server (event processing)
Temporal worker (workflows)

Additional options:

# Enable distributed tracing
./bin/start --tracing

# Use custom mprocs config
./bin/start --custom bin/mprocs-custom.yaml

Use Ctrl+A then K to navigate between services in mprocs. Press Q to quit all services.

Running Services Individually

For debugging or targeted development:

# Start Django development server
python manage.py runserver 8000

# Start Celery worker
celery -A posthog worker -l INFO

# Start Celery beat (scheduler)
celery -A posthog beat -l INFO

# Start frontend dev server with hot reload
pnpm --filter=@posthog/frontend dev

# Process events and run plugins
pnpm --filter=@posthog/plugin-server start

Development Workflow

Auto-Detection of Flox Environment

If using Flox, commands are automatically wrapped:

# Automatically uses flox if available
pytest

# Equivalent to:
flox activate -- bash -c "pytest"

Never use flox activate in interactive sessions - it hangs. The auto-detection handles this for you.

Code Formatting

# Format and lint Python code
ruff check . --fix
ruff format .

# Format TypeScript/React code
pnpm --filter=@posthog/frontend format

# Type check
pnpm --filter=@posthog/frontend typescript:check

Hot Reloading

Frontend: Changes auto-reload at http://localhost:8000
Backend: Django auto-reloads on Python file changes
Styles: Tailwind CSS rebuilds automatically

Common Tasks

Create a New Product

# Bootstrap product structure
bin/hogli product:bootstrap your_product_name

# Verify structure
bin/hogli product:lint your_product_name

Generate API Types

When you change Django serializers, regenerate TypeScript types:

bin/hogli build:openapi

This updates:

frontend/src/generated/core/api.ts
products/*/frontend/generated/api.ts

Create Database Migrations

# Auto-generate migration
python manage.py makemigrations

# Apply migrations
python manage.py migrate

# Create ClickHouse migration
python manage.py create_clickhouse_migration <name>

# Apply ClickHouse migrations
python manage.py migrate_clickhouse

Reset Database

# Drop and recreate PostgreSQL
docker compose -f docker-compose.dev.yml down -v
docker compose -f docker-compose.dev.yml up -d
python manage.py migrate
python manage.py migrate_clickhouse

Troubleshooting

Port already in use

If you see Address already in use errors:

# Find process using port
lsof -i :8000

# Kill the process
kill -9 <PID>

# Or change the port in docker-compose.dev.yml

Database connection errors

Ensure Docker services are running:

# Check service status
docker compose -f docker-compose.dev.yml ps

# Restart services
docker compose -f docker-compose.dev.yml restart

Frontend build fails

Clear caches and reinstall:

# Clear pnpm cache
pnpm store prune

# Remove node_modules
rm -rf node_modules frontend/node_modules

# Reinstall
pnpm install

Python dependencies not found

If using Flox:

# Rebuild environment
flox activate -- bash -c "pip install -r requirements.txt"

Without Flox:

# Reinstall with uv
uv pip install -r requirements.txt --force-reinstall

System Design

Development

Local Development Setup

Prerequisites

Quick Start

Detailed Setup

1. Environment Setup

Option A: Using Flox (Recommended)

Option B: Manual Setup

2. Infrastructure Services

3. Database Setup

4. Environment Variables

5. Frontend Setup

Running PostHog

Using bin/start (Recommended)

Running Services Individually

Development Workflow

Auto-Detection of Flox Environment

Code Formatting

Hot Reloading

Common Tasks

Create a New Product

Generate API Types

Create Database Migrations

Reset Database

Troubleshooting

Next Steps

Testing

Contributing

​Prerequisites

​Quick Start

​Detailed Setup

​1. Environment Setup

​Option A: Using Flox (Recommended)

​Option B: Manual Setup

​2. Infrastructure Services

​3. Database Setup

​4. Environment Variables

​5. Frontend Setup

​Running PostHog

​Using bin/start (Recommended)

​Running Services Individually

​Development Workflow

​Auto-Detection of Flox Environment

​Code Formatting

​Hot Reloading

​Common Tasks

​Create a New Product

​Generate API Types

​Create Database Migrations

​Reset Database

​Troubleshooting

​Next Steps

Testing

Contributing

Prerequisites

Quick Start

Detailed Setup

1. Environment Setup

Option A: Using Flox (Recommended)

Option B: Manual Setup

2. Infrastructure Services

3. Database Setup

4. Environment Variables

5. Frontend Setup

Running PostHog

Using bin/start (Recommended)

Running Services Individually

Development Workflow

Auto-Detection of Flox Environment

Code Formatting

Hot Reloading

Common Tasks

Create a New Product

Generate API Types

Create Database Migrations

Reset Database

Troubleshooting

Next Steps