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 the .env file (this is included in .gitignore by default):

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")

Available environment variables

Name Default Environment Description
SECRET_KEY *required Any Django SECRET_KEY setting
BASE_URL *required Any
DJANGO_SETTINGS_MODULE settings.py Any
DEBUG False Any Django DEBUG setting
CSRF_TRUSTED_ORIGINS BASE_URL Any Split on whitespace if multiple origins

Local development

Name Default Environment Description
RUNSERVER_PORT 8000 Local Port used for Django RUNSERVER setting
NGROK_SUBDOMAIN Local Ngrok subdomain

Heroku

Name Default Environment Description
PYTHON_RUNTIME_VERSION Heroku Heroku Python version

Database

Name Default Environment Description
DATABASE_URL *required Any Database URL used for Django DATABASES setting
DATABASE_CONN_MAX_AGE 600 Any Database connection max age used for Django DATABASES setting
POSTGRES_VERSION 13 Local Postgres version for local dev

Caching

Name Default Environment Description
REDIS_URL Any Redis URL used for Django CACHES setting
REDIS_SSL_CERT_REQS required Any Redis SSL certificate requirements used for Django CACHES setting (can set to none in Heroku production Redis)

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 Only works with TemplateEmail
DEFAULT_REPLYTO_EMAIL Any Only works with TemplateEmail

Logging

Name Default Environment Description
DJANGO_LOG_LEVEL INFO Any Log level for the django logger
APP_LOG_LEVEL INFO Any Log level for the app logger