Learn how to install an Open edX XBlock code extension with this detailed step-by-step how-to guide. This step-by-step guide works for any XBlock. Let’s get started!

Summary

XBlock is the extensibility framework for Open edX. That is, it’s a framework that allows the open source software development community to extend and enhance edX to meet future needs. If you’re familiar with the content management system WordPress then, architecturally speaking, XBlocks are nearly identical to plugins. ExtensionEngine wrote this great blog article on XBlocks. However, a big difference between WordPress plugins and XBlocks is that installing them is a murky process. In this blog post I set out clarify and simplify the exact steps that are required to install any XBlock.

For this tutorial we’ll install a really cool XBlock named In-Video Quiz which, as the name implies, will abruptly pause a video to present the student with a problem. This XBlock was written by the Open edX programming team at Stanford University and is freely available on GitHub (https://github.com/Stanford-Online/xblock-in-video-quiz). Like many XBlocks that I’ve installed, the functionality works great, but the documentation is sparse. So, the In-Video Quiz is a great example for this blog post.

Before moving on I’ll point out a couple of things that might weigh on your installation choices. First, you can install XCode packages anywhere in your Ubuntu server. References to the code are bound during the automated installation process. But having said that, I would recommend that you NOT install XCode packages anywhere inside of the /edx subdirectory simply because doing this can complicate future platform software upgrades. That is, if you install you XBlock packages anywhere inside the /edx subdirectory, it might get overwritten during a future upgrade of any part of the Open edX platform.

Implementation Steps

  1. Clone the GitHub repository of the XCode package into your Ubuntu instance.
  2. Change ownership of the cloned repository to edxapp
  3. Run the pip installation program
  4. Manually compile Open edX assets
  5. Restart the LMS and CMS
  6. Enable The XBlock In Your Course

Assumptions

  • Your Open edX instance is running from an AWS account
  • Your AWS EC2 instance is running on an Ubuntu 16.04 LTS server built from the Amazon Linux AMI
  • You have SSH access to your EC2 instance and sudo capability
  • You are generally familiar with GitHub packages (you’ve at least heard of them)
  • Your Open edX instance is substantially based on the guidelines published here: Native Open edX Ubuntu 16.04 64 bit Installation

1. Clone The GitHub Repository of the XBlock Package

Like Open edX itself, XBlocks are written in Python, and while I’m not a Python programmer myself, I will say that I’ve observed that the Python programming community tends to have a preferred way to do everything; and that includes for example, how Python programs should be installed. That being the case, a lot of Python programs (or all of them?) are stored as raw source code which one downloads in packages from repository platforms like GitHub to be compiled on the server using a variety of Python-specific installations tools. In the case of Open edX the preferred route seems to be a command line utility named pip (Python Installation Program). I’m a Python neophyte, just so you know. But regardless, pip is pretty awesome, and pretty stupid-proof.

All of this matters because XBlocks are written in Python and, as it happens, thanks in no small measure to the peculiarities of the Python community, there’s one single method of installation that works for all XBlocks. First, we need to clone the GitHub repository where our In-Video Quiz is stored. I can almost always find the GitHub repository by using Google. Once you find the repository, GitHub provides a 1-click way to copy the exact http URI of the repository, which we’ll use on the command line of our Ubuntu instance. Refer to the following screen shot for the location of the 1-click copy method:

Afterwards, paste the URI of the repository onto the command line so that you have a command line that looks like the following:

$ cd ~
$ git clone https://github.com/Stanford-Online/xblock-in-video-quiz.git

2. Change Ownership of the Repository directory in Ubuntu

Cloning the GitHub repository simply means copying all of the files (and whatever else might be in the repository like say, images, mp3s, etc) to your Ubuntu file system.

I clone repositories into the Ubuntu home folder /home/ubuntu/ where I also store any and all other Open edX configuration files and scripts. However, feel free to clone the repository to whatever location in your file system you prefer as this (within reason) has no bearing on the installation process.

Once you’ve cloned the repository you’ll also need to change the folder ownership and group to edxapp. This is because we’ll install the code using the edxapp user, and if the source code itself doesn’t reside in a folder that’s owned by this user then the pip installation program will potentially complain.

$ sudo chown -R edxapp xblock-in-video-quiz
$ sudo chgrp -R edxapp xblock-in-video-quiz

3. Run the pip Installation Program

This is where the magic happens. We’re going to use pip (Python Installation Program) to install our XBlock. Python programmers are a thorough bunch. They not only think about their code’s functionality, but also the code dependencies of their code, and even the version compatibility. Ultimately, pip does all of this for us. Therefore, the specifics on how to run pip might seem underwhelming, but here it is:

(October 2018) Note: Beginning with the Hawthorn release some of the Open edX installations that I support will only allow me to store Xblock executable files inside of /edx/app/edxapp/edx-platform/. So, if the commands below generate an installation error such as, unrecognized requirement ... is XXX a path?, then consider changing the local installation location of your Xblock files.
# To install the xblock:
sudo -H -u edxapp bash
source /edx/app/edxapp/edxapp_env
/edx/bin/pip.edxapp install /home/ubuntu/xblock-in-video-quiz

# To uninstall the xblock (in the event of problems):
/edx/bin/pip.edxapp list     #then look for the registered name of the Xblock. 
                             #In this example the Xblock name is, "invideo-quiz (0.x.x)"
/edx/bin/pip.edxapp uninstall THE-REGISTERED-NAME-OF-THE-XBLOCK-TO-UNINSTALL

We now find ourselves in one of those, “the proof is left to the reader” moments. :/

4. Manually Compile Assets

It’s virtually assured that your XBlock will not yet work, even if the pip installation package reported that it installed successfully. That is because farther up the technology stack of Open edX there is more work to do that resides far beyond the purview of pip. Namely, we need to manually compile the Open edX assets. I’ll probably write a blog post about what this means since the need do this seems to arise so often. For now however, just do the following:

$ sudo -H -u edxapp bash
$ source /edx/app/edxapp/edxapp_env
$ cd /edx/app/edxapp/edx-platform
$ paver update_assets cms --settings=aws
$ paver update_assets lms --settings=aws

If this is your first time to manually compile assets that be aware that the process will take around 10 minutes to complete, and meanwhile, your Open edX platform will be offline to your teachers and students.

5. Restart the LMS and CMS

Any time you manually compile assets, you’ll also need to restart the LMS and CMS. The command lines to do this are as follows:

$ sudo /edx/bin/supervisorctl restart edxapp:
$ sudo /edx/bin/supervisorctl restart edxapp_worker:

This process takes around five minutes to complete. Meanwhile your teachers and students will not have access. Note that you can use the Linux command line “top” to view the progress of the restart process.

$ top

I confess that this is not particularly scientific, but, the following three screen shots demonstrate how to monitor and detect the precise state of your Open edX platform. Importantly, using “top” will enable you to know whether your Open edX platform is available to your users.

Shutting Down
Restarting
Running Normally

6. Enable The XBlock In Your Course

Adding your XBlock to a course involves four steps, three of which are standard with the latter two steps varying slightly depending on design choices made by the XBlock programmer. All of these steps are performed from within the Course Management Studio Application.

  1. Select the course which you want to install the XBlock. You need to have edit rights for the course.
  2. Choose “Configuration / Advanced Configuration” from the Course Studio menu bar
  3. Scroll to near the bottom of the next screen until you find “XBlocks”. You include the XBlock in your course by adding it’s technical name to a JSON array in this field. JSON arrays take the form ['Item1', 'Item2', 'Item3']. The square brackets are required. The technical name of the XBlock is often described in the Readme page in its GitHub repository. If not, you might need to ask the XBlock author. Don’t forget to save! After completing this step the XBlock should become visible in the Course’s tool palettes.
  4. Return to your course content and choose either “Advanced” or “Problem” from the “Add new Component” button bar at the bottom of the window. The Xblock will appear in either (or perhaps both) depending on how the programmer designed it.
  5. Specifics on configuring an instance of the XBlock will vary. However, XBlocks commonly refer to other course objects (aka course elements, aka course building blocks). You might see data fields in your XBlock referring to an “ID” value of object X in your course. The illustration below shows how to locate, and importantly, how to correctly these ID values to your XBlock.

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