nativeInstalleredx

Enable and apply a custom theme

Before running the commands shown on this page, you should load the Bitnami stack environment by executing the installdir/use_APPNAME script (Linux and MacOS) or by clicking the shortcut in the Start Menu under “Start -> Bitnami APPNAME Stack -> Application console” (Windows). On OS X VMs, the installation directory is /opt/bitnami and OS X VM users can click the “Open Terminal” button to run commands. Learn more about the Bitnami stack environment and about OS X VMs.

In order to enable and apply custom themes for edX, you need to follow these steps in the sequence shown:

Enable a custom theme

  • Place your theme in the installdir/apps/edx/var/themes directory (example).
  • In order to enable a custom theme for LMS, modify the installdir/apps/edx/conf/lms.env.json file and apply the following changes (example):

    • Set ENABLE_COMPREHENSIVE_THEMING to “true”.
    • Add the absolute path of the themes directory to the COMPREHENSIVE_THEME_DIRS configuration property array.
  • In order to enable a custom theme for CMS, modify the installdir/apps/edx/conf/cms.env.json file and apply the following changes (example):

    • Set ENABLE_COMPREHENSIVE_THEMING to “true”.
    • Add the absolute path of the themes directory to the COMPREHENSIVE_THEME_DIRS configuration property array.

Example settings for an edX theme

Custom theme folder structure

Themes should have the following folder structure:

-installdir/apps/edx/var/themes
  |-my-custom-theme/
    |-cms/
      |-static/
      |-templates/
    |-lms/
      |-static/
      |-templates/

Custom theme configuration

The lms.env.json and cms.env.json configuration files should contain the following:

"COMPREHENSIVE_THEME_DIRS": [
    "installdir/apps/edx/edx-platform/themes",
    "installdir/apps/edx/var/themes"
],
...
"ENABLE_COMPREHENSIVE_THEMING": true,

Apply a custom theme

  • Access the Django administration console. Check the Django Admin Console instructions for more information.
  • Browse to “Theming -> Site themes -> Add site theme”.
  • From the “Site menu”, select the site you want to apply a theme to.
  • Enter the identifier of the theme (same as its directory name) and click on “Save”.

    Add site and theme

    The theme will be enabled for the specified site as it shown below:

    Theme enabled

Build assets for a custom theme

The steps below are only needed for releases older than Open edX Ironwood.1 (e.g. Hawthorn, Ginkgo, etc.):

  • If you enabled the custom theme for LMS, update LMS assets:

    $ sudo installdir/apps/edx/bin/edxapp-update-assets-lms
    
  • If you enabled the custom theme for CMS, update CMS assets:

    $ sudo installdir/apps/edx/bin/edxapp-update-assets-cms
    
  • Restart the Apache server:

    $ sudo installdir/ctlscript.sh restart apache
    
Last modification April 12, 2019