Self-host PostHog

Last updated:

|Edit this page

This page covers our open-source Docker compose deployment, which is available under a MIT license, without guarantee. We are continuing to develop this version of PostHog, but please note that PostHog does not provide support for customers deploying this version beyond these docs.

Our MIT-licensed Docker compose deployment is best suited to internal tools, or evaluating features without vendor approval. It's also great for hobby projects which don't need advanced tools. For all other use cases, we recommend you use PostHog Cloud, which comes with a generous free tier.

Requirements

  • You have deployed a Linux Ubuntu Virtual Machine.
    • We highly recommend an instance with at least 4GB of RAM to handle any surges in event volume
  • You have set up an A record to connect a custom domain to your instance.
    • PostHog will automatically create an SSL certificate for your domain using LetsEncrypt

New deployments of PostHog's paid open source product using Kubernetes are no longer supported.

Configuration

There are various ways to configure and personalize your PostHog instance to better suit your needs. In this section you will find all the information you need about settings and options you can configure to get what you need out of PostHog.

Setting up the stack

To get started, all we need to do is run the following command, which will spin up a fresh PostHog deployment for us automatically!

Terminal
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/posthog/posthog/HEAD/bin/deploy-hobby)"

You'll now be asked to provide the release tag you would like to use, as well as the domain you have connected to your instance.

This release tag is the DockerHub tag and doesn't refer to the sunsetted Helm chart releases

Once everything has been setup, you should see the following message:

We will need to wait ~5-10 minutes for things to settle down, migrations to finish, and TLS certs to be issued
⏳ Waiting for PostHog web to boot (this will take a few minutes)

PostHog will wait here on a couple of tasks that need to be completed, which should only take a couple minutes.

Once this is complete, you should be able to see your PostHog dashboard on the domain you provided!

If you notice this step taking longer than 10 minutes, it's best to cancel it with Ctrl+C and take a look at the troubleshooting section.

Customizing your deployment (optional)

By default, the docker-compose.yml file that gets run comes with a series of default config values that should work for most deployments. If you need to customize anything, you can take a look at the full list of environment variables. After making any changes, simply restart the stack with docker-compose.

Additionally, if you would like to run a different version of PostHog, you can change the tag for the web, worker, and plugins services. Check out here for a list of all available tags.

Troubleshooting

If you have already run the one-step deployment command above and something went wrong, this section covers a number of steps you can take to debug issues.

Checking that all containers are running

We can use docker ps to check that all of our services are running.

Terminal
$ docker ps
CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES
21a2f62d6e50 posthog/posthog:release-1.39.1 ... 1m ago Up 1m ... ...
77face12d3e2 posthog/posthog:release-1.39.1 ... 1m ago Up 1m ... ...
3b4bc7394049 posthog/posthog:release-1.39.1 ... 1m ago Up 1m ... ...
03f393c7aa84 caddy:2.6.1 ... 1m ago Up 1m ... ...
f1060c3d8d73 clickhouse/clickhouse-server:22.3 ... 1m ago Up 1m ... ...
7d2353a6bddf bitnami/kafka:2.8.1-debian-10-r99 ... 1m ago Up 1m ... ...
72051397040e zookeeper:3.7.0 ... 1m ago Up 1m ... ...
ff42ccf14481 redis:6.2.7-alpine ... 1m ago Up 1m ... ...
402a0eef69ae postgres:12-alpine ... 1m ago Up 1m ... ...
da0d115dd02e minio/minio ... 1m ago Up 1m ... ...

You should see all the same containers as above. If any containers aren't showing up or show that they've restarted recently, it's worth checking their logs to see what the issue is.

Checking the logs of each container

We can use the following command to check the logs for each of our containers.

Terminal
docker logs <container_name>

The best place to start looking is in the web container, which runs all the database migrations and will produce an error if any have failed.

Running into issues with deployment? Ask a question here or check out our Slack to get help.

Upgrading

To upgrade, you can run the upgrade-hobby script from the PostHog repo.

Terminal
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/posthog/posthog/HEAD/bin/upgrade-hobby)"

Warning: Before upgrading, make sure you have created back-ups of all your data!

Our recommendation is to keep your PostHog deployment up-to-date. While we avoid breaking changes wherever possible we may sometimes deprecate or add features that require you to update to the latest version. You can track our latest updates in the changelog.

Migrating

If your server is struggling, you can either increase your instance size or move to PostHog Cloud for a hands-off experience

Questions?

Was this page useful?

Next article

Upgrading PostHog

We want to make sure upgrading PostHog is as smooth as possible. We use a synchronous and an asynchronous migration framework to make sure database migrations are easy to be deployed, rolled back and safe to run. Because some data migrations require touching tables that can get very large for some PostHog installation, some migrations are a little more involved. For more information on any extra steps needed when updating to specific versions, check out our upgrade notes . If you need help…

Read next article