These docs are a work-in-progress and are currently undergoing a major rewrite!

Environment variables

Most of Forge and the some of the standard Django settings are configured via environment variables. Environment variables are used both in development and in production. If there is a setting that you need to change based on who, how, or where the app is running, then our recommendation is to use environment variables (vs multiple git-committed settings files, hardcoded secrets, etc.).

Setting environment variables

In local development, you can set environment variables in your .env file at the top of your repo (don't commit this file to your git repo!):

DEBUG=true
SECRET_KEY=dev
BASE_URL=http://localhost:8000
DATABASE_URL=postgres://postgres:postgres@localhost:54321/postgres

For Heroku, you can set environment variables either on the Heroku dashboard or by using the heroku config command:

heroku config:set BASE_URL=https://app.example.com

Adding custom settings

Occasionally you will want to add your own settings, and connecting them to environment variables is as simple as using os.environ in your settings.py:

from os import environ

# "Require" a setting by using environ["<name>"]
# (useful if the app cannot operate without it)
A_REQUIRED_SETTING = environ["A_REQUIRED_SETTING"]

# Use environ.get to provide a default value
AN_OPTIONAL_SETTING = environ.get("AN_OPTIONAL_SETTING", "default")

Reference

Name Default Environment Description
SECRET_KEY *required Any Django SECRET_KEY setting
BASE_URL *required Any
DATABASE_URL *required Any Database URL used for Django DATABASES setting
DEBUG False Any Django DEBUG setting
DATABASE_CONN_MAX_AGE 600 Any Database connection max age used for Django DATABASES setting
REDIS_URL Any Redis URL used for Django CACHES setting
DJANGO_SETTINGS_MODULE settings.py Any
CSRF_TRUSTED_ORIGINS [BASE_URL] Any
PYTHON_RUNTIME_VERSION Heroku Heroku Python version
POSTGRES_VERSION 13 Local Postgres version for local dev
RUNSERVER_PORT 8000 Local Port used for Django RUNSERVER setting
NGROK_SUBDOMAIN Local Ngrok subdomain

Email

Name Default Environment Description
EMAIL_HOST Any
EMAIL_PORT 587 Any
EMAIL_HOST_USER Any
EMAIL_HOST_PASSWORD Any
DEFAULT_FROM_EMAIL Any
DEFAULT_FROM_NAME Any
DEFAULT_REPLYTO_EMAIL Any

Sentry (Forge Pro)

Name Default Environment Description
SENTRY_DSN Any Sentry DSN
SENTRY_RELEASE HEROKU_SLUG_COMMIT Any Sentry release tag
SENTRY_ENVIRONMENT production Any Sentry environment tag
SENTRY_PII_ENABLED true Any Send username/email with Sentry errors
SENTRY_JS_ENABLED true Any Enables JS error monitoring (requiers {% sentry_js %} tag too)

Stripe (Forge Pro)

Name Default Environment Description
STRIPE_SECRET_KEY Any Stripe API key
STRIPE_WEBHOOK_SECRET Any Enables webhook signature verification
STRIPE_WEBHOOK_PATH Local Enables stripe listen in forge work and sets STRIPE_WEBHOOK_SECRET

Google Analytics (Forge Pro)

Name Default Environment Description
GOOGLEANALYTICS_MEASUREMENT_ID production