Configuration¶

All configuration happens through environment variables.

Django settings¶

These settings map directly to built-in Django settings. An environment variable like DJANGO_FOO controls the Django setting FOO. Not all Django settings are available for configuration.

Note

Default values given refer to Production configurations, which is the default in Docker images.. Other configurations may have defaults not listed here.

DATABASE_URL¶

Default: postgres://postgres@localhost/normandy
Documentation: https://github.com/kennethreitz/dj-database-URL#URL-schema

A database URL, including any username and password, if needed.

DJANGO_ALLOWED_HOSTS¶

Default: Empty string
Documentation: https://docs.djangoproject.com/en/1.9/ref/settings/#std:allowed-hosts

A comma-seperated list of host values to accept. Examples: example.com,www.example.com, .example.com (matches any subdomain of example.com), * (allows everything). This setting is required to be set. If there are other protections (such as load balancers), setting this to * presents no risk.

DJANGO_CONFIGURATION¶

Default: Production
Documentation: http://django-configurations.readthedocs.io/en/stable/

The name of a configuration preset to use for this environment. Useful values are

Production - Preferred
ProductionInsecure - For systems running without HTTPS
Build - This is used during CI to build static assets
Development - This is used by developers
Test - Used during unit tests

DJANGO_DEBUG¶

Default: false
Documentation: https://docs.djangoproject.com/en/1.9/ref/settings/#std:debug

true or false. Enables Django’s debug mode. This should never be enabled on permanent servers. It is inefficient and leaks memory.

DJANGO_MEDIA_URL¶

Default: /media/
Documentation: https://docs.djangoproject.com/en/1.9/ref/settings/#std:media-url

The URL prefix for media files (files uploaded to the service). Both host-relative (/media/) and host-absolute URLs (https://cdn.example.com/) work. Should end in a slash.

DJANGO_SECRET_KEY¶

Required: True
Documentation: https://docs.djangoproject.com/en/1.9/ref/settings/#std:setting-SECRET_KEY

A string used as a seed for security features. This should be the same on all instances that share a database, and should be kept secret. It should be a long, random string. This field is required to be set in most environments.

DJANGO_STATIC_URL¶

Default: /static/
Documentation: https://docs.djangoproject.com/en/1.9/ref/settings/#std:static-url

The URL prefix for static files (files shipped with the service). Both host-relative and host-absolute URLs work. Should end in a slash.

DJANGO_CONN_MAX_AGE¶

Default: 0
Documentation: https://docs.djangoproject.com/en/1.9/ref/settings/#std:setting-CONN_MAX_AGE

Time to hold database connections open in seconds. If set to 0, will close every database connection immediately. Each worker (as controlled by WEB_CONCURRENCY) will have its own connection.

Normandy settings¶

These settings are specific to Normandy. In other words, they won’t be present in other Django projects.

DJANGO_GEOIP2_DATABASE¶

Default: /app/GeoIP2-Country.mmdb

Path to a Maxmind GeoIP Country database.

DJANGO_ADMIN_ENABLED¶

Default: true

For security, Normandy can disable write access. This should be enabled on production servers. Servers with this setting set to false shouldn’t require write access to Postgres.

DJANGO_IMMUTABLE_CACHE_TIME¶

Default: 31536000 (1 year)

Sets the time in seconds immutable objects (such as Action implementations) are cached for with the HTTP Cache-Control header.

DJANGO_NUM_PROXIES¶

Default: 0

The number of proxies between users and Normandy. This is used to parse the X-Forwarded-For header.

DJANGO_RAVEN_CONFIG_DSN¶

Default: None

Optional. The DSN for Raven to report errors to Sentry.

DJANGO_RAVEN_CONFIG_RELEASE¶

Default: None

Optional. The release for Raven to report to Sentry. Automatically set by production Docker images.

DJANGO_AUTOGRAPH_URL¶: The URL where an Autograph server can be reached. If left blank, content signing will be disabled.

DJANGO_AUTOGRAPH_HAWK_ID¶: The pre-arranged ID to use for Hawk authentication with Autograph.

DJANGO_AUTOGRAPH_SECRET_KEY¶: The pre-arranged secret key to use for Hawk authentication with Autograph.

DJANGO_AUTOGRAPH_SIGNATURE_MAX_AGE¶

Default: 604800 (1 week)

Content with signature ages older than this are considered out of date and will be re-signed. The keys used by Autograph to sign content are generally only valid for a few weeks, and have a period of overlap where both the new key and old key are valid. The aim with this setting is to be as long as possible while still guaranteeing that actions will get resigned during the overlap period.

DJANGO_X5U_CACHE_TIME¶

Default: 600 (10 minutes)

The time in seconds to cache the public keys retrieved from x5u URLs when verifying signatures. Set to 0 to disable caching.

DJANGO_X5U_ERROR_CACHE_TIME¶

Default: 5

The time in seconds to cache errors while trying to retrieve public keys from x5u URLs when verifying signatures. Set to 0 to disable error caching.

DJANGO_X5U_REQUEST_TIMEOUT¶

Default: 0.5

The time in seconds to wait to receive a response from the server when requesting x5u URLs to verify signatures. A value of 0 means no timeout.

DJANGO_AUTOGRAPH_X5U_CACHE_BUST¶

Default: Unset

If set, the value will be added to the URL for the x5u certificate chain as a query parameter named cachebust. This is used to force clients to re-fetch the certificate chain in cases where they’re caching an expired or otherwise invalid copy of the chain.

DJANGO_REMOTE_SETTINGS_URL¶

Default: Unset

The URL where a Remote Settings server can be reached (e.g. https://settings-writer.prod.mozaws.net/v1).

If left blank, the publication of recipes will be disabled.

DJANGO_REMOTE_SETTINGS_USERNAME¶

Default: Unset

The account username that is allowed to create records on the Remote Settings collection.

DJANGO_REMOTE_SETTINGS_PASSWORD¶

Default: Unset

The account password to authenticate as DJANGO_REMOTE_SETTINGS_USERNAME.

DJANGO_REMOTE_SETTINGS_CAPABILITIES_COLLECTION_ID¶

Default: normandy-recipes-capabilities

The name of the Remote Settings collection where the recipes will be published.

DJANGO_REMOTE_SETTINGS_BUCKET_ID¶

Default: main-workspace

The name of the Remote Settings bucket where the recipes will be published.

REMOTE_SETTINGS_RETRY_REQUESTS¶

Default: 3

If the Remote Settings server does not return a successful response, the requests will be retried if the specified number is superior to zero.

DJANGO_API_CACHE_TIME¶

Default: 30

The time in seconds to set in cache headers for cacheable APIs. This may be set to 0 in non-production environments to ease testing. In production environments, setting this value too low can be a denial-of-service risk.

DJANGO_API_ROOT_CACHE_TIME¶

Default: 86400 (1 day)

The time in seconds to set in cache headers for cacheable API root endpoints.

DJANGO_API_CACHE_ENABLED¶

Default: True

Controls cache headers for cacheable APIs. If true, API views will send headers indicating that they can be cached according to DJANGO_API_CACHE_TIME. If false, API views will send headers indicating that they should never be cached.

DJANGO_PERMANENT_REDIRECT_CACHE_TIME¶

Default: 2592000 (30 days)

The time in seconds to set in cache headers for permanent redirects.

DJANGO_HTTPS_REDIRECT_CACHE_TIME¶

Default: 2592000 (30 days)

The time in seconds to set in cache headers for permanent redirects to change from HTTP to HTTPS.

DJANGO_LOGGING_USE_JSON¶

Default: True

If this setting is true, standard logging will be output in mozlog format. Otherwise logs will be unstructured.

DJANGO_CSP_REPORT_URI¶

Default: None

Controls the report-uri directive in the Content Security Policy header. Attempts to violate the Content Security Policy are sent by the browser to this URL. See the MDN documentation on report-uri for more info.

DJANGO_CDN_URL¶

Default: None

The URL of a CDN that is backed by Normandy, if one is in use. This is used to enforce that immutable content is routed through the CDN. Must end with a slash (/).

DJANGO_APP_SERVER_URL¶

Default: None

The URL that allows direct access to Normandy, bypassing any CDNs. This is used for content that cannot be cached. If not specified, Normandy will assume direct access. Must end with a slash (/).

DJANGO_USE_OIDC¶

Default: False

If enabled, Normandy will authenticate users by reading a header in requests. The expectation is that a proxy server, such as Nginx, will perform authentication using Open ID Connect, and then pass the unique ID of the user in a header.

Gunicorn settings¶

These settings control how Gunicorn starts, when the default command of the provided Dockerfile is used.

GUNICORN_WORKER_CLASS¶

Default: sync
Documentation: http://docs.gunicorn.org/en/latest/settings.html#worker-class

The worker class to use. Supported options are sync, gevent, and eventlet.

GUNICORN_MAX_REQUESTS¶

Default: 0 (no cycling)
Documentation: http://docs.gunicorn.org/en/latest/settings.html#max-requests

If set to a positive number, after serving this many requests, individual Gunicorn works will be recycled. This can be helpful to avoid potential memory leaks.

WEB_CONCURRENCY¶

Default: 1
Documentation: http://docs.gunicorn.org/en/latest/settings.html#workers

The number of workers to use. Recommended values are in the range of 2-4 x $(NUM_CORES).