Quickstart

Installation

The package can be installed from PyPI using pip:

pip install django-setup-configuration

Configuration

See Configuration Documentation.

Command usage

To automatically configure your application, this library provides the command line tool setup_configuration to assist with this configuration by loading a YAML file in which the configuration information is specified.

src/manage.py setup_configuration --yaml-file /path/to/your/yaml

You can get the full command documentation with:

src/manage.py setup_configuration --help

Warning

This command is declarative - each step is idempotent, so it’s safe to run the command multiple times. The steps will overwrite any manual changes made in the admin if you run the command after making these changes.

The command accepts a single YAML file that contains configuration in a separate namespace for each configuration step the application provides. Individual steps can be enabled or disabled by setting the corresponding _enable flag to true or false.

This YAML file could look something like this:

sites_config_enable: true
sites_config:
  items:
  - domain: example.com
    name: Example site
  - domain: test.example.com
    name: Test site
other_config_enable: false
other_config:
  items:
  - ...

You can validate your config file, without actually executing any of the steps, by using the the validate-only flag:

src/manage.py setup_configuration --yaml-file /path/to/your/yaml --validate-only

The command will report any validation errors on raise a non-zero exit code if the yaml file cannot be loaded. Note that this check only verifies that the yaml file is well-formed, i.e. that it has the required shape and that all values are of the correct type. Whether or not the values are correct will only be known when actually executing the steps.

Integrating with deployment

One way of integrating setup_configuration into your deployment is by adding an extra container that runs a script that executes the setup_configuration command. This container requires a volume to mount the YAML file.

web-setup-config:
  image: <docker-image>
  environment: *web_env
  command: /setup_configuration.sh
  volumes:
  - ./path/to/config.yaml:/app/config.yaml
  - ./path/to/setup_configuration.sh:/setup_configuration.sh
  depends_on:
  - db
  - redis

Example of setup_configuration.sh:

#!/bin/bash

# setup initial configuration using environment variables
# Run this script from the root of the repository

set -e

# Figure out abspath of this script
SCRIPT=$(readlink -f "$0")
SCRIPTPATH=$(dirname "$SCRIPT")

# wait for required services
${SCRIPTPATH}/wait_for_db.sh

src/manage.py migrate
src/manage.py setup_configuration --yaml-file config.yaml