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:
- Update JSON config like
In tutorial about custom theming, it said we have to update
/edx/app/edx_ansible/server-vars.yml then re run provisining script
In tutorial about setting up mobile application, it said we need to update
edx/app/edxapp/lms.env.json then restart the server with
In tutorial about enabling course prerequisites, we need to
Set the value of MILESTONES_APP in the /cms/envs/common.py and /lms/envs/common.py files to True
Then run database migration with (see here for how to manage Open edX full stack):
1 2 3 4
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.
- common.py – 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.
- aws.py – this file basically executes after common.py, and inspects the environment, including the json files in (
lms.env.jsonand others) to see if some default should be modified.
- devstack.py – builds on top of aws.py, changing any settings as appropriate so that it may run on development servers, and locally.
So now we have link between updating
envs/aws.py (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/aws.py 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
It will create a four JSON config files:
1 2 3 4
Those json files is then read when
aws.py 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 (
aws.py 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
aws.py 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
aws.py (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
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.