Open edX Sandbox to Production In 10 Steps

I’ll never forget that empty feeling in my stomach. After much Googling I’d finally found coherent instructions and code samples for installing Open edX on an Ubuntu server; only to read an ominous disclaimer at the top of the page basically stating that the instructions that followed were incomplete. Why, I wondered? What’s missing?

I’ve since learned that the simple 4-step instructions provided on the Open edX Alassian page, “Native Open edX Ubuntu 16.04 64 bit Installation” are not only the correct procedure for a native installation, but furthermore, that there is no difference in the executable program files between the “Sandbox” installation that is regularly mentioned in the Open edX ecosystem versus that of a genuine production installation. The difference between the two therefore lies solely in the additional management considerations that a production environment requires. Let’s take a closer look at the ten fundamental differences between a “sandbox” and a production site.

A sandbox is generally used by not more than a handful of project team members for evaluation, planning, development and training purposes. It’s safe to make broad generalizations about the underlying infrastructure requirements simply because the load on the system is small and predictable. I usually recommend a t3.large EC2 on-demand instance for sandboxes. When you go to production your needs will immediately change.

A good production information system begins with well-planned infrastructure. Your Open edX project’s infrastructure requirements are unique, and thus merit an independent analysis that considers normal versus peak usage of your platform, its growth, your up-time requirements, your locale, and so on. Hopefully your project will not only succeed but will grow in popularity and usage over time, in which case you’ll require additional IT infrastructure. Your growth plan also merits special consideration.

Open edX software is highly scalable and infinitely configurable. You can install the entire Open edX platform on a single instance of any of the nearly 100 different virtual server configurations that AWS offers. But it’s also possible to install parts of the system on individual, specially-configured servers, or, spread across clusters of servers working together.

Infrastructure tends to involve capital expenditures as well as recurring monthly costs, which are topics that tend to be of interest to many if not all of the stakeholders in your project. Additionally,

A production installation of Open edX runs the same executable system files as those of a Sandbox. The difference therefore lies in how these files are installed, with the key factor being repeatability. It’s important that you are able to run the installation process for your production environment in a predictable, repeatable way. This is why I always execute the installation with a Bash script like this one.

One of the most effective means of trouble shooting an Open edX installation is to re-install the software on a fresh, new Ubuntu server, and then migrate your data to this new instance. In order to employ these types of IT management strategies however, it is necessary that your installation procedure produces consistently identical servers.

You can learn more about how to design an effective production installation procedure by reading my blog posts, “Open edX Step-By-Step Production Installation Guide” and “Open edX Configuration Tutorial“.

How you manage customizations in your Sandbox may not be a matter of importance, but it definitely matters in your production environment. You should create a Git repository to maintain all of the configuration and customization data for your production Open edX instance. I understand that you might be saying, “But I’m not planning to modify the Open edX software, so I don’t need to worry about source control”, but that is not true. Adding version control and a remote  source code repository like GitHub will help you maintain a disciplined approach to change management that importantly, will give you a way to roll-back any changes that create unintended side effects. Even if you have no intention of modifying the core code base, you’ll most likely need to modify the following sets of files:

• Django app configuration and authorization JSON files in /edx/app/edxapp
• the LMS’ header and footer mako templates
• the Nginx configuration files for the LMS and CMS
• the email templates

Keeping your configuration data in a Git repository will also make it possible for you to automate your production “build” procedure. For lots of reasons, you will need to occasionally rebuild your production Open edX environment; or at least, parts of it. When mapping out your production build process you want to try to think of “configuration” as a single, indivisible entity that you simply add to an automation scripts in order generate a new production server.

Lastly, if more than one person will have the ability to connect to your Open edX instance via SSH in order to modify system files then it behooves you to follow a team-based work flow for source code management and deployment.

Open edX is a themeable platform, but this is not enabled by default. Importantly, theming is an elegant way for you to modify the appearance of your platform without actually modifying the code case. Simply described, a theming system relies on a base set of UI files (templates, CSS, Javascript, images, fonts, etc.) that are used in cases where you have not provided a custom alternative which is stored in a specially designated location on your server. Avoiding modifications to the code base is good practice on a production machine because, any time you upgrade your Open edX instance, all of the existing code base gets completely deleted. By contrast, maintaining your UI customizations in a custom theme is a good practice that also conforms to the Git repository discussion in the preceding section.

You can usually modify UI files in a sandbox without worrying about the long-term affects. But there are important considerations in a production environment that make this an undesirable practice.

You can learn more about how to setup Comprehensive Theming from my blog post, “Open edX Custom Theming Tutorial”