Skip to content

LOCAL-DEVELOPMENT.md

Latest commit

 

History

History
106 lines (70 loc) · 4.15 KB

LOCAL-DEVELOPMENT.md

File metadata and controls

106 lines (70 loc) · 4.15 KB

Connecting PostHog Code to a Local PostHog Instance

This guide walks you through running PostHog Code's dev build against a local PostHog instance (localhost:8010).

Prerequisites

1. Set up the OAuth application in PostHog

PostHog Code authenticates with PostHog via OAuth. Your local PostHog instance needs an OAuth application registered for PostHog Code to connect to it.

Option A: Generate demo data (easiest)

PostHog's demo data generator creates a pre-configured OAuth application with the correct client ID:

# In your PostHog repo
python manage.py generate_demo_data

This creates an OAuth application with:

  • Client ID: DC5uRLVbGI02YQ82grxgnK6Qn12SXWpCqdPb60oZ
  • Redirect URIs: includes http://localhost:8237/callback and http://localhost:8239/callback

Option B: Create the OAuth application manually via Django admin

  1. Go to http://localhost:8010/admin/posthog/oauthapplication/
  2. Click Add OAuth Application
  3. Set these fields:
    • Name: PostHog Code (or whatever you like)
    • Client ID: DC5uRLVbGI02YQ82grxgnK6Qn12SXWpCqdPb60oZ — this must match the POSTHOG_DEV_CLIENT_ID in PostHog Code's source
    • Client type: Public (PostHog Code is an Electron desktop app)
    • Authorization grant type: Authorization code
    • Redirect URIs: http://localhost:8237/callback http://localhost:8239/callback
    • Algorithm: RS256
  4. Save

Important: The Client ID must be exactly DC5uRLVbGI02YQ82grxgnK6Qn12SXWpCqdPb60oZ — this is hardcoded in PostHog Code as the Dev region client ID (see apps/code/src/shared/constants/oauth.ts).

2. Configure RSA keys in PostHog

OAuth token signing requires an RSA private key. In your PostHog repo:

# Copy the RSA key from .env.example to your .env
grep OIDC_RSA_PRIVATE_KEY .env.example >> .env

Or generate a new one:

openssl genrsa 2048 | openssl pkcs8 -topk8 -nocrypt -outform PEM | \
  awk 'NF {sub(/\r/, ""); printf "%s\\n",$0;}'

# Add to your PostHog .env as OIDC_RSA_PRIVATE_KEY="<generated_key>"

3. Clone and run PostHog Code

git clone https://github.com/PostHog/code.git
cd code
pnpm install
cp .env.example .env
pnpm dev

4. Connect to your local instance

  1. When the PostHog Code app opens, select the Dev region on the login screen (in addition to US & EU, the dev build shows a Dev option that points to localhost:8010)
  2. This will redirect you to your local PostHog instance for OAuth authorization
  3. Authorize the application and select the project/organization access level
  4. You'll be redirected back to PostHog Code, now connected to your local PostHog

How it works

The dev build of PostHog Code includes a "Dev" cloud region that maps to:

  • API URL: http://localhost:8010
  • OAuth Client ID: DC5uRLVbGI02YQ82grxgnK6Qn12SXWpCqdPb60oZ

This is defined in apps/code/src/shared/constants/oauth.ts. The Dev region only appears when running the dev build (pnpm dev), not in production releases.

Troubleshooting

"Invalid client_id" error during OAuth

The OAuth application in your local PostHog must have the client ID DC5uRLVbGI02YQ82grxgnK6Qn12SXWpCqdPb60oZ. Verify at http://localhost:8010/admin/posthog/oauthapplication/.

"Redirect URI mismatch"

Make sure the OAuth application's redirect URIs include http://localhost:8237/callback and http://localhost:8239/callback. Check for trailing slashes.

OAuth authorization page fails to load

Ensure your local PostHog instance is running at http://localhost:8010 and that the RSA key is configured (see step 2).

Existing projects not showing up

After connecting, PostHog Code will show projects from your local PostHog instance. If you need test data, run python manage.py generate_demo_data in your PostHog repo.

Further reading