Local Settings Philosophy

The ready-made Artshow Jockey project has an unusual layout for using settings. This page details the philosophy behind that.

Most Django functionality is distributed as an "app", which is really just a Python package with few additional requirements so that the Django framework can find key components. These app/packages can be installed anywhere into the python path, such as in site-packages, or in the top-level directory for the Django project.

However, this distribution method requires the administrator to follow the process of starting a Django project (startproject), and then making all the necessary settings.py adjustments to meet the requirements of all the app/packages.

A faster way is to distribute a complete (or nearly so) package, with the project created, the customised app/packages already included, and a list of additional packages that need to be installed (using pip, for example). Artshow Jockey has been distributed this way, but in a way that does not preclude an administrator using the "start from scratch" method.

The Problem

Every Django project includes a file called settings.py that includes a bunch of customisation, including a list of apps/packages that Django needs to examine and activate, plus a bunch of app-specific settings. However, certain settings are installation specific, such as the name of the database, and directory names. This is very likely going to differ from installation to installation.

However, most settings will stay the same, and it is useful for the static settings to be checked into the source repository, so that future updates to the code will have necessary new, or updated, settings reflected in the checkout. However, if both the source repository and the administrator are making changes to settings.py, merge problems will occur.

The Solution

Settings that are unlikely to change between installations are kept in settings.py. However, we've renamed this to common_settings.py so that any code improperly importing this directory, rather than using from django.conf import settings, will fail. common_settings.py is checked into the repository so that updates to the code, such as adding additional features, will automatically have the required settings added, too.

An additional file called local_settings.py is required that the administrator is expected to examine and change. local_settings.py imports from common_settings.py, and manage.py and wsgi.py are updated to use local_settings as their DJANGO_SETTINGS_MODULE.

local_settings.py is not checked in, but a local_settings.py.example is created to act as an easily-modifyable template.

This way the entire Django project can be checked out, or copied and moved around, without worrying that a future "pull" from the source repository will overwrite local changes, and that every installation is configured appropriately.

A Reminder

This only applies if the administrator is using Artshow Jockey as a standalone project. If they've created their own project, and using the apps supplied, then the normal Django configuration rules apply. But the above has been so useful, when working with multiple installations (eg: a desktop test system verses beta system verses production system), the author highly recommends mimicking it.