Deploying to Heroku

Why Heroku

Heroku is currently the quickest way to get a production PostHog environment up and running!

If you've never heard of Heroku or what it does, feel free to check out this page that provides a quick gist of the product.

Prerequisites

  • A Heroku account set up and verified (it's free, don't worry :D).

    Although the deployment is free, ensure that your credit card information is entered in your profile. If not, the initial build will fail and prompt you to do so.

Step By Step Installation

Deploy

  1. Click on the button above to go to the app creation screen.
  2. Enter the desired name of your PostHog app and hit Deploy App on the bottom of the screen.
  3. Wait.

    Note: This may take a few minutes, so resist the urge to refresh the page or restart the process

  4. Once completed, you will see two options on the bottom of the screen: Manage App & View App. To go to PostHog, simply click the View App button!

    • If you want to review add ons and other details of the instance, simply click the Manage App button or access the instance from your Dashboard (click on the 9 dots by your profile on the top right).
    • Within the Manage App screen, simply click Open App on the top right to start your PostHog environment.

Add-Ons

By default, we install a hobby-dev Postgres and Redis add-on to the app - these can be found in the Manage App screen under Installed add-ons.

Heroku provides 10k rows for free on Postgres, which you will hit fairly quickly - even on smaller websites.

  • To upgrade your Postgres plan, check out this doc by Heroku that outlines the process step-by-step.

Similarly, you might also want to upgrade your Redis instance if you have a larger PostHog deployment:

  1. Navigate back to the Manage App screen.
  2. Click on the Configure Add-ons link by the Installed add-ons section.
  3. Click on the button to the right of both the Heroku Postgres and Heroku Redis add-on.

    • it looks like an up and down symbol you'd see by an elevator.
  4. Click on Modify Plan and pick your desired one!

Upgrading PostHog on Heroku

git clone https://github.com/PostHog/posthog.git
cd posthog
git remote add heroku https://git.heroku.com/[your-heroku-posthog-app-name].git
git push -f heroku master

Upgrading Dyno Type

By default, Heroku uses a hobby-dev dyno, which sleeps if there hasn't been any activity for 30 minutes. If PostHog is constantly used, eventually you'll exceed your free hours and Heroku will put your app to sleep.

To avoid this, we strongly recommend upgrading to at least a "Hobby" dyno:

  1. Navigate back to the Manage App screen.
  2. Click on the Configure Dynos link by the Dyno Formation section.
  3. Click on the Change Dyno Type button.
  4. Choose your desired tier!

Upgrading from before 1.0.11?

PostHog is now using Redis with a worker to process events and other background tasks. If you're getting a REDIS_URL is required error or seeing a Configuration Error in the interface, you'll need to setup a Redis server and run the worker process.

A new Heroku Redis addon should be enabled automatically with the free plan. We recommend to switch to at least the first paid plan (premium-0) to enable persistence and protect yourself against data loss. You will also see a new dyno type called worker, which may or may not be deployed automatically. You will need to deploy at least one worker dyno for the background tasks to work.

Upgrading from before 3 March 2020?

If you last updated PostHog before 3 March 2020 AND you have a lot of events, there is one migration (0027) that might take a long time.

To avoid this, before you migrate, run python manage.py migrate_elementgroup to pre-migrate elements across.

If you only have a few thousand events, you probably don't need to worry about this.