Creating and including local settings

Configuration doesn't necessarily need to be complex. If you want to keep things simple, you can work with a single settings.py file for common configuration and use environment variables for settings that should be kept private and not in version control.

Getting ready

Most of the settings for a project will be shared across all environments and saved in version control. These can be defined directly within the settings.py file. However, there will be some settings that are specific to the environment of the project instance, or sensitive and require additional security such as database or email settings. We will expose these using environment variables.

How to do it...

To use local settings in your project, first we must draw values from environment variables for any configurations in settings.py that will differ across environments or that would be a security risk if stored in version control. It is a good practice to be very clear and unique when naming these variables, but also take into account those that already exist in the environment. Some examples follow:

1. Whether or not to use DEBUG mode will generally differ per environment, where debugging would be on in development, but not by default:

# settings.py
DEBUG = False
if os.environ.get('DJANGO_USE_DEBUG'):
    DEBUG = True

2. Similarly, we might want the debug_toolbar to be active in development, or perhaps only in certain situations even then, so we could add it only when necessary:

# settings.py
INSTALLED_APPS = [
    # ...
]
if os.environ.get('DJANGO_USE_DEBUG_TOOLBAR'):
    INSTALLED_APPS += ('debug_toolbar',)

MIDDLEWARE = [
    # ...
]
if os.environ.get('DJANGO_USE_DEBUG_TOOLBAR'):
    MIDDLEWARE += (
        'debug_toolbar.middleware.DebugToolbarMiddleware',)

3. Perhaps we use a SQLite3 database in testing, but a MySQL database in development, staging, and production. Also, in development, the MySQL database might be on localhost, but have its own separate domain in staging and production. Finally, storing the credentials for the connection in any environment is a security risk. We can handle all of these scenarios just as easily with the following updates to settings.py:

# settings.py
DATABASES = {
    'default': {
        'ENGINE': 'django.db.backends.sqlite3',
        'NAME': os.path.join(BASE_DIR, 'db.sqlite3'),
    }
}
if os.environ.get('MYSQL_HOST'):
    DATABASES['default'] = {
        'ENGINE': 'django.db.backends.mysql',
        'HOST': os.environ.get('MYSQL_HOST'),
        'NAME': os.environ.get('MYSQL_DATABASE'),
        'USER': os.environ.get('MYSQL_USER'),
        'PASSWORD': os.environ.get('MYSQL_PASSWORD'),
    }

How it works...

As you can see, the local settings are not directly stored in settings.py, they are rather included via externally defined environment variables and evaluated in the settings.py file itself. This allows you to not only create or overwrite the existing settings, but also adjust the tuples or lists from the settings.py file. For example, we add debug_toolbar to INSTALLED_APPS here, plus its associated MIDDLEWARE, in order to be able to debug the SQL queries, template context variables, and so on.

Defining the values of these variables can be done in one of two ways. In development, we can declare them within runtime commands, as in the following:

$ DJANGO_USE_DEBUG=1 python3 manage.py runserver 8000

This sets the DJANGO_USE_DEBUG variable for this particular process, resulting in DEBUG=True in settings.py as per the examples listed earlier. If there are many variables to define, or the same values will be set every time the server starts, it may be handy to create a reusable script to do so. For example, in the development environment, we can create a dev shell script, such as the following:

#!/usr/bin/env bash
# bin/dev
# environment variables to be defined externally for security
# - MYSQL_USER
# - MYSQL_PASSWORD
# - MYSQL_ROOT_PASSWORD

DJANGO_USE_DEBUG=1 \
DJANGO_USE_DEBUG_TOOLBAR=1 \
MYSQL_HOST=localhost \
MYSQL_DATABASE=myproject_db \
  python3 manage.py runserver 8000

Store the above in a bin directory alongside manage.py in your project, and make sure it is executable, as follows:

$ chmod +x bin/dev

Then, in a terminal, we can now start our development server, with all of the appropriate settings, as in the following:

$ MYSQL_USER=username MYSQL_PASSWORD=pass1234 bin/dev

The resultant runserver command will receive values not only for the MySQL username and password given here, but also all of the variables set in the dev script itself.

See also

• The Creating a virtual environment project file structure recipe
• The Creating a Docker project file structure recipe
• The Toggling the Debug Toolbar recipe in Chapter 11, Bells and Whistles