Settings & Configuration

# manage.py (excerpt) -- wsgi.py and asgi.py contain the same line
os.environ.setdefault("DJANGO_SETTINGS_MODULE", "config.settings.dev")

export DJANGO_SETTINGS_MODULE=config.settings.dev
python manage.py check
python manage.py check --deploy --settings=config.settings.prod   # overrides the variable

from django.conf import settings

if settings.DEBUG:
    ...  # fine: read through the settings object

# from django.conf.settings import DEBUG   # ImportError: settings is an object, not a module
# from config.settings.dev import DEBUG    # wrong: bypasses the defaults and the override mechanism
# settings.DEBUG = True                    # don't mutate settings at runtime (tests excepted)

$ python manage.py diffsettings --settings=config.settings.dev
BASE_DIR = PosixPath('/srv/bookshelf')  ###
DEBUG = True
MAILERS = {'default': {'BACKEND': 'django.core.mail.backends.console.EmailBackend'}}  ###
ROOT_URLCONF = 'config.urls'  ###
SECRET_KEY = 'dev-only-not-a-secret'
SETTINGS_MODULE = 'config.settings.dev'  ###
...

import django
from django.conf import settings

if not settings.configured:
    settings.configure(
        DEBUG=True,
        TEMPLATES=[{"BACKEND": "django.template.backends.django.DjangoTemplates"}],
    )
django.setup()  # required for standalone use; manage.py and the WSGI/ASGI entry points do it for you

from django.template import engines  # noqa: E402

print(engines["django"].from_string("Hello {{ name }}").render({"name": "Bookshelf"}))
print("configured:", settings.configured, "| DEBUG:", settings.DEBUG)

Hello Bookshelf
configured: True | DEBUG: True

from django.test import SimpleTestCase, override_settings


class HostValidationTests(SimpleTestCase):
    """ALLOWED_HOSTS is read on every request (HttpRequest.get_host())."""

    @override_settings(DEBUG=False, ALLOWED_HOSTS=["bookshelf.example.com"])
    def test_unknown_host_is_rejected(self):
        response = self.client.get("/admin/login/", headers={"host": "evil.example.org"})
        self.assertEqual(response.status_code, 400)

    @override_settings(DEBUG=False, ALLOWED_HOSTS=["bookshelf.example.com"])
    def test_known_host_is_served(self):
        response = self.client.get(
            "/admin/login/", headers={"host": "bookshelf.example.com"}
        )
        self.assertEqual(response.status_code, 200)

bookshelf/
  manage.py
  config/
    __init__.py
    settings/
      __init__.py        # empty on purpose
      base.py            # shared by every environment
      dev.py             # DEBUG, console mailer, local SQLite
      test.py            # fast hasher, in-memory database
      prod.py            # secrets from the environment, HTTPS hardening
    urls.py
    asgi.py
    wsgi.py
  shop/                  # the Bookshelf app

# config/settings/base.py -- shared by every environment
from pathlib import Path

# config/settings/base.py -> parents[0]=settings, [1]=config, [2]=project root
BASE_DIR = Path(__file__).resolve().parents[2]

INSTALLED_APPS = [
    "django.contrib.admin",
    "django.contrib.auth",
    "django.contrib.contenttypes",
    "django.contrib.sessions",
    "django.contrib.messages",
    "django.contrib.staticfiles",
    "shop",
]

MIDDLEWARE = [
    "django.middleware.security.SecurityMiddleware",
    "django.contrib.sessions.middleware.SessionMiddleware",
    "django.middleware.common.CommonMiddleware",
    "django.middleware.csrf.CsrfViewMiddleware",
    "django.contrib.auth.middleware.AuthenticationMiddleware",
    "django.contrib.messages.middleware.MessageMiddleware",
    "django.middleware.clickjacking.XFrameOptionsMiddleware",
]

ROOT_URLCONF = "config.urls"
WSGI_APPLICATION = "config.wsgi.application"

TEMPLATES = [
    {
        "BACKEND": "django.template.backends.django.DjangoTemplates",
        "DIRS": [],
        "APP_DIRS": True,
        "OPTIONS": {
            "context_processors": [
                "django.template.context_processors.request",
                "django.contrib.auth.context_processors.auth",
                "django.contrib.messages.context_processors.messages",
            ],
        },
    },
]

LANGUAGE_CODE = "en-us"
TIME_ZONE = "UTC"
USE_I18N = True
USE_TZ = True

STATIC_URL = "static/"
MEDIA_URL = "media/"
MEDIA_ROOT = BASE_DIR / "media"

# config/settings/dev.py -- development: readable, insecure, throw-away
from .base import *  # noqa: F403

DEBUG = True
SECRET_KEY = "dev-only-not-a-secret"  # a throw-away key that is only valid on a developer machine
ALLOWED_HOSTS = []  # with DEBUG=True Django allows localhost, 127.0.0.1 and [::1]

DATABASES = {
    "default": {
        "ENGINE": "django.db.backends.sqlite3",
        "NAME": BASE_DIR / "db.sqlite3",  # noqa: F405
    }
}

MAILERS = {
    "default": {"BACKEND": "django.core.mail.backends.console.EmailBackend"},
}

# config/settings/test.py -- tests: fast and isolated
from .dev import *  # noqa: F403

PASSWORD_HASHERS = ["django.contrib.auth.hashers.MD5PasswordHasher"]  # speed only, never outside tests
DATABASES["default"]["NAME"] = ":memory:"  # noqa: F405
MAILERS = {"default": {"BACKEND": "django.core.mail.backends.locmem.EmailBackend"}}

# config/settings/prod.py -- production: everything sensitive comes from the environment
import os

from .base import *  # noqa: F403

DEBUG = False
SECRET_KEY = os.environ["DJANGO_SECRET_KEY"]  # KeyError at start-up if it is missing: good
SECRET_KEY_FALLBACKS = [
    key for key in os.environ.get("DJANGO_SECRET_KEY_FALLBACKS", "").split(",") if key
]
ALLOWED_HOSTS = os.environ["DJANGO_ALLOWED_HOSTS"].split(",")
CSRF_TRUSTED_ORIGINS = [
    o for o in os.environ.get("DJANGO_CSRF_TRUSTED_ORIGINS", "").split(",") if o
]

DATABASES = {
    "default": {
        "ENGINE": "django.db.backends.sqlite3",  # PostgreSQL in the real deployment, see the databases section
        "NAME": os.environ.get("DJANGO_DB_PATH", BASE_DIR / "db.sqlite3"),  # noqa: F405
    }
}

SECURE_SSL_REDIRECT = True
SECURE_HSTS_SECONDS = 3600  # raise gradually once HTTPS is proven; HSTS is hard to undo
SECURE_HSTS_INCLUDE_SUBDOMAINS = True
SECURE_HSTS_PRELOAD = True
SECURE_CONTENT_TYPE_NOSNIFF = True
SESSION_COOKIE_SECURE = True
CSRF_COOKIE_SECURE = True
SECURE_REFERRER_POLICY = "same-origin"
X_FRAME_OPTIONS = "DENY"

STATIC_ROOT = BASE_DIR / "staticfiles"  # noqa: F405

MAILERS = {
    "default": {
        "BACKEND": "django.core.mail.backends.smtp.EmailBackend",
        "OPTIONS": {
            "host": os.environ.get("DJANGO_EMAIL_HOST", "localhost"),
            "port": int(os.environ.get("DJANGO_EMAIL_PORT", "587")),
            "username": os.environ.get("DJANGO_EMAIL_USER", ""),
            "password": os.environ.get("DJANGO_EMAIL_PASSWORD", ""),
            "use_tls": True,
        },
    },
}

$ python manage.py check
System check identified no issues (0 silenced).

$ DJANGO_SETTINGS_MODULE=config.settings.prod python manage.py check --deploy   # no variables set
...
KeyError: 'DJANGO_SECRET_KEY'

$ export DJANGO_SECRET_KEY="$(python -c 'from django.core.management.utils import get_random_secret_key as g; print(g())')"
$ export DJANGO_ALLOWED_HOSTS=bookshelf.example.com
$ python manage.py check --deploy --settings=config.settings.prod
System check identified no issues (0 silenced).

$ python manage.py test --settings=config.settings.test
Found 9 test(s).
...
OK

# config/settings/env.py -- one settings module for every environment
from pathlib import Path

import environ

from .base import *  # noqa: F403

BASE_DIR = Path(__file__).resolve().parents[2]

env = environ.Env(
    # (cast, default) pairs
    DJANGO_DEBUG=(bool, False),
    DJANGO_ALLOWED_HOSTS=(list, []),
    DJANGO_CSRF_TRUSTED_ORIGINS=(list, []),
    DJANGO_SECRET_KEY_FALLBACKS=(list, []),
)
# Reads BASE_DIR/.env if it exists; real environment variables always win.
environ.Env.read_env(BASE_DIR / ".env")

DEBUG = env("DJANGO_DEBUG")
SECRET_KEY = env("DJANGO_SECRET_KEY")  # no default: ImproperlyConfigured if missing
SECRET_KEY_FALLBACKS = env("DJANGO_SECRET_KEY_FALLBACKS")
ALLOWED_HOSTS = env("DJANGO_ALLOWED_HOSTS")
CSRF_TRUSTED_ORIGINS = env("DJANGO_CSRF_TRUSTED_ORIGINS")

# DATABASE_URL=postgres://user:password@host:5432/dbname   (PostgreSQL)
# DATABASE_URL=sqlite:///db.sqlite3                        (what this page runs)
DATABASES = {"default": env.db("DATABASE_URL", default=f"sqlite:///{BASE_DIR}/db.sqlite3")}
DATABASES["default"]["CONN_MAX_AGE"] = env.int("DJANGO_CONN_MAX_AGE", default=0)

if not DEBUG:
    SECURE_SSL_REDIRECT = env.bool("DJANGO_SECURE_SSL_REDIRECT", default=True)
    SESSION_COOKIE_SECURE = True
    CSRF_COOKIE_SECURE = True

# .env.example -- committed; copy to .env (git-ignored) and fill in. Values are placeholders.
DJANGO_DEBUG=false
DJANGO_SECRET_KEY=replace-me-with-output-of-get_random_secret_key
DJANGO_ALLOWED_HOSTS=bookshelf.example.com,www.bookshelf.example.com
DJANGO_CSRF_TRUSTED_ORIGINS=https://bookshelf.example.com
DATABASE_URL=sqlite:///db.sqlite3

$ DJANGO_SETTINGS_MODULE=config.settings.env python manage.py check          # no .env, no variables
django.core.exceptions.ImproperlyConfigured: Set the DJANGO_SECRET_KEY environment variable

$ cp .env.example .env
$ DJANGO_SETTINGS_MODULE=config.settings.env python manage.py diffsettings | grep -E "^(ALLOWED_HOSTS|CSRF_TRUSTED|SECRET_KEY)"
ALLOWED_HOSTS = ['bookshelf.example.com', 'www.bookshelf.example.com']
CSRF_TRUSTED_ORIGINS = ['https://bookshelf.example.com']
SECRET_KEY = 'replace-me-with-output-of-get_random_secret_key'

$ DJANGO_DEBUG=true DJANGO_SETTINGS_MODULE=config.settings.env python manage.py diffsettings | grep "^DEBUG"
DEBUG = True        # the real environment beat the .env file

import environ

environ.Env.db_url_config("postgres://bookshelf:change-me@db.internal:5432/bookshelf?sslmode=require")
# {'NAME': 'bookshelf', 'USER': 'bookshelf', 'PASSWORD': 'change-me', 'HOST': 'db.internal', 'PORT': 5432,
#  'OPTIONS': {'sslmode': 'require'}, 'ENGINE': 'django.db.backends.postgresql'}

from django.conf import settings
from django.core import signing
from django.core.management.utils import get_random_secret_key
from django.test import override_settings

old_key = get_random_secret_key()
new_key = get_random_secret_key()

# 1. Before the rotation: the old key is SECRET_KEY.
settings.configure(SECRET_KEY=old_key)
token = signing.dumps({"user_id": 42}, salt="bookshelf.demo")
print("verify before rotation:", signing.loads(token, salt="bookshelf.demo"))

# 2. Rotation: new key first, old key moved to SECRET_KEY_FALLBACKS.
with override_settings(SECRET_KEY=new_key, SECRET_KEY_FALLBACKS=[old_key]):
    print("verify during rotation:", signing.loads(token, salt="bookshelf.demo"))
    fresh = signing.dumps({"user_id": 42}, salt="bookshelf.demo")
    print("new tokens are signed with the new key:", fresh != token)

# 3. After removing the fallback: old tokens are rejected.
with override_settings(SECRET_KEY=new_key, SECRET_KEY_FALLBACKS=[]):
    try:
        signing.loads(token, salt="bookshelf.demo")
    except signing.BadSignature as exc:
        print("after the fallback is removed:", type(exc).__name__)

verify before rotation: {'user_id': 42}
verify during rotation: {'user_id': 42}
new tokens are signed with the new key: True
after the fallback is removed: BadSignature

# config/settings/postgres.py -- needs a PostgreSQL server and psycopg[pool]
import os

from .dev import *  # noqa: F403

DATABASES = {
    "default": {
        "ENGINE": "django.db.backends.postgresql",
        "NAME": os.environ.get("POSTGRES_DB", "bookshelf"),
        "USER": os.environ.get("POSTGRES_USER", "bookshelf"),
        "PASSWORD": os.environ.get("POSTGRES_PASSWORD", ""),  # from the secret store, never committed
        "HOST": os.environ.get("POSTGRES_HOST", "127.0.0.1"),
        "PORT": os.environ.get("POSTGRES_PORT", "5432"),
        "CONN_MAX_AGE": 0,  # must be 0 when "pool" is enabled
        "CONN_HEALTH_CHECKS": True,
        "OPTIONS": {
            "pool": {"min_size": 2, "max_size": 10, "timeout": 10},
            "sslmode": os.environ.get("POSTGRES_SSLMODE", "prefer"),
        },
        "TEST": {"NAME": "test_bookshelf"},
    },
}

$ DJANGO_SETTINGS_MODULE=config.settings.postgres python manage.py check
System check identified no issues (0 silenced).

$ DJANGO_SETTINGS_MODULE=config.settings.postgres python manage.py migrate     # psycopg without the pool extra
django.core.exceptions.ImproperlyConfigured: Error loading psycopg_pool module.
Did you install psycopg[pool]?

# config/settings/sqlite_tuned.py
from .dev import *  # noqa: F403

DATABASES = {
    "default": {
        "ENGINE": "django.db.backends.sqlite3",
        "NAME": BASE_DIR / "db.sqlite3",  # noqa: F405
        "OPTIONS": {
            "timeout": 20,  # seconds to wait on a locked database
            "transaction_mode": "IMMEDIATE",  # take the write lock when a transaction begins
        },
    },
    "analytics": {
        "ENGINE": "django.db.backends.sqlite3",
        "NAME": BASE_DIR / "analytics.sqlite3",  # noqa: F405
    },
}

$ DJANGO_SETTINGS_MODULE=config.settings.sqlite_tuned python manage.py shell -c "
from django.db import connections
for alias in connections: print(alias, connections[alias].settings_dict['OPTIONS'], connections[alias].vendor)"
default {'timeout': 20, 'transaction_mode': 'IMMEDIATE'} sqlite
analytics {} sqlite

# config/settings/highlights.py
import os

from django.utils.csp import CSP

from .prod import *  # noqa: F403

CACHES = {
    "default": {
        # Redis in production: "django.core.cache.backends.redis.RedisCache"
        # with "LOCATION": "redis://redis:6379/1" (needs redis-py; not run here).
        "BACKEND": "django.core.cache.backends.locmem.LocMemCache",
        "KEY_PREFIX": "bookshelf",
        "TIMEOUT": 300,
    }
}

LOGGING = {
    "version": 1,
    "disable_existing_loggers": False,
    "handlers": {"console": {"class": "logging.StreamHandler"}},
    "root": {"handlers": ["console"], "level": os.environ.get("DJANGO_LOG_LEVEL", "INFO")},
}

# Content Security Policy (built in since 6.0) -- needs the middleware as well.
MIDDLEWARE = [*MIDDLEWARE, "django.middleware.csp.ContentSecurityPolicyMiddleware"]  # noqa: F405
SECURE_CSP = {
    "default-src": [CSP.SELF],
    "img-src": [CSP.SELF, "data:"],
}

# Only when a proxy that you control sets (and strips) this header.
SECURE_PROXY_SSL_HEADER = ("HTTP_X_FORWARDED_PROTO", "https")

# The load balancer redirects HTTP to HTTPS, so Django does not have to.
SECURE_SSL_REDIRECT = False
SILENCED_SYSTEM_CHECKS = ["security.W008"]  # a documented decision, not an oversight

$ python manage.py check --deploy --settings=config.settings.highlights
System check identified no issues (1 silenced).

# shop/conf.py
from django.conf import settings


def reviews_per_page() -> int:
    """Read at call time, never at import time, so override_settings works."""
    return getattr(settings, "BOOKSHELF_REVIEWS_PER_PAGE", 20)

# shop/checks.py
from django.conf import settings
from django.core.checks import Error, Tags, register


@register(Tags.compatibility)
def check_reviews_per_page(app_configs, **kwargs):
    value = getattr(settings, "BOOKSHELF_REVIEWS_PER_PAGE", 20)
    if not isinstance(value, int) or value < 1:
        return [
            Error(
                "BOOKSHELF_REVIEWS_PER_PAGE must be a positive integer.",
                hint="Set it to e.g. 20 in your settings module.",
                id="shop.E001",
            )
        ]
    return []

# shop/apps.py -- register the check when the app is ready
from django.apps import AppConfig


class ShopConfig(AppConfig):
    name = "shop"
    default_auto_field = "django.db.models.BigAutoField"

    def ready(self):
        from . import checks  # noqa: F401  (importing registers the check)

$ python manage.py check
System check identified no issues (0 silenced).

# with BOOKSHELF_REVIEWS_PER_PAGE = 0 in settings:
$ python manage.py check
SystemCheckError: System check identified some issues:

ERRORS:
?: (shop.E001) BOOKSHELF_REVIEWS_PER_PAGE must be a positive integer.
	HINT: Set it to e.g. 20 in your settings module.

System check identified 1 issue (0 silenced).