How to add a django Configuration Setting

  1. First, determine whether your setting should be a dynamically modifiable django admin model setting instead?  If so, it is stored in a django model and available via the django Admin interface - and not explained in this document.  Since django-admin-model settings do not require code changes when they need to be changed, they are preferable over code-based django settings (the subject of this wiki).  However, code-based django settings should still be used for:
    1. security-sensitive settings
    2. settings that you anticipate will not change (often) for a given openedX deployment: e.g., one-time configuration for storage, external servers, etc.

  2. Determine whether your setting is security-sensitive.
    1. Does it contain a secret key, private key, IP address, etc?
    2. If so, it is an Auth setting.
    3. Otherwise, it is an Env setting.
       
  3. Add your setting to your envs python file so the setting can be read from the environment.  For edx-platform, it would be located in: 
    1. https://github.com/edx/edx-platform/blob/master/lms/envs/aws.py, or
    2. https://github.com/edx/edx-platform/blob/master/cms/envs/aws.py

      MY_SETTINGS = ENV_TOKENS.get('MY_SETTINGS', MY_DEFAULT_VALUE)
  4. Update the playbook for the appropriate role of the edx/configuration repo.
    1. Add a default at the top of the file: https://github.com/edx/configuration/blob/master/playbooks/roles/edxapp/defaults/main.yml

      EDXAPP_MY_SETTINGS: MY_DEFAULT_VALUE
    2. Add a mapping between the ansible name and the name used in your python file.

      MY_SETTINGS: "{{ EDXAPP_MY_SETTINGS }}"
  5.  To provide overrides of your setting for edx.org deployments, update the YAML files in the following locations:
    1. https://github.com/edx/edx-internal/tree/master/ansible/vars
    2. https://github.com/edx/edge-internal/tree/master/ansible/vars
    3. https://github.com/edx/sandbox-internal/tree/master/ansible/vars