It is probable that the upgrade will not succeed on your first attempt. With that in mind, here are the preparatory steps that I would suggest that you at least consider before pressing forward with an upgrade to your Open edX platform.
1. Create an AWS Machine Image (AMI)
This is unquestionably your absolute best means of restoring your current production environment in the events that things don’t go as planned. It only takes a few minutes to create a snapshot, and more importantly, it only takes a few minutes to recreate your current production server.
2. Review the steps to launch your AMI
It is quick and simple to stage a replacement server using an AWS AMI, unless you’ve never done it before. If this is new to you then you should definitely do a practice run before venturing into a production software upgrade.
3. Backup the MySQL databases and MongoDB’s
If you already have an up to date AWS AMI then it is unlikely that you’d also need backups of your databases. However, in order to maximize the restore options that are available to you — again, in the event that things don’t go as planned — then it’d be a great idea to have full backups of all of your databases before your venture ahead. Here is a link to a robust backup script: github.com/lpm0073/edx.scripts/edx.backup.sh
4. Check Available Disk Space
The Upgrade script that I reference in this post creates full backups of around 5Gb of files in your /edx file system. Ideally you should have multitudes more than this much space available on your Ubuntu Linux volume. You can check the available space on your volume with this command
5. Review your steps to merge customizations and configuration into the upgraded code base
Aside from your MySQL and MongoDB data, several other data sources are unique to your installation including for example
- The passwords.yml file that is hopefully still stored in your home folder following the Native build process that you followed to initially created your Open edX instance. The Open edX update script references this file during the upgrade process.
- UI Customizations. Hopefully you’ve implemented these as a custom theme. If not then you should seriously consider biting the bullet and migrating your UI customizations to a custom theme beforehand. Otherwise, you’re definitely going to be in for a rough ride.
- Configuration Files. The entire platform is configured via four json files located in /edx/app/edxapp. The upgrade scripts backs these up for you, but it’d be prudent to automate this yourself.
- Nginx virtual server settings. Any customizations you’ve made to the Nginx virtual servers will get overwritten by the upgrade process, so make sure to back these up yourself prior to attempting an upgrade!
6. Confirm You Have Enough Time To Complete The Upgrade.
The upgrade takes a long time. Ideally, you’ll perform the upgrade on a low-volume day. If the upgrade goes perfectly then you’ll need around four hours. But, it probably won’t go perfectly.
7. Perform the upgrade.
Warning: Make a complete snapshot of your instance before attempting to upgrade the software.
There are two possible commands that you can use to upgrade the Open edX software.
/edx/bin/update edx-platform master <– this is the preferred method
- re-running the “native build” installation script
You should first attempt to upgrade using the built-in update method. I occasionally have problems with version incompatibilities with Pip and other libraries. If, after 15 minutes or so, I’m unable to trouble-shoot these problems then I’ll switch to the alternative method of re-installing the software which is effectively the following:
sudo chmod 755 native.sh
# HEADS UP! -- you need to edit this script, and set the following variable
sudo rm -r /edx/app/ #NOTE: this will delete all modifications and configuration of your instance.