⚠️ Do not use
release-*patterns in your branches unless pushing a release as these branches have special handling related to releases.
Note: If you're using the latest generation MacBooks (M1) have a look at this issue for info on how to run PostHog.
If you want to run your development instance using ClickHouse, check out our EE setup section (currently intended for internal use only).
- Clone the repository:
git clone https://github.com/PostHog/posthog
- Make sure you have Python 3.8 installed
python3 --version. pyenv is recommended to manage multiple Python versions and make sure you don't use the system version.
Set up databases
- Navigate into the correct folder (project's root directory):
- Create the virtual environment in current directory called 'env':
python3 -m venv env
- Activate the virtual environment:
- Install requirements with pip
pip install -r requirements.txt
If you have problems with this step (TLS/SSL error), then run
~ brew update && brew upgrade
python3 -m pip install --upgrade pip
then retry the requirements.txt install.
Friendly tip: If you're running into errors with this step on a Mac with an Apple Silicon chip, you may need to set some environment variables before running the install command, like so:
CFLAGS="-I /opt/homebrew/opt/openssl/include" LDFLAGS="-L /opt/homebrew/opt/openssl/lib" GRPC_PYTHON_BUILD_SYSTEM_OPENSSL=1 GRPC_PYTHON_BUILD_SYSTEM_ZLIB=1 pip install -r requirements.txt
- If you want to fully test all our features, you'll need to install a few dependencies for SAML to run properly. If you're on macOS run the command below, otherwise check out the official xmlsec repo for more details.
brew install libxml2 libxmlsec1 pkg-configpip install python3-saml==1.12.0
- Install dev requirements:
pip install -r requirements-dev.txt
- Run migrations:
DEBUG=1 python3 manage.py migrate
Friendly tip: The error
fe_sendauth: no password suppliedconnecting to Postgres happens when the database is set up with a password and the user:pass isn't specified in
- Make sure you have Yarn installed:
# macOS (Homebrew)brew install yarn
- Make sure you have NodeJS installed:
# macOS (Homebrew)brew install node
Note: For Apple Silicon support, please use NodeJS >= v15.0
- Start the backend, worker, and frontend simultaneously with:./bin/start
Note: The first time you run this command you might get an error that says "layout.html is not defined". Make sure you wait until the frontend is finished compiling and try again.*
Friendly tip: If you run into frontend webpack module errors running
rm -rf node_modules/might help.
Now open http://localhost:8000 to see the app.
To see some data on the frontend, you should go to the
http://localhost:8000/demo and play around with it, so you can see some data on dashboard.
Friendly tip: Homebrew services can be stopped with
brew services stop <service_name>
Running backend, worker, and frontend all together
This script runs the below three scripts concurrently, and automatically sets
Running backend separately (Django)
Running background worker separately (Celery)
Running frontend separately (React)
If at any point, you get "command not found: nvm", you need to install nvm, then use that to install node.
Running backend tests
To see debug logs (includes e.g. ClickHouse queries), run
Running end-to-end Cypress tests
Debugging the backend in PyCharm
With PyCharm's built in support for Django, it's fairly easy to setup debugging in the backend. This is especially useful when you want to trace and debug a network request made from the client all the way back to the server. You can set breakpoints and step through code to see exactly what the backend is doing with your request.
Configuring the debugger
- Setup Django configuration as per JetBrain's docs.
- Click Edit Configuration to edit the Django Server configuration you just created.
- Point PyCharm to the project root (
posthog/) and settings (
- Add these two environment variables
Let's spin it up!
- Set some breakpoints
- In the top toolbar, select the config you just created and click the green bug icon.
- This runs
python manage.py runserverwith extra parameters that enable debugging.
Testing ingestion and feature flags
Note: When developing locally and setting environment variable
DEBUG=1, the local server is treated as what would be "PostHog Cloud". This means that all analytics that are captured from the usage of PostHog are sent to this same local instance (can be quite useful to generate test data too). In addition, feature flags are considered based on the local instance.
Add feature flags to your local instance to use them while developing locally. For example, let's say you want to test the using the
my-feature-flag flag locally - you would create a new flag with the name
my-feature-flag and release that flag to the user account used for testing. Learn more about using feature flags in the Feature Flags user guide.