Learn pro tips on how to configure the Open edX platform. This tutorial will help you to better understand the organizational strategy behind the many Open edx  platform configuration files. You’ll also learn about the platform architecture and how the file system is organized.

Summary

Updated January 19, 2021 for the Open edX Koa release.

Open edX is a highly configurable, modular platform. In fact, there are well more than a thousand configuration parameters that you can use to tailor the functionality, behavior and infrastructure plan for your project. With some cursory knowledge of the Open edX platform architecture you’ll be able to use intuition and common sense to find the parameters that you need in order to tailor the platform to your needs. I have attempted to organize this article so that you can grab the information that you need as quickly as possible, only reading as much of the content as you really need to.

Note that this article focuses on “Application Configuration“. That is, how to modify application parameters and feature flags for the LMS and CMS. There are many other aspects of the Open edX platform that are also customizable using the same basic approach. The aspects of Open edX on which I spend most of my time are as follows.

  • Application Configuration

  • Site Theming

  • Horizontal Scaling

  • Nginx configuration

  • Certificate Server Configuration

  • E-commerce setup

A Practical Example

Let’s use the built-in Linux text editor Vim to set the platform display name. If you’re unfamiliar with Vim then this 8-minute video will teach you enough to get through this step of the tutorial.

# Step 1: Edit the LMS configuration file
sudo vim /edx/etc/lms.yml
# Find the parameter, "PLATFORM_NAME: : Your Platform Name Here" 
# located on or around row 465.
# Replace the text "Your Platform Name Here" 
# with a more appropriate name for your Open edX platform.

# Step 2: Reload the LMS configuration parameters.
sudo /edx/app/edxapp/reload_lms_config.sh

# Step 3: Check your work. Open the LMS in a browser window. 
# In the footer of the landing page you should see the text, 
# "© [YOUR NEW PLATFORM NAME]. All rights reserved except where noted. edX, Open edX and their respective logos are registered trademarks of edX Inc."

Pro Tips

1. ) lms.yml has most of what you need. The vast majority of the configuration parameters that you will need are located in the file /edx/etc/lms.yml, so take the time to learn about the contents of this file. lms.yml (and it’s cms.yml counterpart) contains 600 lines of alphabetized parameters that cover topics including: application feature flags, display names, SMTP email configuration and email addresses, connection settings for databases and caches, security passwords, CSRF and CORS parameters, names of browser cookies, custom theming parameters, and more.

2.) Maintain your configuration data offline. Rather than editing files directly on the server with Vim as I’ve shown in the exercise above, I store my configuration data in Github, and I use VS Code on my development workstation to edit the files. This not only gives you control over versions but also allows you the luxury of better real-time syntax checking and color formatting to help you to work better and faster.

3.) Keep it simple. Most likely you can tailor your Open edX platform to your specific needs using only the parameters included in the yaml files in /edx/etc/. Therefore, I’d recommend avoiding any other configuration methodologies and techniques that you might encounter in the official Open edX documentation. It is unlikely that you need to fork the edx/edx-platform repository for example, in which case you definitely do not need to use server-vars.yml. Devstack is not necessary, nor is Vagrant, nor is Docker.

Commonly Modified Files

Aside from custom theming, most of the other work that I do on Open edX projects only involves a dozen or so files. I’m presenting these in order of importance, meaning, the frequency with which I find myself editing each file.

edX platform These are the yaml files located in /edx/etc/, and entail nearly all of the salient content of this article. In addition to configuration files for the LMS and CMS, you’ll also find the main configuration files for e-commerce, discovery and Insights.
Passwords The master passwords file is located in /home/ubuntu/my-passwords.yml and was generated as one of the very first steps of your native build installation process. The native build procedures are coded in Ansible, and the ansible playbooks reference this file dozens of times while building your platform. Note that the password values in my-passwords.yml are really only for your reference. Changing password values in this file is not only a terrible idea, but it also would have no direct affect on any of the Open edX platform nor its subsystems, unless you re-run the respective Ansible playbooks (which you probably should not attempt unless you really, really really know what you’re doing.
Nginx You’ll find one Nginx configuration file per site located in /edx/app/nginx/sites-available/. The files are deftly named. I modify the files “lms” and “cms” in this folder as part of installing SSL certificates to enable https. Less commonly, I also modify these files whenever I’m adding a load balancer.
Django settings Pursuant to section, “Open edX Configuration File Hierarchy” below, I occasionally need to add custom parameters to a platform. Again, this is rare, and you probably will not need to do this. In the case of the LMS, I only ever need to modify /edx/app/edxapp/edx-platform/lms/envs/production.py.

Open edX Configuration File Hierarchy

The LMS and CMS are traditional Python/Django projects and are organized accordingly. Both applications rely on a file named “production.py” that contains the principal application parameters. Consistent with Django best practice, these two applications include a lower level configuration file named “common.py” that contains parameter values that are “common” to various application stages such as “dev”, “test” and “production”.

In the case of Open edX however, we edited the file, “/edx/etc/lms.yml”, which is a practice that is unique to the Open edX project. This approach provides several benefits:

  • For a typical Open edX project, all of the configuration settings are consolidated into a single folder, /edx/etc/, simplifying configuration management.
  • It is not necessary to modify any Open edX platform source code.
  • It provides a more human friendly format — Yaml files in this case — to modify configuration da