PostHog Docker 설치 가이드: 올인원 제품 분석 플랫폼

작성자:


PostHog는 Mixpanel, Amplitude, Heap을 대체하는 올인원 제품 분석 플랫폼입니다. 웹 분석을 넘어 사용자 행동 심층 분석, 세션 녹화, 기능 플래그, A/B 테스트, 퍼널 분석까지 하나의 플랫폼에서 제공합니다. 제품 개발팀이 데이터 기반 의사결정을 하기 위한 모든 도구를 갖추고 있습니다. GitHub Stars 25K+로 빠르게 성장 중입니다.

PostHog 주요 특징

PostHog는 제품 팀을 위한 완전한 분석 스택입니다.

제품 분석

  • 이벤트 추적: 자동 & 커스텀 이벤트
  • 퍼널 분석: 전환 경로 분석
  • 리텐션: 사용자 유지율 분석
  • 경로 분석: 사용자 여정 시각화
  • 코호트: 사용자 세그먼트 분석
  • 트렌드: 시계열 분석

사용자 행동 분석

  • 세션 녹화: 사용자 화면 녹화
  • 히트맵: 클릭/스크롤 히트맵
  • 에러 추적: 버그 모니터링

실험 & 기능 관리

  • 기능 플래그: 기능 토글
  • A/B 테스트: 실험 설계 및 분석
  • 점진적 롤아웃: 단계별 기능 배포

데이터 플랫폼

  • Data Warehouse: SQL 쿼리
  • CDP: 고객 데이터 플랫폼
  • API & Webhooks: 통합

사전 요구 사항

PostHog는 리소스를 많이 사용합니다:

  • Docker 및 Docker Compose 설치
  • 최소 4 vCPU, 8GB RAM (16GB 권장)
  • 50GB 이상 저장 공간
  • 도메인 (Let’s Encrypt 자동 인증)

Docker Compose로 PostHog 설치

방법 1: 공식 Hobby 배포 (권장)

# 공식 설치 스크립트 실행
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/PostHog/posthog/HEAD/bin/deploy-hobby)"

설치 중 입력 항목:

  • Release tag (예: release-1.43.0 또는 latest)
  • 도메인 (예: posthog.yourdomain.com)

방법 2: 수동 Docker Compose

# 저장소 클론
git clone https://github.com/posthog/posthog.git
cd posthog

# 환경 변수 설정
cp .env.example .env

# .env 파일 편집
nano .env

환경 변수 (.env)

# .env
POSTHOG_SECRET=your_very_long_secret_key_here
SITE_URL=https://posthog.yourdomain.com

# 데이터베이스 (자동 설정)
DATABASE_URL=postgres://posthog:posthog@db:5432/posthog

# ClickHouse (분석 데이터)
CLICKHOUSE_HOST=clickhouse
CLICKHOUSE_DATABASE=posthog

# Redis
REDIS_URL=redis://redis:6379/

시크릿 키 생성:

openssl rand -hex 32

Docker Compose 실행

# 컨테이너 실행
docker compose -f docker-compose.hobby.yml up -d

# 로그 확인 (마이그레이션에 5-10분 소요)
docker compose logs -f

# 브라우저에서 접속
# http://localhost:8000 또는 https://posthog.yourdomain.com
# 첫 계정 생성

초기 설정

1. 관리자 계정 생성

  1. https://posthog.yourdomain.com 접속
  2. 이름, 이메일, 비밀번호 입력
  3. 조직 이름 설정
  4. 첫 프로젝트 생성

2. 추적 코드 설치

JavaScript SDK:

<script>
  !function(t,e){var o,n,p,r;e.__SV||(window.posthog=e,e._i=[],e.init=function(i,s,a){function g(t,e){var o=e.split(".");2==o.length&&(t=t[o[0]],e=o[1]),t[e]=function(){t.push([e].concat(Array.prototype.slice.call(arguments,0)))}}(p=t.createElement("script")).type="text/javascript",p.async=!0,p.src=s.api_host+"/static/array.js",(r=t.getElementsByTagName("script")[0]).parentNode.insertBefore(p,r);var u=e;for(void 0!==a?u=e[a]=[]:a="posthog",u.people=u.people||[],u.toString=function(t){var e="posthog";return"posthog"!==a&&(e+="."+a),t||(e+=" (stub)"),e},u.people.toString=function(){return u.toString(1)+".people (stub)"},o="capture identify alias people.set people.set_once set_config register register_once unregister opt_out_capturing has_opted_out_capturing opt_in_capturing reset isFeatureEnabled onFeatureFlags getFeatureFlag getFeatureFlagPayload reloadFeatureFlags group updateEarlyAccessFeatureEnrollment getEarlyAccessFeatures getActiveMatchingSurveys getSurveys".split(" "),n=0;n<o.length;n++)g(u,o[n]);e._i.push([i,s,a])},e.__SV=1)}(document,window.posthog||[]);
  posthog.init('YOUR_PROJECT_API_KEY',{api_host:'https://posthog.yourdomain.com'})
</script>

3. 이벤트 자동 캡처 활성화

PostHog는 기본적으로 클릭, 페이지뷰 등을 자동 캡처합니다.

고급 기능 설정

세션 녹화 활성화

posthog.init('YOUR_PROJECT_API_KEY', {
  api_host: 'https://posthog.yourdomain.com',
  session_recording: {
    recordCrossOriginIframes: true,
  }
})

기능 플래그 사용

// 기능 플래그 확인
if (posthog.isFeatureEnabled('new-checkout')) {
  // 새 체크아웃 UI 표시
}

// 기능 플래그 값 가져오기
const variant = posthog.getFeatureFlag('experiment-name')

커스텀 이벤트 추적

// 이벤트 캡처
posthog.capture('purchase', {
  product_name: 'T-Shirt',
  price: 29.99,
  currency: 'USD'
})

// 사용자 식별
posthog.identify('user_123', {
  email: 'user@example.com',
  plan: 'premium'
})

프로덕션 설정

Traefik과 함께 사용

# docker-compose.override.yml
services:
  web:
    labels:
      - "traefik.enable=true"
      - "traefik.http.routers.posthog.rule=Host(`posthog.yourdomain.com`)"
      - "traefik.http.routers.posthog.entrypoints=websecure"
      - "traefik.http.routers.posthog.tls.certresolver=letsencrypt"
      - "traefik.http.services.posthog.loadbalancer.server.port=8000"

SSL/TLS 설정 (Caddy 내장)

PostHog Hobby 배포는 Caddy가 포함되어 자동으로 Let’s Encrypt 인증서를 발급합니다.

# .env에 도메인 설정
SITE_URL=https://posthog.yourdomain.com

관리 명령어

# 로그 확인
docker compose logs -f web

# 서비스 상태 확인
docker compose ps

# Django 관리 명령어
docker compose exec web python manage.py migrate
docker compose exec web python manage.py createsuperuser

# 데이터베이스 백업
docker compose exec db pg_dump -U posthog posthog > backup_$(date +%Y%m%d).sql

# ClickHouse 백업
docker compose exec clickhouse clickhouse-client --query "BACKUP DATABASE posthog TO Disk('backups', 'backup.zip')"

# 업데이트
docker compose pull
docker compose up -d

# 재시작
docker compose restart web worker

주요 환경 변수

변수설명필수
POSTHOG_SECRETDjango 시크릿 키✅
SITE_URL외부 접근 URL✅
DATABASE_URLPostgreSQL 연결✅
CLICKHOUSE_HOSTClickHouse 호스트✅
REDIS_URLRedis 연결✅
DISABLE_SECURE_SSL_REDIRECTSSL 리디렉션 비활성화❌

문제 해결

메모리 부족 (Exit Code 137)

PostHog는 최소 8GB RAM이 필요합니다:

# 메모리 확인
free -h

# Docker 메모리 제한 확인
docker stats

ClickHouse 연결 오류

# ClickHouse 상태 확인
docker compose exec clickhouse clickhouse-client --query "SELECT 1"

마이그레이션 오류

# 마이그레이션 재실행
docker compose exec web python manage.py migrate

로컬 PostgreSQL 충돌

호스트의 PostgreSQL 서비스 중지:

sudo service postgresql stop

PostHog Cloud vs Self-Hosted

항목CloudSelf-Hosted
설정즉시30분+
유지보수자동직접
비용사용량 기반인프라 비용만
데이터 위치PostHog 서버내 서버
기능전체전체 (MIT)

마무리

PostHog는 제품 분석, 세션 녹화, 기능 플래그, A/B 테스트를 하나의 플랫폼에서 제공하는 올인원 솔루션입니다. Mixpanel, Amplitude, LaunchDarkly를 각각 사용하는 대신 PostHog 하나로 통합할 수 있습니다. 리소스 요구사항이 높지만, 제품 팀에게 필요한 모든 도구를 제공합니다.

참고 링크

  • 공식 사이트: https://posthog.com
  • GitHub: https://github.com/PostHog/posthog
  • Docker: https://hub.docker.com/r/posthog/posthog
  • 문서: https://posthog.com/docs


댓글 남기기