PostHog Deploy Integration

Overview

Deploy PostHog analytics integration to production. Covers client-side snippet deployment, server-side event capture with posthog-node, reverse proxy setup to avoid ad blockers, and self-hosted PostHog deployment using Docker.

Prerequisites

PostHog project API key (starts with phc_)
PostHog personal API key for server-side operations
Platform CLI installed (vercel, docker, or gcloud)

Instructions

Step 1: Client-Side Integration

// lib/posthog.ts
import posthog from "posthog-js";

export function initPostHog() {
  if (typeof window !== "undefined") {
    posthog.init(process.env.NEXT_PUBLIC_POSTHOG_KEY!, {
      api_host: process.env.NEXT_PUBLIC_POSTHOG_HOST || "https://us.i.posthog.com",
      capture_pageview: false, // Manual pageview tracking
      loaded: (posthog) => {
        if (process.env.NODE_ENV === "development") posthog.debug();
      },
    });
  }
}

Step 2: Server-Side Event Capture

// lib/posthog-server.ts
import { PostHog } from "posthog-node";

const posthog = new PostHog(process.env.POSTHOG_API_KEY!, {
  host: process.env.POSTHOG_HOST || "https://us.i.posthog.com",
});

export async function trackServerEvent(
  distinctId: string,
  event: string,
  properties?: Record<string, any>
) {
  posthog.capture({ distinctId, event, properties });
  await posthog.flush();
}

Step 3: Reverse Proxy (Avoid Ad Blockers)

// next.config.js - Proxy PostHog through your domain
module.exports = {
  async rewrites() {
    return [
      {
        source: "/ingest/static/:path*",
        destination: "https://us-assets.i.posthog.com/static/:path*",
      },
      {
        source: "/ingest/:path*",
        destination: "https://us.i.posthog.com/:path*",
      },
    ];
  },
};

Step 4: Self-Hosted Docker Deployment

set -euo pipefail
# Deploy PostHog self-hosted
git clone https://github.com/PostHog/posthog.git
cd posthog
docker compose -f docker-compose.hobby.yml up -d

# Your PostHog instance at http://localhost:8000

Step 5: Vercel Deployment

vercel env add NEXT_PUBLIC_POSTHOG_KEY production
vercel env add NEXT_PUBLIC_POSTHOG_HOST production
vercel env add POSTHOG_API_KEY production  # Server-side key
vercel --prod

Error Handling

Issue	Cause	Solution
Events not appearing	Wrong API key	Verify `phc_` project key
Ad blocker blocking	Direct PostHog requests	Set up reverse proxy
Self-hosted slow	Under-provisioned	Increase Docker resources
Missing server events	Not flushing	Call `posthog.flush()` in serverless

Examples

Basic usage: Apply posthog deploy integration to a standard project setup with default configuration options.

Advanced scenario: Customize posthog deploy integration for production environments with multiple constraints and team-specific requirements.

Resources

Next Steps

For webhook handling, see posthog-webhooks-events.

Output

Configuration files or code changes applied to the project
Validation report confirming correct implementation
Summary of changes made and their rationale

posthog-deploy-integration