Environment variables ¶
The first steps of the Getting Started guide mention creating an .env file.
The sections below outline in more detail the application environment variables that you may want to override, and their purpose. In Azure Container Apps, this is more generally called the “configuration”.
Multiline environment variables
Although Docker, bash, etc. support multiline values directly in e.g. an .env file:
multi_line_value='first line
second line
third line'
The VS Code Python extension does not parse multiline values: https://code.visualstudio.com/docs/python/environments#_environment-variables
When specifying multiline values for local usage, use the literal newline character \n but maintain the single quote wrapper:
multi_line_value='first line\nsecond line\third line'
A quick bash script to convert direct multiline values to their literal newline character equivalent is:
echo "${multi_line_value//$'\n'/\\n}"
Amplitude ¶
Amplitude API docs
Read more at https://developers.amplitude.com/docs/http-api-v2#request-format
ANALYTICS_KEY ¶
Deployment configuration
You may change this setting when deploying the app to a non-localhost domain
Amplitude API key for the project where the app will direct events.
If blank or an invalid key, analytics events aren’t captured (though may still be logged).
Django ¶
DJANGO_ALLOWED_HOSTS ¶
Deployment configuration
You must change this setting when deploying the app to a non-localhost domain
Django docs
A list of strings representing the host/domain names that this Django site can serve.
DJANGO_STORAGE_DIR ¶
Deployment configuration
You may change this setting when deploying the app to a non-localhost domain
The directory where Django creates its SQLite database file and where it creates the uploads folder for file uploads.
Must exist and be writable by the Django process.
By default, the base project directory (i.e. the root of the repository).
DJANGO_DB_FIXTURES ¶
Local configuration
This setting only affects the app running on localhost
A path, relative to the repository root, of Django data fixtures to load when resetting the database.
The file must end in fixtures.json for the script to process it correctly.
By default, benefits/core/migrations/local_fixtures.json.
DJANGO_DEBUG ¶
Deployment configuration
Do not enable this in production
Django docs
Boolean:
true: the application is launched with debug mode turned on, allows pausing on breakpoints in the code, changes how static files are servedfalse(default): the application is launched with debug mode turned off, similar to how it runs in production
DJANGO_LOCAL_PORT ¶
Local configuration
This setting only affects the app running on localhost
The port used to serve the Django application from the host machine (that is running the application container).
i.e. if you are running the app in Docker on your local machine, this is the port that the app will be accessible from at http://localhost:$DJANGO_LOCAL_PORT
From inside the container, the app is always listening on port 8000.
DJANGO_LOG_LEVEL ¶
Deployment configuration
You may change this setting when deploying the app to a non-localhost domain
Django docs
The log level used in the application’s logging configuration.
Defaults to DEBUG when Django is running in debug mode and WARNING otherwise.
By default the application sends logs to stdout.
DJANGO_SECRET_KEY ¶
Deployment configuration
You must change this setting when deploying the app to a non-localhost domain
Django docs
Django’s primary secret, keep this safe!
DJANGO_SUPERUSER_EMAIL ¶
Local configuration
This setting only affects the app running on localhost
The email address of the Django Admin superuser created when resetting the database.
DJANGO_SUPERUSER_PASSWORD ¶
Local configuration
This setting only affects the app running on localhost
The password of the Django Admin superuser created when resetting the database.
DJANGO_SUPERUSER_USERNAME ¶
Local configuration
This setting only affects the app running on localhost
The username of the Django Admin superuser created when resetting the database.
DJANGO_TRUSTED_ORIGINS ¶
Deployment configuration
You must change this setting when deploying the app to a non-localhost domain
Django docs
Comma-separated list of hosts which are trusted origins for unsafe requests (e.g. POST)
HEALTHCHECK_USER_AGENTS ¶
Deployment configuration
You must change this setting when deploying the app to a non-localhost domain
Comma-separated list of User-Agent strings which, when present as an HTTP header, should only receive healthcheck responses. Used by our HealthcheckUserAgents middleware.
Django database ¶
DJANGO_DB_NAME ¶
The name of the database to use for Django.
By default, django.
DJANGO_DB_USER ¶
The username to use when connecting to the Django database.
By default, django.
DJANGO_DB_PASSWORD ¶
The password to use when connecting to the Django database.
Django admin interface ¶
Django docs
The configuration values that can be stored in the application database are managed directly in the Django Admin interface at the /admin endpoint.
Single sign-on authentication is supported by the admin interface using django-google-sso.
These environment variables can be set in your .env file to use certain features in the admin interface locally:
AZURE_COMMUNICATION_CONNECTION_STRING ¶
settings.py
Usage of AZURE_COMMUNICATION_CONNECTION_STRING in Benefits settings
The connection string needed to use an Azure Communication Service for sending emails, such as the one for user password reset. If this variable is not set, the file-based email backend is used.
In deployed instances, this is automatically set by Terraform by referencing the azurerm_communication_service.primary_connection_string attribute.
DEFAULT_FROM_EMAIL ¶
Django docs
The email address used by default in the From: header of outgoing emails.
GOOGLE_SSO_CLIENT_ID ¶
django-google-sso docs
settings.py
Configuration of django-google-sso in Benefits settings
The Google OAuth 2.0 Web Application Client ID.
GOOGLE_SSO_PROJECT_ID ¶
The Google OAuth 2.0 Project ID.
GOOGLE_SSO_CLIENT_SECRET ¶
The Google OAuth 2.0 Web Application Client Secret.
GOOGLE_SSO_ALLOWABLE_DOMAINS ¶
List of domains that will be allowed to create users.
GOOGLE_SSO_STAFF_LIST ¶
List of emails that will be created as staff.
“Staff” refers to Django’s concept of a user with is_staff set to True, which means they can log in, and also to the Cal-ITP Benefits concept of a user who should have a “Cal-ITP staff” level of access to configuration values.
GOOGLE_SSO_SUPERUSER_LIST ¶
List of emails that will be created as superuser.
django-csp ¶
MDN docs
The Mozilla Developer Network has more on Content Security Policy
The HTTP
Content-Security-Policyresponse header allows web site administrators to control resources the user agent is allowed to load for a given page.With a few exceptions, policies mostly involve specifying server origins and script endpoints. This helps guard against cross-site scripting attacks
Strict CSP
Benefits configures a Strict Content Security Policy. Read more about Strict CSP from Google: https://csp.withgoogle.com/docs/strict-csp.html.
django-csp docs
Benefits uses the open source django-csp library for helping to configure the correct response headers.
DJANGO_CSP_CONNECT_SRC ¶
Comma-separated list of URIs. Configures the connect-src Content Security Policy directive.
DJANGO_CSP_FONT_SRC ¶
Comma-separated list of URIs. Configures the font-src Content Security Policy directive.
DJANGO_CSP_FRAME_SRC ¶
Comma-separated list of URIs. Configures the frame-src Content Security Policy directive.
DJANGO_CSP_SCRIPT_SRC ¶
Comma-separated list of URIs. Configures the script-src Content Security Policy directive.
DJANGO_CSP_STYLE_SRC ¶
Comma-separated list of URIs. Configures the style-src Content Security Policy directive.
pgAdmin ¶
Container Deployment configuration
The pgAdmin image exposes some environment variables directly for its configuration. For other configuration settings, the PGADMIN_CONFIG_ environment variable prefix can be used to override any of the configuration options in pgAdmin’s config.py file.
PGADMIN_DEFAULT_EMAIL ¶
The email address used when setting up the initial administrator account to login to pgAdmin.
PGADMIN_DEFAULT_PASSWORD ¶
The password used when setting up the initial administrator account to login to pgAdmin.
PGADMIN_CONFIG_SERVER_MODE ¶
The server mode determines whether pgAdmin is running on a web Server Mode requiring user authentication (true), such as in Azure; or in Desktop Mode, such as for local development, which uses an automatic default login (false).
PGADMIN_CONFIG_MASTER_PASSWORD_REQUIRED ¶
Applicable to Desktop Mode only, the master password used to encrypt/decrypt saved server passwords. Set to false for local development.
psql default connection parameters
For convenience, the environment variables below are set for the psql command to run in the pgAdmin container.
PGHOST ¶
Maps to POSTGRES_HOSTNAME
PGPASSWORD ¶
Maps to POSTGRES_PASSWORD
PGUSER ¶
Maps to POSTGRES_USER
PGSSLMODE ¶
Maps to POSTGRES_SSLMODE
Cloud configuration
The environment variables below only need to be set for Cloud deployments.
PGADMIN_CONFIG_CONFIG_DATABASE_URI ¶
Configuration settings are stored by default in a SQLite database. SQLite does not work well over a network, such as an Azure File Share, thus requiring them to be stored in a Postgres database. In order to use the Postgres server’s database, set this variable to the connection string to the Postgres server that stores the configuration settings.
PGADMIN_LISTEN_PORT ¶
On the pgAdmin Container App using the dpage/pgadmin4:latest image, it is not possible to run pgAdmin without specifying a value greater than 1024 for this variable. Since the container runs as UID/GID 5050, set this to 5050 by convention.
PGSSLROOTCERT ¶
When pgAdmin starts up and sets its configuration settings, sqlalchemy runs and uses this variable. Since the dpage/pgadmin4:latest image has system-provided certifications, set to system to avoid manually adding certifications to the image.
PGADMIN_SETUP_EMAIL ¶
Required when running in Server Mode (PGADMIN_CONFIG_SERVER_MODE=true) to configure authentication. Should be set to the same value as PGADMIN_DEFAULT_EMAIL.
PGADMIN_SETUP_PASSWORD ¶
Required when running in Server Mode (PGADMIN_CONFIG_SERVER_MODE=true) to configure authentication. Should be set to the same value as PGADMIN_DEFAULT_PASSWORD.
PostgreSQL ¶
postgres Docker image docs
The official PostgreSQL Docker image has more on available postgres environment variables
POSTGRES_DB ¶
Used to define a different name for the default database that is created when the image is first started. If it is not specified, then the value of POSTGRES_USER will be used.
POSTGRES_HOSTNAME ¶
The hostname of the (local) PostgreSQL Docker service, which is usually just the name of the service itself (postgres). Or the hostname of a cloud-based PostgreSQL service for e.g. Django to establish a connection.
POSTGRES_PASSWORD ¶
Required to use the (local) PostgreSQL Docker service. It must not be empty or undefined. This environment variable sets the superuser password for PostgreSQL.
POSTGRES_PORT ¶
The port exposed by the (local) PostgreSQL Docker service. Or the port on which to connect to a cloud-based PostgreSQL service.
POSTGRES_SSLMODE ¶
Determines whether or with what priority a secure SSL TCP/IP connection will be negotiated with the PostgreSQL server. In deployed environments, this value needs to be verify-full. For local environments, set to disable.
POSTGRES_USER ¶
Used in conjunction with POSTGRES_PASSWORD to set a user and its password. This variable will create the specified user with superuser power.
reCAPTCHA ¶
reCAPTCHA docs
See the reCAPTCHA Developer’s Guide for more information
reCAPTCHA v3 is a free Google-provided service that helps protect the app from spam and abuse by using advanced risk analysis techniques to tell humans and bots apart.
reCAPTCHA is applied to all forms in the Benefits app that collect user-provided information. Version 3 works silently in the background, with no additional interaction required by the user.
Warning
The following environment variables are all required to activate the reCAPTCHA feature
DJANGO_RECAPTCHA_API_URL ¶
URL to the reCAPTCHA JavaScript API library.
By default, https://www.google.com/recaptcha/api.js
DJANGO_RECAPTCHA_SITE_KEY ¶
Site key for the reCAPTCHA configuration.
DJANGO_RECAPTCHA_SECRET_KEY ¶
Secret key for the reCAPTCHA configuration.
DJANGO_RECAPTCHA_VERIFY_URL ¶
reCAPTCHA docs
URL for the reCAPTCHA verify service.
By default, https://www.google.com/recaptcha/api/siteverify
requests configuration ¶
requests docs
REQUESTS_CONNECT_TIMEOUT ¶
The number of seconds requests will wait for the client to establish a connection to a remote machine. Defaults to 3 seconds.
REQUESTS_READ_TIMEOUT ¶
The number of seconds the client will wait for the server to send a response. Defaults to 1 second.
Sentry ¶
SENTRY_DSN ¶
Sentry docs
Enables sending events to Sentry.
SENTRY_ENVIRONMENT ¶
Sentry docs
Segments errors by which deployment they occur in. This defaults to dev, and can be set to match one of the environment names.
local may also be used for local testing of the Sentry integration.
SENTRY_REPORT_URI ¶
Sentry docs
Collect information on Content-Security-Policy (CSP) violations. Read more about CSP configuration in Benefits.
To enable report collection, set this env var to the authenticated Sentry endpoint.
SENTRY_TRACES_SAMPLE_RATE ¶
Sentry docs
Control the volume of transactions sent to Sentry. Value must be a float in the range [0.0, 1.0].
The default is 0.0 (i.e. no transactions are tracked).