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.

NoteĀ thatĀ there is good system documentation located on your Open edX installation Ubuntu file system:Ā /edx/app/edxapp/edx-platform/themes/README.rst, and also in the Open edX OfficialĀ documentation.

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:Ā https://github.com/lpm0073/edx.custom-theme

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.

Update September 24, 2018: Please take note that on my most recent installation of Hawthorn I was unable to compile static assets after cloning the sample theme into my home folder. Instead, I had to move the theme folder to /edx/app/edxapp/edx-platform/themes, where incidentally you’ll find a set of additional preinstalled themes created by the Open edX team. Some of the comments below suggest that others have recently run into this same problem. This problem might work itself out in subsequent releases, so for the time being I’m leaving the original technical instructions unchanged.

cd ~
git clone https://github.com/lpm0073/edx.custom-theme.git       #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.

Update September 24, 2018: Please also take note that if you cloned your theme into /edx/app/edxapp/edx-platform/themes then you’ll need to modify the lms.env.json parameter value “COMPREHENSIVE_THEME_DIRS” accordingly.

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=production
paver update_assets cms settings=production
exit
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:

edx.custom-theme/themes/custom-theme/lms/static/images/logo.png

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

By |2018-10-25T07:51:07+00:00August 1st, 2018|Categories: Open edX|25 Comments

About the Author:

Lawrence is a full stack developer specializing in the Open edX platform, Django, Angular, Ionic, Wordpress and Amazon Web Services. He lives in Puerto Escondido, Oaxaca, Mexico.

25 Comments

  1. Henry Vermont November 26, 2018 at 6:41 pm - Reply

    Thanks for your wonderful blog, Lawrence. It has been a life saver.
    There seems to be an error on this post, though. The recompile static assets box above shows:
    paver update_assets lms settings=production
    Should it not be one of these?
    paver update_assets lms –settings=production
    or perhaps
    paver update_assets lms –settings=aws

    • admin November 27, 2018 at 5:39 am - Reply

      hi henry, i’m glad the article helped. yes, you’re correct. the web server keeps cutting the hyphens off the command :/

  2. Chris November 22, 2018 at 4:54 am - Reply

    Hi Lawrence,

    No need to compile static assets to enable comprehensive theme. It just works once you restart LMS. I only edited *.html file and once I restart LMS those changes were reflected.
    I still have error when I compile static assets, not sure what is the problem, even though no changes applied to any file. I have also moved the theme to /edx/app/edxapp/edx-platform/themes/

    • admin November 22, 2018 at 5:48 am - Reply

      often the problem is a syntax error in one or more of your scss files. regardless, you’ll find meaningful debugging information in the screen output.

      • Chris November 22, 2018 at 7:44 am - Reply

        Hi Lawrence, I copied the theme directly from your github and without any changes.

        • admin November 22, 2018 at 9:10 am - Reply

          you need to read the screen output to determine the source of your problem. if you want you can pipe it to an output file and email it me, and i’ll take a look.

          • Chris November 22, 2018 at 7:51 pm

            Thank you Lawrence for your kindness. I tried to do the following step:
            1. assign r+w access to custom theme directory
            sudo chmod -R u+rw /my-open-edx-themes

            2. add additional option to paver command as follow ( adding –watch )
            paver update_assets lms –settings=production –theme-dirs=/edx/app/edxapp/edx-platform/themes/edx.custom-theme/ –watch

            It shows this success message:
            Successful compilations:
            — “common” sass files.
            — lms sass for system.

            Then it doesn’t show error message for maybe 7-8 minutes. At the end of execution, it shows this error :
            python manage.py cms –settings=production print_setting STATIC_ROOT 2>/dev/null
            /bin/sh: 1: /webpack: not found

            But the change that I made to favicon.ico is reflected in the LMS after I restart lms. Does it mean my compilation successful?

  3. John Bowling November 3, 2018 at 11:44 am - Reply

    Hi Lawrence,

    I reset my instance of open edx back to the state after enabling SMTP and still encounter the build failure when I try to rebuild the themes. I have not put anything into the themes folder. I did edit lms.env.json and cms.env.json to use the red-theme.

    john

  4. Eduardo November 1, 2018 at 12:45 pm - Reply

    Hi!!

    In this moment i have the same problem of Chris, i was move to edx/app/edxapp/edx-platform/themes but doesn’t work!! please help me!!

    • admin November 1, 2018 at 2:02 pm - Reply

      when compiling assets there is a lot of screen output. you need to review this carefully. most likely you have a syntax error in your Sass files (at least, that tends to be the case for me). if there are any other problems then you’ll find some error messaging in your screen output.

  5. Spurgeon October 12, 2018 at 7:47 am - Reply

    Awesome!! Thank you!

  6. Yafet Getachew October 12, 2018 at 1:38 am - Reply

    Hi Lawrence,
    Wondering if there’s a way to compile assets for a specific theme and not all the themes (I’m using multiple themes for multiple microsites)

  7. Yafet Getachew October 11, 2018 at 10:13 pm - Reply

    Hi Lawrence, enjoying your blogs .. Very helpful. I use custom themes on different microsites, is there a way to compile a specific theme and not all of em? Thanks

    • admin October 12, 2018 at 7:10 am - Reply

      hi Yafe, great question. unfortunately no. Hawthorn includes several example themes which, if you’re not using them, you can delete to speed up the process somewhat.

  8. techmac October 10, 2018 at 12:16 pm - Reply

    what will be th epassword for edxapp user

    • admin October 10, 2018 at 12:25 pm - Reply

      no password is required if you use the following command: sudo -H -u edxapp

  9. baraa October 2, 2018 at 12:21 am - Reply

    Hi Lawrence,
    thanks for your post.
    i face the same problem as Mario
    when i finish pavar i get some files lms-main-v1-rtl.css,lms-main-v1-rtl.css not found error in the browser console.

    i sovled it by add another link tag to the correct path
    “/static/css/lms-main-v1-rtl.css”

    the wrong one was
    “css/lms-main-v1-rtl.css”

    but of course this is not a solution this is a work around
    any suggestion for a real solution?

  10. Mario September 27, 2018 at 1:47 am - Reply

    Hi Lawrence,

    thanks for your post.
    I tried do what you say on my native installation, but without any success.
    After paver compilation, apparently without any errors but with many warnings, when I access the lms I get a lms-main-xxxx.css not found error in the browser console.

    Do you have any suggestion?

    Thanks
    Mario

    • admin September 27, 2018 at 6:20 am - Reply

      hi mario. Paver generates several dozen deprecation warnings. these are normal. however, file not found error makes me wonder if maybe you have compilation error(s) in your scss files?

  11. Chris September 23, 2018 at 6:43 pm - Reply

    Hi Lawrence,

    I followed the steps but I failed during this step to call paver:
    paver update_assets lms –settings=aws

    The error message is just like this:
    Build failed running pavelib.assets.update_assets: Subprocess return code: 1

    What did I do wrong? Thanks

  12. Chris September 23, 2018 at 3:11 am - Reply

    hi Lawrence,

    When I ran this command: paver update_assets lms –settings=aws

    It gives me this error below. I don’t use AWS to install it but another cloud.

    Build failed running pavelib.assets.update_assets: Subprocess return code: 1

    I have removed –settings=aws but the error still the same. What could have been gone wrong?

    • admin September 23, 2018 at 10:29 am - Reply

      Hi chris, the message, “Build failed running pavelib.assets.update_assets” means that the Paver / Webpack process encountered errors within your theme files. themes are tricky to trouble-shoot since the Paver process takes so long to run; usually 10 minutes or so on most builds. I’d suggest that you strip down your theme theme to the bare minimum and then gradually add files / assets, recompiling assets until you isolate your problem. good luck!!

      • Chris September 23, 2018 at 6:45 pm - Reply

        Hi Lawrence,
        o it
        The theme that I used was the one that I forked from your github. I haven’t added anything to it, so it was the first time I ran it.

        • admin September 24, 2018 at 4:32 am - Reply

          ok. try this: move the theme files to /edx/app/edxapp/edx-platform/themes/. don’t forget to modify the path in the array parameter, “COMPREHENSIVE_THEME_DIRS” accordingly. i had to do this on my most recent hawthorn installation. if that still does not work then temporarily disable comprehensive theming by setting ENABLE_COMPREHENSIVE_THEMING = false and then attempt to compile static asset one more time, just to verify that it works with your default installation.

          • Chris October 25, 2018 at 2:06 am

            Hi Lawrence, moving to edx/app/edxapp/edx-platform/themes does work! Also –settings=aws has been deprecated, replace with this one : –settings=production

Leave A Comment

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