Introductory Guide to Open edX

An Introductory Guide to Open edX

I joined the Appsembler team just a few short weeks ago and could not be more excited and terrified. My past experiences have been in front-end design with absolutely no exposure to the Open edX platform. I found myself quickly feeling a bit in over my head to say the least; as a newbie I simply wasn’t sure where to begin.

I’m certainly not new to being a student, however, and the overwhelming sensation of having to learn something new and complex as quickly as possible is not unfamiliar to me. As an author so much of what I choose to write about is inspired by what I am having to learn at the time and any frustration I may run in to when not being able to find friendly resources geared towards true beginners.

This post will touch on some high level, handy bits of information for those just getting started with Open edX and looking to get your bearings. I’ll try to speak to some things that tripped me up and provide links to resources I found helpful along the way.

What Is It?

edX is an open online course provider with a mission to increase access to high-quality education and enhance teaching and learning on campus, online, and through research. Founded by Harvard University and MIT in 2012, edX now has more than 90 global partners that strive to offer courses within a variety of disciplines, such as: computer science, languages, engineering, psychology, writing, electronics, biology, and marketing.

Open edX is the free and open source platform that powers these edX courses which allows institutions to host their own instances and offer their very own classes. They maintain a steady stream of announcements and provide a number of different avenues for getting help. There are two sides to the platform: student facing courses through the LMS and course administration through Studio and both can be used directly through a browser.

The edX mobile apps for Android and iPhone allow learners to download course videos to watch on the go, follow and participate in course discussions, and get a head-start on assignments; tablet use is a future goal for edX.

Sites And Providers

Within the edX wiki there is a list of sites powered by Open edX as well as a list of service providers.

Latest Release

The fifth and current release of Open edX is called Eucalyptus, which includes several additional features for learners, course teams, and developers over the previous release, Dogwood.

Some of the newest Eucalyptus features include: teams, bookmarks, navigation updates, a peer instruction XBlock, support of themes for multiple sites in a single installation, and a number of mobile app updates.

Common Terminology

While getting started with a new platform can be staggering enough coming across seemingly endless acronyms and jargon can make this experience even more deflating, so let’s take a look at the more common ones:

  • Open edX is a content management system (CMS) that is used to create, manage, and consume digital learning content.
  • A learning management system, or LMS, is software used for the administration, documentation, tracking, reporting, and delivery of e-learning courses and training programs. An LMS represents a significant portion of what Open edX offers.
  • MOOC stands for massive open online course and it’s a model for delivering learning content line to any person that wants to take a course, which is exactly what edX is.
  • Studio is the edX tool used to build courses from the administrative side of an LMS. The user can create a course structure and then add details, challenges, videos, and other resources for learners. It also enables the ability to manage schedules, view course members, and set a grading policy among other things.
  • XBlocks refer to the individual components that deliver course content to learners. These building blocks can range in size from a paragraph of text to a multiple-choice input field or an entire course. The Appsembler team hosted a webinar with Ned Batchelder, senior edX architect, which discusses XBlocks in much more detail.
  • Devstack represents the virtual environment needed to run Open edX locally on your computer and edX has a great guide to getting started.

Once you jump in you’ll run into a lot more unfamiliar terminology but luckily there’s a glossary for that.

The Community

Like many successful open source projects Open edX has a strong community with an active, engaging blog and Twitter profile that are definitely worth following.

Slack and Google Groups

Anyone can join the Open edX Slack channel to connect with others doing similar work, ask questions, and offer assistance. Slack has fairly recently become the preferred place for discussions over IRC. There are also a number of Google Groups for: announcements, operations, code and general discussions, and more.


Meetup is a great way to find local groups passionate about Open edX and related technologies. Appsembler, for example, contributes to the Open edX Boston and Bay Area Meetups. I personally don’t live near an in-person Open edX group specifically but there is a very active Python group and you can always start your own Meetup as you settle in.

From my experience these types of groups were essential in officially feeling like part of certain spaces and provided unique speaking opportunities for those looking to get into public speaking but not sure where to start.

Also, if you are part of a distributed team like we are here at Appsembler it can be refreshing to get out and be part of a supportive, inclusive, irl community; I’ve sincerely known few as welcoming as those related to Django and Python.

Some related technologies to search for:

  • Open edX
  • Python
  • Django
  • JavaScript
  • CSS/Sass/front-end design

Remote Meetups

Luckily there are also remote Open edX meetups that got started a few months ago. These meetups are scheduled for the fourth Thursday of each month (unless they announce otherwise), with times rotating between 10-11AM and 2-3PM EST.

You can expect valuable community updates and new Open edX team member introductions, release news, general roadmap updates, and a change to share what you have been working on with the group. Each month there is a featured topic presented by a guest speaker and topic suggestions can be submitted through the Open edX open source community email.


Open edX has its very own conference.

There is a seemingly endless list of Python conferences and JavaScript events around the world. I can also personally vouch for how inclusive and informative Djangocon US is as I was lucky enough to speak at their 2016 event this past summer in Philadelphia. Django also holds conferences in Europe as well.

If you are more interested in the design side of things in general there are bunches of related conferences, for example: CSS Dev Conf, CSSConf, CSSConf EU, CSS Summit, Design It Build It, and Sass Conf to name a few.

There are so many people that want to help so hanging out in these spaces, either in person or online, for a while is essential in building up the courage and comfort needed to ask questions and give back.


There is a wonderful, detailed document on how to contribute to Open edX so I won’t get in to any of the fine details of how to contribute but rather touch on what it’s like and why you may want to consider it.

What’s It Like?

There’s a fairly recent great talk (with slides) by Adolfo Brandes called “Life as a New Open edX Contributor”. This talk touches on personal stories of organically hitting some limitations of the platform and how to go about resolving these in the open source environment.

Contributors will inevitably hit conflicts when submitting pull requests and will experience frustrations and roadblocks when their work is reviewed. Brandes speaks to this directly and mentions that it’s important to not get discouraged or abandon your submitted work and the individuals in Open edX are among the most helpful he has come across.

This can all be very intimidating. Being a newbie in any space is uncomfortable, but perhaps even more so with such a massive project. To add to this it’s very possible that your limited interaction with this new community has been strictly through a screen so far, which can make it even more challenging to connect and feel like part of something.

Why Contribute At All?

This is perhaps one of the most significant questions around open source projects and one that Brandes addresses head-on in the talk mentioned above:

“If you create a patch to solve a problem that’s beautiful and you will want to share it with the world.”

It can simply be very exciting and rewarding to solve a problem not only for yourself but for countless other people that hit that same problem or would have in the future. Contributions strengthen your confidence but also make the entire community stronger in the process.

Contributing doesn’t end with a pull-request. Contributors must take care of it and see it through, fully immersing themselves in documentation, the process, and the larger community; it’s a great natural path to getting to know this new space and the people in it. It can also be painful to maintain a forked project of your own and pushing these solutions upstream will simply save you a lot of time.

In Jessica McKellar’s workshop “Contribute with me! Getting started with open source development” she is sure to touch on the significance of people as a benefit to contributing to free software. It’s a way to give back to the community, learn from some of the smartest most experienced people in the space, and gain a competitive advantage when applying for jobs. Last but not least, Jessica mentions that she also contributes because it’s fun.

It’s important to stress that everyone has something of value to give and the very first step to contributing is becoming part of the community and joining the conversation; here’s a great summary on different non-code ways to contribute to open source if you are not a programmer.

Desktop Theming

The role of visual design exists in Open edX through theming.

You may find that simply swapping out a logo, for example, doesn’t do much in terms of establishing a strong identity. The overall company feel will be absent within the platform and you may find it’s difficult to distinguish one LMS from another.

Proper, consistent branding is crucial in building trust, loyalty, and recognition in any space. Without the ability to customize this platform an institution or business may struggle to be viewed as a serious, stable competitor and fail to set the proper expectations needed to gain user and staff support.

Basic theming is also not especially responsive which may prove very limiting for many users and another factor to consider regarding custom efforts here.

Quick Overview Of How It Works

The front-end of edX consists of a number of moving parts, such as: JavaScript, Sass, and Mako and Django HTML templates. Once you configure a site for the Open edX installation you can set up a custom theme through overrides by creating replacement files.

The theme is housed in a folder that imitates the structure of the LMS folder. If the platform finds new theming files with the same relative paths and names as the default files it will use these instead, initiating an override. This same concept applies to static assets as well.

You can read a more comprehensive take on theming in the edX documentation.


Open edX has a thorough Developer’s Guide that helps walk you through the basics of browser support, architecture, setting up your environment and platform installation, contributing, XBlocks, testing, and even includes a list of additional resources.

Perhaps it’s also worth mentioning here that Open edX tracks issues in JIRA and not GitHub.

See You Around

Hopefully this post helps serve as a starting point to feeling comfortable and welcome enough to jump into the vast details of the Open edX platform. There are so many proactive paths to take to make sure you feel empowered enough to begin contributing in a way that makes sense to you.

Welcome to the exciting world of Open edX, I look forward to learning, sharing, and contributing with you.