Infinite | Squares

Art of code and more

Customizing Open edX - Settings

After finished OpenEdX installation we need to modify some settings to change text, logo and activate some functionality: changing site name, using third party auth and many others. This is where things are a bit confusing because some documentations use different approach.

Ways to update Open edX settings

When reading several Open edX documentation, I found there are several methods to update Open edX settings:

  1. Update server-vars.yml at /edx/app/edx_ansible/server-vars.yml
  2. Update JSON config like lms.env.json or cms.env.json in /edx/app/edxapp
  3. Change *.py files in /edx/app/edxapp/edx-platform/cms/envs or /edx/app/edxapp/edx-platform/lms/envs

In tutorial about custom theming, it said we have to update /edx/app/edx_ansible/server-vars.yml then re run provisining script

sudo /edx/bin/update edx-platform master

In tutorial about setting up mobile application, it said we need to update edx/app/edxapp/lms.env.json then restart the server with

sudo /edx/bin/supervisorctl restart edxapp:

In tutorial about enabling course prerequisites, we need to

Set the value of MILESTONES_APP in the /cms/envs/ and /lms/envs/ files to True

Then run database migration with (see here for how to manage Open edX full stack):

# sudo su edxapp -s /bin/bash
# cd ~
# source edxapp_env
# python /edx/app/edxapp/edx-platform/ {lms/cms} syncdb --migrate --settings aws

Now, do all the methods is related? And what is recommended approach?

How Open edX read settings

Open edX app (CMS and LMS) both has envs folders consisted to several *.py files. Those files are there to provide default sane settings in case you as the developer or admin did not provide customized settings. That is usually the case when we start exploring Open edX (either dev-stack or full-stack installation).

We only need to pay attention to two files if you deploy full-stack like me. If you working on dev-stack there is one setting file for that environment too.

  1. – contains default settings, so that reasonable things happen; this way a default setting just for django does not need to appear in a playbook. Rule of thumb: Never change these, unless you are doing new application/component development, and you are setting a new reasonable default for your component.
  2. – this file basically executes after, and inspects the environment, including the json files in (lms.env.json and others) to see if some default should be modified.
  3. – builds on top of, changing any settings as appropriate so that it may run on development servers, and locally.

So now we have link between updating envs/ (3rd method) and *.json (2nd method). In general changes to *.json will be read and used to override default setting from

In case you notice, in database migration command above we passed parameter --settings aws which indicate that we want to use envs/ as our settings.

Now, how it all connected to the server-vars.yml (1st method)? it turns out that *.json files is generated from server-vars.yml during ansible playbook process.

When we run our ansible install commands

# cd /var/tmp/configuration/playbooks && sudo ansible-playbook -c local ./edx_sandbox.yml -i "localhost,"

It will create a four JSON config files:


Those json files is then read when is loaded.

Working with settings

For the full list of settings that you can override in server-vars.yml check here. If you see main.yml file in previous link, there are more than 100 settings that you can tweak and set. We can pick one of the three methods above for development while we learn about Open edX and make sure those settings working as we expected.

For initial development purposes, we can start with creating our own settings file or modifying the one that used by default ( in case of full stack install as we have) to experiment and determine what works. This is fast because we only need to restart the app after settings update.

Or we can start with modifying JSON file in /edx/app/edxapp/*.json and check in that the variable is read (if not, make sure that happens, and send in a Patch Request to contribute to Open edX). This is also fast because we only need to restart the app after settings update.

For long-term development purposes, it is better if we use server-vars.yml and to ensure that each variable is actually read in by (if not, make sure that happens, and send in a Patch Request to contribute to Open edX). server-vars.yml will then be read and used by the update command. Note that update command will run ansible playbook and it can take a while. Also if you updated your Open edX with the latest code from git, both JSON config files and envs folder will be reset. So its better to use server-vars.yml.

I am still learning Open edX and if you find any errors or have question or suggestion, please let me know.

Next, we will continue on customizing settings on our Open edX instance to enable third party auth and many others.