Restore Open edX From a Backup

There are a few details to successfully restoring an Open edX instance that are definitely worth understanding well before the need arises. If you haven’t done so already, make sure to take a look at my blog post, “Complete Backup Solution for Open edX“. There are multiple kinds of persistent data in an Open edX platform, and these naturally rely on different kinds of technology and store. Whether you’re migrating to a new server or restoring an environment that suffered a catastrophic failure, you’ll need to consider all of the these:

This article focuses on the two truly critical data sources, MySQL and MongoDB, plus a couple of common pitfalls that can prevent your restored platform from running properly.

First, the Django framework relies on a process called “Database Migrations” to ensure that the physical database schema in MySQL is consistent with the Django objects described in the source code. That is, Django programmers do not directly modify the MySQL database schema, but instead rely on Database Migrations to handle this for them. When you restore an Open edX MySQL database, you have to consider the possibility that the physical schema of the backup differs from that of the Django codebase.

Second, Open edX relies extensively on a subsystem named RabbitMQ to asynchronously manage tasks. By “task” I’m referring to virtually every command button that a learner clicks while interacting with course data. RabbitMQ is invoked each time they provide a response to a problem, each time they interact with the discussion forum, provide a comment, record data in Notes/Annotations, request a password reset, and so on. These tasks are queued and then run in a first-in-first-out queue based on available server and network resources. Depending on the circumstances surrounding your need to restore or migrate your Open edX instance, there might be many hundreds or thousands (or millions) of pending RabbitMQ tasks in queue. If that’s the case then it would be prudent on your part to at least attempt to migrate these tasks as well. Furthermore, there are some common problems with migrating and/or restoring RabbitMQ configuration settings that we’ll look at in more detail below.

* Download your backup files to the Ubuntu local file system

If your backup files are stored remotely then you’ll need to download a copy of the MySQL and MongoDB backup sets to your local Ubuntu file system. If you followed my instructions from my article, “Open edX Complete Backup Solution” then you can follow these instructions to download your compressed backup files from your AWS S3 bucket to your Ubuntu local file system.

Once your file has been made public you can download a copy of it to your local file system using the Linux wget command.

# Download the backup tarball to the current directory.
wget https://s3.amazonaws.com/[YOUR-BUCKET-NAME]/backups/openedx-data-20180919T175920.tgz

# Uncompress the tarball into the current directory
tar xvzf openedx-data-20180919T175920.tgz

# Where
# x: This option tells tar to extract the files.
# v: The “v” stands for “verbose.” This option will list all of the files one by one in the archive.
# z: The z option is very important and tells the tar command to uncompress the file (gzip).
# f: This options tells tar that you are going to give it a file name to work with.

1. Restore MySQL Databases

Nearly all of your users’ data is stored in MySQL, including usernames and passwords, course content responses, notes & annotations data, their profile and so on. If you followed my guidelines on Creating a Complete Backup Solution for Open edX then your MySQL dump contains all of the Open edX databases and none of the MySQL system databases, which is exactly what you want. Restoring from your MySQL dump will therefore be as simple as the following:

mysql -u root -p < db_backup.dump

That’s it. You do not need to restart MySQL, nor flush any caches or buffers, nor do any other administrative tasks. MySQL is remarkably resilient in this respect. However it is really important that your perform Database Migrations in the next section.

2. Run Database Migrations

This process is simple to run and usually only takes a minute or so to complete. Running this procedure more than once will not harm your database. Make Migrations scans the Django objects in your Open edX application codebases to ensure that the physical database tables, fields and relationships are consistent. It automatically adds anything that is missing, and it keeps track of what it’s done.

sudo -H -u