Environment variables

Last updated:

When using PostHog, there are various environment variables you can set to configure your instance. Below is a comprehensive list of all of them. However, for general use, you most likely do not have to worry about the vast majority of these.

Rows with a missing 'Default Value' usually default to an empty string. This is different from None.

Some variables here are default Django variables. This Django Docs page has more information about them.

VariableDescriptionDefault Value
SECRET_KEY❗️ Always required. Used by Django for cryptography. Helps secure cookies, sessions, hashes, etc. Custom value required in production.<randomly generated secret key>
SITE_URL - should be an absolute URL and include the protocol (e.g. https://app.posthog.com)❗️ Always required. Principal/canonical URL of your PostHog instance. Needed for emails, webhooks and SSO to work properly. We currently do not support subpaths in this URL.http://localhost:8000
DEBUGDetermines if PostHog should run in DEBUG mode. You can set this to a truthy value when developing, but disable this in production!False
SECURE_COOKIESDetermines if Django should use secure cookies. Insecure cookies do not work without HTTPS.False if PostHog is running in DEBUG or TEST mode, else True
JS_URLURL used by Webpack for loading external resources like images and files.http://localhost:8234 if PostHog is running in DEBUG mode, must be specified otherwise.
SENTRY_DSNUsed to integrate with Sentry error and event tracking. Ignored when running tests.None
ASYNC_EVENT_ACTION_MAPPINGIf set to False, actions will be matched to events as they come. Otherwise, the matching will happen in batches through a periodic Celery task. Should only be toggled on by high load instances.False
ACTION_EVENT_MAPPING_INTERVAL_SECONDSSpecify how often (in seconds) PostHog should run a job to match events to actions.300
DISABLE_SECURE_SSL_REDIRECTDisables automatic redirect from port 80 (HTTP) to port 443 (HTTPS).False
IS_BEHIND_PROXYSpecifies if PostHog is running behind a proxy like Apache, NGINX or ELB. Be sure to properly set trusted proxies.False
ALLOWED_IP_BLOCKSSpecifies IP blocks allowed to connect to the PostHog instance for management (events will still be allowed from anywhere). Make sure to properly configure your proxy if running behind a proxy.Empty
TRUSTED_PROXIESSpecifies the IPs of proxies that can be trusted.None
TRUST_ALL_PROXIESDetermines if all proxies can be trusted.False
ALLOWED_HOSTSA list of strings representing the host/domain names that Django can serve. More info.* (all)
STATSD_HOSTHost of a running StatsD daemon (e.g. 127.0.0.1)None
STATSD_PORTPort for the running StatsD daemon8125
STATSD_PREFIXPrefix to be prepended to all stats used by StatsD. Useful for distinguishing environments using the same server.Empty
CAPTURE_INTERNAL_METRICSSend some internal instrumentation to your own posthog instance, exposed via /instance/status page. For EE only.False
DATABASE_URLDatabase URL pointing to your PostgreSQL instance.postgres://localhost:5432/posthog if PostHog is running in DEBUG or TEST mode, must be specified otherwise.
POSTHOG_DB_NAMEDatabase name.Must be specified when DATABASE_URL is not set.
POSTHOG_DB_USERDatabase user name.postgres if PostHog is running in DEBUG or TEST mode. Must be specified when DATABASE_URL is not set.
POSTHOG_DB_PASSWORDDatabase password."" if PostHog is running in DEBUG or TEST mode. Must be specified when DATABASE_URL is not set.
POSTHOG_POSTGRES_HOSTHost pointing to your PostgreSQL instance.localhost if PostHog is running in DEBUG or TEST mode. Must be specified when DATABASE_URL is not set.
POSTHOG_POSTGRES_PORTPort pointing to your PostgreSQL instance.5432 if PostHog is running in DEBUG or TEST mode. Must be specified when DATABASE_URL is not set.
POSTHOG_POSTGRES_SSL_MODEPostgreSQL SSL mode. More info.None
POSTHOG_POSTGRES_CLI_SSL_CALocation of the SSL root certificate file for PostgreSQL. More info.None
POSTHOG_POSTGRES_CLI_SSL_CRTLocation of the SSL certificate file for PostgreSQL. More info.None
POSTHOG_POSTGRES_CLI_SSL_KEYLocation of the SSL key file for PostgreSQL. More info.None
REDIS_URLRedis URL pointing to your Redis instance.redis://localhost/ if PostHog is running in DEBUG or TEST mode, must be specified otherwise.
EMAIL_HOSTPlease see configuring email for details.Please see configuring email for details.
EMAIL_PORTPlease see configuring email for details.Please see configuring email for details.
EMAIL_HOST_USERPlease see configuring email for details.Please see configuring email for details.
EMAIL_HOST_PASSWORDPlease see configuring email for details.Please see configuring email for details.
EMAIL_USE_TLSPlease see configuring email for details.Please see configuring email for details.
EMAIL_USE_TLSPlease see configuring email for details.Please see configuring email for details.
EMAIL_DEFAULT_FROMPlease see configuring email for details.Please see configuring email for details.
EMAIL_ENABLEDPlease see configuring email for details.Please see configuring email for details.
NPM_TOKENAccess token for npm, used to allow installation of plugins released as a private npm packageNone
GITHUB_TOKENGitHub personal access token, used to prevent rate limiting when using plugins and to allow installation of plugins from private reposNone
GITLAB_TOKENGitLab personal access token, used to prevent rate limiting when using plugins and to allow installation of plugins from private reposNone
MULTI_ORG_ENABLEDAllows creating multiple organizations in your instance (multi-tenancy). Requires a premium license.False
SOCIAL_AUTH_GITHUB_KEYGitHub key for allowing sign up with GitHub.Empty
SOCIAL_AUTH_GITHUB_SECRETGitHub secret for allowing sign up with GitHub.Empty
SOCIAL_AUTH_GITLAB_KEYGitLab key for allowing sign up with GitLab.Empty
SOCIAL_AUTH_GITLAB_SECRETGitLab secret for allowing sign up with GitLab.Empty
SOCIAL_AUTH_GITLAB_API_URLEndpoint to be used for GitLab authentication. Changing this is only relevant for self-host GitLab users.https://gitlab.com
SOCIAL_AUTH_GOOGLE_OAUTH2_KEYGoogle client ID for allowing SSO with Google.Empty
SOCIAL_AUTH_GOOGLE_OAUTH2_SECRETGoogle client secret for allowing SSO with Google.Empty
SAML_DISABLEDWhether SAML should be completely disabled. If set at build time, this will also prevent SAML dependencies from being installed. See SAML authentication.False
SAML_ENTITY_IDEntity ID from your SAML IdP. See SAML authentication.Empty
SAML_ACS_URLAssertion Consumer Service URL from your SAML IdP. See SAML authentication.Empty
SAML_X509_CERTPublic X509 certificate from your SAML IdP to validate SAML assertions. See SAML authentication.Empty
SAML_ATTR_PERMANENT_IDName of attribute that contains the permanent ID of the user in SAML assertions. See SAML authentication.name_id
SAML_ATTR_FIRST_NAMEName of attribute that contains the first name of the user in SAML assertions. See SAML authentication.first_name
SAML_ATTR_LAST_NAMEName of attribute that contains the last name of the user in SAML assertions. See SAML authentication.last_name
SAML_ATTR_EMAILName of attribute that contains the email of the user in SAML assertions. See SAML authentication.email
SAML_ENFORCEDWhether password-based login is disabled and users automatically redirected to SAML login. Requires SAML to be properly configured. See SAML authentication.False