Open edX Custom Theming Tutorial

With comprehensive theming you can completely customize the look & feel of your Open edX instance while also protecting your customizations from being overwritten by future platform upgrades. This tutorial will help you get started on the most common theming tasks like a custom header, footer, logo and adding your Google Analytics tracking code.

How Comprehensive Theming Works

Open edX’s Comprehensive Theming Framework (also known as “Stanford Theming”) provides a powerful and infinitely flexible way for you to tailor your user interface to your unique needs. By leveraging the comprehensive theming framework as opposed to directly editing UI source code you’ll also be able to better manage your customizations and protect your work from the risks of being overwritten whenever you upgrade your Open edX platform.

The basic software pattern for Open edX’s comprehensive theming framework is refreshingly similar to theming systems with which you might already be familiar, such as Drupal and WordPress. In the case of Open edX, the platform ships with a default theme that is preloaded with the standard “Native Build” installation. If no alternative theme is specified, as is the case when you’ve only just installed the platform, then Open edX renders the UI using the files from the default theme. Once comprehensive theming has been enabled then Open edX will first look for files in the custom theme folders, reverting to the files from the default theme only in cases where files were not found in the custom theme folder.

Let’s take a look at this in practice. Suppose the the Open edX web browser needs two files: the logo png file, and the header.html file. Let’s furthermore assume that we’ve modified the logo png file in our custom theme but we’ve made no other changes to the header of our site. Here is how the comprehensive theming system will evaluate these file requests:

The comprehensive theming framework elegantly determines the correct combination of source files using this very simple 2-factor search protocol. Bear in mind however that this evaluation is NOT done on a real-time basis as you might expect. On the contrary, in the case of Open edX the UI files must be compiled, which is a multi-step process that deals with a host of UI related technologies so that at run-time the Nginx web server only has to work with pure HTML, CSS, Javascript and media assets. We’ll look at this in more detail below.

The default theme is enormous, containing nearly 2,000 source files combined between the Learning Management System (LMS) and the Course Management Studio (CMS). Fortunately however you’ll probably only need to modify a dozen or so. The reasoning behind this is pretty simple: the header and footer makeup the bulk of the content areas that most organizations want to customize, and these areas of the platform are rendered with a limited set of source files, as follows:

Lets take a closer look at some of the contents of the default theme files and folders. Take note of the highlighted files as these are the most commonly customized parts of the default theme.

How to Enable Comprehensive Theming

By following this procedure you should be able to enable comprehensive theming working in around one hour. The steps we will complete:

  1. Fork my Github repository edx.custom-theme
  2. Clone the repository to the home folder of your EC2 Ubuntu instance
  3. Edit /edx/app/edxapp/lms.env.json
  4. Compile static assets
  5. Restart the Open edX LMS and CMS
1. Fork my GitHub repository

This repository should save you some time and potential confusion getting everything setup. This repository contains an empty theme, and so it won’t change your UI in any way. However, it does include the correct folder structure as per the framework’s technical requirements. I struggled with this the first time created a custom Open edX theme, which is why i eventually created and began using this template. The repository is located here:

Note: you’ll need to create a free Github account if you don’t already have one.

Once you’ve forked the repository the basic idea is that you’ll manage this like any other software development project. You’ll copy source files from the Open edX default theme into your repository folders, and then permanently manage these files using Github as your source control system and code repository.

2. Clone Repository To Your EC2 Ubuntu Instance

SSH into your Open edX Ubuntu instance and then clone your repository into the home directory. For this tutorial I’m going to use the path to my own original edx.custom-theme repository, so make sure that you edit the path information so that these commands point to your forked repository.

cd ~
git clone       #Change this to YOUR repository
chown edxapp -R edx.custom-theme
chgrp edxapp -R edx.custom-theme
3. Edit /edx/app/edxapp/lms.env.json

Once again, keep in mind that these code samples reference my Github repository rather than your forked repository, so make sure you edit the path data accordingly. This file has around 400 rows of parameter values, and you’ll make edits in three different parts of the file so make sure to take note of the row numbers in the screen shots below.

4. Compile Static Assets

In most cases, the effects of modifying your custom theme will not take effect until you re-compile static assets. The Open edX static asset compilation process is somewhat murky to me, but so far I can confirm that it uses both Webpack and Paver to consolidate static assets into a single location (which incidentally is /edx/var/edxapp/staticfiles/) and then it encodes the files with system-generated filename suffixes, which as best I can tell is a crude way to invalidate client browser caches.

One exception to the re-compilation requirement is Mako templates, which are magically evaluated real-time. AWESOME! 

Take note that this process runs for around 15 minutes, and your Open edX platform will not be available until the process completes. Also be aware that if your theme contains any compilation errors then your Open edX platform will almost certainly break.

The commands to re-compile static assets are as follows:

# update assets as edxapp user
sudo -H -u edxapp bash 
source /edx/app/edxapp/edxapp_env
cd /edx/app/edxapp/edx-platform
paver update_assets lms --settings=aws
paver update_assets cms --settings=aws
5. Restart the LMS and CMS

You have to restart the LMS and CMS for two reasons.  First, you modified the Django environment configuration file lms.env.json and in order for these changes to take effect the file needs to be reloaded, which is most easily accomplished by stopping and re-starting the application. Second, you recompiled static assets, and for reasons entirely unknown to me this necessitates a restart of at least the LMS (but restart both LMS and CMS just to be safe).

# restart edx instance
/edx/bin/supervisorctl restart lms
/edx/bin/supervisorctl restart cms
/edx/bin/supervisorctl restart edxapp_worker:

If you followed the steps correctly then your Open edX platform should be running, but you should not notice any visual changes to the UI. Next you should add a file to your new custom theme and then repeat steps 2 thru 5 to verify that Open edX detects and includes your new file when it renders the UI. Changing the platform logo is a great way to get started. The platform logo file should be saved in the following location in your theme:


I hope you found this helpful. Please help me improve this article by leaving a comment below. Thank you!

By |2018-08-01T18:31:39+00:00August 1st, 2018|Categories: Open edX|0 Comments

About the Author:

Lawrence is a full stack developer specializing in web and mobile development using AngularJS, Ionic, Wordpress and Amazon Web Services. He has worked as a freelance technology consultant since 1999. He earned a BS in computer science and mathematics with minors in physics and English from University of North Texas.

Leave A Comment

This site uses Akismet to reduce spam. Learn how your comment data is processed.