Start with the Tutor Distribution of Open edX

The Open edX platform offers a comprehensive learning management system (LMS). Considering you read this manual, you have likely decided to use the self managed over the fully managed LMS option. This manual describes operating and developing Open edX using the Tutor distribution, making it easier to get started. The commands in this blog post are tested using the version 12 release.

The official Tutor logo, source: docs.tutor.overhang.io

As stated on the official website, this distribution is Docker-based. It means that the platform is operated using Docker containers. Inside these containers, the platform services run. Thanks to this approach, manipulation with the Open edX platform is straightforward — from its initial configuration and modification to future upgrading and scaling.

If you are still unsure about the platform choice, navigate the link below to access the demo site.

Concepts - Tutor documentation

Useful Resources 🔎

Tutor Distribution

The relevant source is the official Tutor documentation, as it contains the latest information. It is worth noting that the documentation does not contain version history, so a tool like Wayback Machine is applicable when looking for legacy sections. For example, operation commands that are slightly changed between the Tutor versions can be tracked down.

In addition, the official Tutor Forum frequently covers the information beyond the documentation. It also contains solutions to common problems.

Lastly, the official Tutor GitHub offers valuable information about the project’s current state. It is highly recommended to utilise the git tags. This repository contains tags with all released Tutor versions, so if your system is not updated, you may still obtain the relevant files.

Open edX Platform

The official Open edX documentation is helpful if more platform-oriented changes are necessary. It is worth noting that the described principles might not work in the Tutor distribution. Some Tutor changes have to be done using configuration files or plugins. For more information, refer to the Functional and Visual Modifications section in this manual. The advantage of this documentation is that information for older versions of the Open edX is available there. As mentioned in the section about named releases, its releases are named after trees in alphabetical order.

The official Open edX GitHub is helpful, especially when modifying the platform behaviour. The source of the entire platform that Tutor operates can be accessed here. It is worth noting that it contains git tags, which are, once again, useful when looking for older versions. These tags can be searched for a specific version — for instance, the Maple version has multiple tags, including the maple.1 tag.

It is worth noting that Open edX commands can be run even when using the Tutor distribution. Refer to the local deployment section in the Tutor documentation for more information.

Environment Information 🌳

There are multiple options for the Tutor environment setup presented in the documentation. Before starting the setup, it is worth checking the system requirements there. To work with Tutor, having a UNIX-based OS like Linux is necessary. However, a Windows setup with Windows Subsystem for Linux installed works well. I can confirm it, as I used such a setup for the development.

Installation

To set up the environment, use one of the installation methods from the documentation. It is recommended not to use more than one installation method, as calling Tutor commands through the command-line interface (CLI) would get confusing.

I recommend the Python package or Installing from source, as they have an advantage over the Binary release. The Binary release should be considered either for testing or platforms with minimal modifications, as the plugins cannot be used with this installation option. I chose the Python package out of the remaining two, as the installation and updates feel more intuitive using the packages. Moreover, the older versions of Tutor are simpler to obtain using the packages, as the version can be specified as displayed in the figure below. The choice is up to you, however.

Example of installing older Tutor version using the Python package option

Initialisation

After installation, use the tutor local quickstart in the terminal to initially launch the platform. For other platform runs, the tutor local start is used. Optionally, the --detach option allows it to continue running even after closing the active terminal. To stop it, the tutor local stop is used.

It is also recommended to create a git repository containing the backups of the root directory. This directory contains all data and modifications, and its path can be found by running the tutor config printroot. The root can be optionally changed. To do so, run the export TUTOR_ROOT="<new_path>" with the <new_path> replaced. These changes are not permanent. To permanently change it, add the command to the ~/.profile file and reopen the terminal.

Operation

Tutor supports two modes of running the platform — the before-mentioned production mode and development mode. The latter has an advantage in the form of additional development, logging and debugging tools. This mode also supports a component called watchthemes, which is useful for theme development. Refer to the so-called local and dev documentation for more information about the modes.

The command tutor local start --detach starts the platform in the production mode at local.overhang.io, which masks the localhost, while the tutor dev runserver lms starts the development mode on port 8000. By default, the Studio is not enabled. To run the LMS with Studio, use the tutor dev runserver cms command, starting Studio on port 8001. The mentioned development commands might differ in version 13 onward.

It is worth noting that both modes cannot run simultaneously — in order to stop the unused one, run the tutor local stop or the tutor dev stop.

Structure

Tutor distribution focuses on a clean project structure. The root directory’s contents are used by the Docker containers of the distribution.

It is advised to use a versioning system for tracking its changes. Moreover, it is worth noting that the platform should be stopped when working with platform files. If the operations with git, like switching branches, cause Docker errors, the restart of Docker may be required to resolve it.

The root directory is composed of the following:

• The data folder containing all system data, including the created courses and registered users.
• The env folder generated based on the settings from the config.yml` file. Any manual change made to this folder’s contents is overwritten upon saving changes, so manually modifying its contents is not recommended. This knowledge is crucial for further modifications discussed in the following section.
• The config.yml file containing the specified Open edX settings.
• The self-explanatory README.md.

For more information, refer to the source — the documentation.

Building

In the next part, I focus on platform modifications. To perform platform modifications, it is oftentimes necessary to rebuild the theme to apply changes. The production version is built using the tutor images build openedx, while development uses the tutor images build openedx-dev. It is worth noting that to apply changes in the development mode, it is necessary to run both commands in the stated order. The first build takes tens of minutes, while subsequent builds are a bit faster.

Functional and Visual Modifications 🎨

Open edX offers a variety of modification options, including plugins and themes. Plugins help customise the deployment, as stated in their section in the documentation. Themes are more focused on modifying the visual aspects of the platform, including not only the CSS but also the rendered HTML, which can be altered by modifying the underlying page templates. Below are the concepts further explained.

Plugins

To start working with plugins, refer to the plugin introduction. It is worth noting that their plugin API was significantly reworked recently. My work with the platform involved creating plugins using now so-called Legacy v0 API. The plugins could either be Python packages or YAML files in this API. During my platform development, I chose the latter.

The figure below displays an example of the YAML plugin. This plugin modifies environment settings using patches, altering already rendered platform templates. The advantage of the new API is that the patch names are finally documented. Hence, the works with the source code are no longer necessary to find the patch modification location, as was the case with the version 0 API. If you are interested in the use of plugins, I recommend following the current API documentation.

Example of the plugin using v0 API that disables email validation for new users

Themes

Many aspects of this distribution can be modified using the theme. The advantage of the Tutor theme is that it overrides the original Open edX theme, making it easier to modify the Tutor distribution.

Every developer can create a theme. However, it is easier to use an existing theme and modify it to one liking. One of such themes is Indigo, an official theme by Overhang — the company developing the Tutor distribution. This theme is lightweight, enabling the developer to customise the platform. In this section, I focus on the fundamentals of working with it. To set it up, follow the instructions on the official Indigo GitHub. Do not forget to enable the theme using the tutor local settheme indigo to see the changes.

Modifying Theme Files

In order to modify theme files, navigate to the theme folder, for instance, indigo. It should contain the config.yml file and theme folder.

• The config.yml modifies platform settings. For more information about supported configuration values, visit the CLI reference.
• The theme folder contains all modifications. These modifications are categorised in the cms folder (for Studio) and the lms folder (for LMS). Below are discussed changes made to the lms folder.

Modifying LMS

The indigo/theme/lms folder contains the static and templates folder.

• To modify the images and CSS (or SCSS), focus on the static folder. To customise the platform, the existing images can be easily replaced. Moreover, the existing SCSS files can be modified.
• To modify page templates, focus on the templates folder. The used templates use Mako and Django, along with Python, so it is worth learning about these technologies.

The modification of page templates is arguably more interesting, as it also allows adding custom classes to the existing HTML elements and adding new elements entirely. To modify existing pages, the existing page templates are overridden, which means that the original Open edX files are ignored. It is only necessary to create folders with matching structures so that the relevant files are overridden.

The original Open edX structure, which should be followed, could be seen in their repository. In this repository, it is recommended to select the relevant version by specifying the git tag. For instance, version 12.2.0 is based on lilac.3 tag. After locating the relevant file, which can sometimes be challenging, its contents should be copied and pasted locally into the matching folder structure. After successful addition, its contents can be modified to meet the needs.

Based on this information, the page templates can be combined with plugins as well in order to add new custom pages to the platform.

Propagating Theme Changes

After applying modifications made to theme files, the changes need to be rendered to the env folder. It is not recommended to place the Indigo theme somewhere in this folder, as it would be chaotic. A better approach is to create, for instance, a themes folder in the root directory that will be used to store platform themes. Subsequently, to render changes, the paths mentioned in the render documentation for the tutor config render command need to be modified to point to this folder.

After performing these steps, the platform needs to be rebuilt. If only the development mode is used, I recommend launching the before-mentioned watchthemes component alongside the development server using the tutor dev run watchthemes. This component watches for file changes in the env folder and, upon detecting them, automatically recompiles the necessary files. The main advantage is that it only takes a few seconds to see the changes instead of a couple of minutes. However, this component works only in the development mode — in the production, the build is necessary.

Publishing 🕸️

The steps for setting up the production platform remain the same as the development discussed above, so the setup should be straightforward. As the machine is different from the development one, it is necessary to rerun the tutor local quickstart, where you opt for the production system. To have the platform fully functional, the following records are necessary:

• The custom platform URL (so other than local.overhang.io).
• The subdomain studio.{platform URL} for Studio.
• The subdomain preview.{platform URL} for course previews.

The mentioned quickstart command should be followed by the tutor local init, and after rebuilding the platform image, the platform should be ready.

The initialisation of the Open edX platform

Enjoy the platform! Do not hesitate to contact me for additional information.