We share the same configuration structure for almost every possible environment.

We use:

  • django-split-settings to organize django settings into multiple files and directories

  • .env files to store secret configuration

  • python-decouple to load .env files into django


If you have some specific components like celery or mailgun installed, they could be configured in separate files. Just create a new file in server/settings/components/. Then add it into server/settings/


To run django on different environments just specify DJANGO_ENV environment variable. It must have the same name as one of the files from server/settings/environments/. Then, values from this file will override other settings.

Local settings

If you need some specific local configuration tweaks, you can create file server/settings/environments/ to server/settings/environments/ It will be loaded into your settings automatically if exists.

cp server/settings/environments/ server/settings/environments/

See version for the reference.

Secret settings

We share the same mechanism for secret settings for all our tools. We use .env files for django, postgres, docker, etc.

Initially, you will need to copy file config/.env.template to config/.env:

cp config/.env.template config/.env

When adding any new secret django settings you will need to:

  1. Add new key and value to config/.env

  2. Add new key without value to config/.env.template, add a comment on how to get this value for other users

  3. Add new variable inside django settings

  4. Use python-decouple to load this env variable like so: MY_SECRET = config('MY_SECRET')

Secret settings in production

We do not store our secret settings inside our source code. All sensible settings are stored in config/.env file, which is not tracked by the version control.

So, how do we store secrets? We store them as secret environment variables in GitLab CI. Then we use dump-env to dump variables from both environment and .env file template. Then, this file is copied inside docker image and when this image is built - everything is ready for production.

Here’s an example:

  1. We add a SECRET_DJANGO_SECRET_KEY variable to Gitlab CI secret variables

  2. Then dump-env dumps SECRET_DJANGO_SECRET_KEY as DJANGO_SECRET_KEY and writes it to config/.env file

  3. Then it is loaded by django inside the settings: SECRET_KEY = config('DJANGO_SECRET_KEY')

However, there are different options to store secret settings:

Depending on a project we use different tools. With dump-env being the default and the simplest one.


We use different django extensions that make your life easier. Here’s a full list of the extensions for both development and production:

Development only extensions:

Further reading

Django admin