env.example

# Example environment configuration for PostHog.
# Source: https://posthog.com/docs/self-host/configure/environment-variables

# --- Core application settings ---
# Required Django signing key. Replace with a unique random string before deploying.
SECRET_KEY=django-insecure-change-me

# Required canonical base URL used in emails, webhooks, and SSO callbacks.
SITE_URL=http://localhost:8000

# Set True behind HTTPS so session cookies are sent securely.
SECURE_COOKIES=False

# Toggle when routing through a reverse proxy (Nginx, ELB, etc.).
IS_BEHIND_PROXY=False

# Comma-separated CIDRs that may reach the management UI; leave empty to allow all.
ALLOWED_IP_BLOCKS=

# Optional comma-separated proxy IPs that can forward client information.
TRUSTED_PROXIES=

# Set True only when every upstream proxy is trusted to forward headers safely.
TRUST_ALL_PROXIES=False

# Restrict hostnames Django will serve; use * for local development only.
ALLOWED_HOSTS=*

# Bypass dependency version checks (generally keep False).
SKIP_SERVICE_VERSION_REQUIREMENTS=False

# --- Background jobs and telemetry ---
# Periodic cadence for matching events to actions, in seconds.
ACTION_EVENT_MAPPING_INTERVAL_SECONDS=300

# Use asynchronous Celery job for action matching on high-volume installs.
ASYNC_EVENT_ACTION_MAPPING=False

# Send PostHog internal telemetry to another PostHog project you control.
CAPTURE_INTERNAL_METRICS=False

# --- PostgreSQL configuration ---
# Primary Postgres connection string; override individual POSTHOG_DB_* settings.
DATABASE_URL=postgres://localhost:5432/posthog

# Enable verbose ClickHouse query logging in the command palette (dev only).
DEBUG_QUERIES=False

# Django DEBUG switch; turn off in production to disable debug tooling.
DEBUG=True

# --- ClickHouse and Kafka ---
# Disable protobuf schemas when using an external ClickHouse vendor.
CLICKHOUSE_DISABLE_EXTERNAL_SCHEMAS=False

# Hide UI that promotes paid features when self-hosting the OSS edition.
DISABLE_PAID_FEATURE_SHOWCASING=False

# Skip enforcing HTTPS redirects (mainly for local HTTP dev).
DISABLE_SECURE_SSL_REDIRECT=False

# GitHub personal token for installing apps without hitting rate limits.
GITHUB_TOKEN=

# GitLab personal token for private apps or higher rate limits.
GITLAB_TOKEN=

# Location to load frontend build assets from; defaults to local webpack dev server.
JS_URL=http://localhost:8234

# Bootstrap URL for the Kafka cluster PostHog connects to.
KAFKA_URL=kafka://kafka

# Kafka endpoint ClickHouse reads from; leave blank to reuse KAFKA_URL.
KAFKA_URL_FOR_CLICKHOUSE=

# Look-back window for column materialization heuristics (hours).
MATERIALIZE_COLUMNS_ANALYSIS_PERIOD_HOURS=168

# How far back to backfill newly materialized columns (days).
MATERIALIZE_COLUMNS_BACKFILL_PERIOD_DAYS=90

# Upper bound of columns materialized per run.
MATERIALIZE_COLUMNS_MAX_AT_ONCE=10

# Query duration threshold (ms) before a column is considered for materialization.
MATERIALIZE_COLUMNS_MINIMUM_QUERY_TIME=3000

# Cron schedule for the ClickHouse column materialization job.
MATERIALIZE_COLUMNS_SCHEDULE_CRON="0 5 * * SAT"

# --- Optional features and analytics ---
# Enable multi-tenant organization support (requires premium license).
MULTI_ORG_ENABLED=False

# Auth token for installing private npm packages from the PostHog App Store.
NPM_TOKEN=

# Disable sending anonymous product usage data back to PostHog.
OPT_OUT_CAPTURE=False

# --- Advanced PostgreSQL overrides ---
# Override Postgres database name when DATABASE_URL is unset.
POSTHOG_DB_NAME=posthog

# Override Postgres password when DATABASE_URL is unset.
POSTHOG_DB_PASSWORD=

# Override Postgres username when DATABASE_URL is unset.
POSTHOG_DB_USER=postgres

# Path to Postgres CA bundle for psql CLI connections.
POSTHOG_POSTGRES_CLI_SSL_CA=

# Path to Postgres client certificate for psql CLI connections.
POSTHOG_POSTGRES_CLI_SSL_CRT=

# Path to Postgres client key for psql CLI connections.
POSTHOG_POSTGRES_CLI_SSL_KEY=

# Hostname for Postgres when you do not provide DATABASE_URL.
POSTHOG_POSTGRES_HOST=localhost

# Port for Postgres when you do not provide DATABASE_URL.
POSTHOG_POSTGRES_PORT=5432

# Postgres SSL mode flag (require, verify-full, etc.) when overriding DATABASE_URL.
POSTHOG_POSTGRES_SSL_MODE=

# --- Caching and queues ---
# Connection string for the Redis cache/queue backend.
REDIS_URL=redis://localhost/

# --- Social authentication ---
# OAuth client ID for GitHub login.
SOCIAL_AUTH_GITHUB_KEY=

# OAuth client secret for GitHub login.
SOCIAL_AUTH_GITHUB_SECRET=

# Base URL for GitLab OAuth (set for self-hosted GitLab).
SOCIAL_AUTH_GITLAB_API_URL=https://gitlab.com

# OAuth client ID for GitLab login.
SOCIAL_AUTH_GITLAB_KEY=

# OAuth client secret for GitLab login.
SOCIAL_AUTH_GITLAB_SECRET=

# Google OAuth client ID for single sign-on.
SOCIAL_AUTH_GOOGLE_OAUTH2_KEY=

# Google OAuth client secret for single sign-on.
SOCIAL_AUTH_GOOGLE_OAUTH2_SECRET=

# --- Observability ---
# Hostname for StatsD metrics forwarding.
STATSD_HOST=127.0.0.1

# StatsD UDP port.
STATSD_PORT=8125

# Prefix added to every StatsD metric name.
STATSD_PREFIX=posthog

# Cron schedule for cleaning deleted ClickHouse rows.
CLEAR_CLICKHOUSE_REMOVED_DATA_SCHEDULE_CRON="0 5 * * SAT"

# Plugin server log level (debug, info, warn, error).
LOG_LEVEL=info

# --- Email (SMTP) ---
# Default From header when email is enabled.
EMAIL_DEFAULT_FROM=posthog@example.com

# Flip to True once SMTP details below are configured.
EMAIL_ENABLED=False

# SMTP password or app-specific token.
EMAIL_HOST_PASSWORD=

# SMTP username used for authentication.
EMAIL_HOST_USER=

# SMTP server hostname.
EMAIL_HOST=smtp.example.com

# SMTP port (587 for STARTTLS, 465 for SSL).
EMAIL_PORT=587

# Use STARTTLS when talking to SMTP.
EMAIL_USE_TLS=True

# Use implicit SSL when talking to SMTP (mutually exclusive with TLS).
EMAIL_USE_SSL=False

# --- Slack integration ---
# Slack OAuth client ID for the PostHog app.
SLACK_APP_CLIENT_ID=

# Slack OAuth client secret for the PostHog app.
SLACK_APP_CLIENT_SECRET=

# Slack signing secret used to validate webhooks.
SLACK_APP_SIGNING_SECRET=