PostHog Deploy Integration Skill

PostHog Deploy Integration

Overview

Deploy PostHog analytics to production platforms. Covers Next.js with Vercel (reverse proxy, server-side capture, edge functions), self-hosted PostHog with Docker, and Google Cloud Run deployment patterns.

Prerequisites

PostHog project API key (phc_...)
PostHog personal API key (phx_...) for server features
Platform CLI installed (vercel, docker, or gcloud)

Instructions

Step 1: Next.js + Vercel Deployment

set -euo pipefail
# Set environment variables in Vercel
vercel env add NEXT_PUBLIC_POSTHOG_KEY production     # phc_... (public)
vercel env add NEXT_PUBLIC_POSTHOG_HOST production    # /ingest (if using proxy)
vercel env add POSTHOG_PERSONAL_API_KEY production    # phx_... (server-only)
vercel env add POSTHOG_PROJECT_ID production          # Project ID number

// next.config.js — Reverse proxy to bypass ad blockers
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*',
      },
    ];
  },
};

// app/providers.tsx — Client-side PostHog with proxy
'use client';
import posthog from 'posthog-js';
import { PostHogProvider } from 'posthog-js/react';
import { useEffect } from 'react';

export function PHProvider({ children }: { children: React.ReactNode }) {
  useEffect(() => {
    posthog.init(process.env.NEXT_PUBLIC_POSTHOG_KEY!, {
      api_host: '/ingest', // Routes through your domain's reverse proxy
      capture_pageview: false, // Handle manually in App Router
      capture_pageleave: true,
    });
  }, []);

  return <PostHogProvider client={posthog}>{children}</PostHogProvider>;
}

Step 2: Server-Side Capture in Vercel Edge Functions

// app/api/track/route.ts — Server-side event capture
import { PostHog } from 'posthog-node';
import { NextResponse } from 'next/server';

export const runtime = 'edge';

export async function POST(request: Request) {
  const body = await request.json();
  const { userId, event, properties } = body;

  const posthog = new PostHog(process.env.NEXT_PUBLIC_POSTHOG_KEY!, {
    host: 'https://us.i.posthog.com',
    flushAt: 1,       // Immediate flush in serverless
    flushInterval: 0,
  });

  try {
    posthog.capture({ distinctId: userId, event, properties });
    await posthog.shutdown(); // CRITICAL: flush before function exits
    return NextResponse.json({ status: 'ok' });
  } catch (error) {
    return NextResponse.json({ error: 'capture failed' }, { status: 500 });
  }
}

Step 3: Self-Hosted PostHog (Docker)

set -euo pipefail
# Deploy PostHog self-hosted (hobby tier)
git clone https://github.com/PostHog/posthog.git
cd posthog

# Configure environment
cat > .env <<'EOF'
SECRET_KEY=your-random-secret-key-here
SITE_URL=https://posthog.yourcompany.com
IS_BEHIND_PROXY=true
EOF

# Start PostHog
docker compose -f docker-compose.hobby.yml up -d

# PostHog runs at http://localhost:8000
# Complete setup wizard in browser

# Health check
curl -s http://localhost:8000/_health | jq .

// Point SDKs to your self-hosted instance
posthog.init('phc_your_key', {
  api_host: 'https://posthog.yourcompany.com', // Your self-hosted URL
});

Step 4: Google Cloud Run Deployment

set -euo pipefail
# Set secrets in GCP Secret Manager
echo -n "phc_your_key" | gcloud secrets create posthog-project-key --data-file=-
echo -n "phx_your_key" | gcloud secrets create posthog-personal-key --data-file=-

# Deploy with PostHog secrets
gcloud run deploy my-app \
  --image gcr.io/my-project/my-app:latest \
  --set-secrets "NEXT_PUBLIC_POSTHOG_KEY=posthog-project-key:latest" \
  --set-secrets "POSTHOG_PERSONAL_API_KEY=posthog-personal-key:latest" \
  --set-env-vars "POSTHOG_HOST=https://us.i.posthog.com" \
  --region us-central1 \
  --allow-unauthenticated

Step 5: Deploy Annotation (Mark Deployments in PostHog)

set -euo pipefail
# Create annotation on each deploy so you can correlate metric changes with releases
curl -X POST "https://app.posthog.com/api/projects/$POSTHOG_PROJECT_ID/annotations/" \
  -H "Authorization: Bearer $POSTHOG_PERSONAL_API_KEY" \
  -H "Content-Type: application/json" \
  -d "{
    \"content\": \"Deploy: $(git rev-parse --short HEAD) — $(git log -1 --pretty=%s)\",
    \"date_marker\": \"$(date -u +%Y-%m-%dT%H:%M:%SZ)\",
    \"scope\": \"project\"
  }"

Error Handling

| Issue | Cause | Solution | |-------|-------|----------| | Events not appearing | Wrong api_host | Use us.i.posthog.com (not app.posthog.com) | | Ad blocker blocks events | Direct PostHog requests | Set up reverse proxy via Next.js rewrites | | Edge function events lost | No shutdown() call | Always await posthog.shutdown() in serverless | | Self-hosted 502 | Under-provisioned | Increase Docker memory (min 4GB RAM) | | Cloud Run cold start lag | PostHog init in handler | Move init to module scope, only shutdown in handler |

Output

PostHog deployed to chosen platform with secrets configured
Reverse proxy enabled for ad blocker bypass (Vercel/Next.js)
Server-side event capture with proper shutdown hooks
Deployment annotations marking releases in PostHog timeline

Resources

Next Steps

For webhook handling, see posthog-webhooks-events.

Agent Skills: PostHog Deploy Integration

Install this agent skill to your local

Skill Files