Overview
This document describes the steps required to migrate from a native installation (using Ansible scripts) to a Tutor deployment of the Open edX platform.
This document will outline steps for:
Single instance installation
Not using external services for MongoDB and MySQL running on the same VM
Migrate to the same Open edX version
For any specific use case, feel free to ask questions in the tutor forum.
The Process
Identify tutor plugins that you need based on the Open edX services that you use.
Backup data from your native installation.
Install tutor and the different plugins you need
Customise your tutor instance to match your native configuration
(Optional) Maintain your tutor instance
1. Getting ready
First, make a list of services that your Open edX instance rely on. The native installation script installs a lot of services (e.g. edx-analytics-api by default but unless you configured them you probably don’t need them.
Here is a list of officially supported plugins.
If you can’t find your service in this list you have two options:
Search or ask in the tutor forum. Someone may have already created a tutor plugin for the service you are looking for.
Create your custom plugin to deploy and configure the service you want to use.
2. Backup data from the native install
Use your preferred method to export the MySQL and MongoDB data of your native installation.
Here is an example backup script if you need some guidance.
Unless you configured your Open edX instance to use a distributed storage system (e.g. S3), you will need to take a copy of your /edx/var/edxapp/media
folder.
3. Install tutor
Installation
Follow the installation instructions in the documentation to install Tutor.
Restore your data
Move your export of MongoDB and MySQL databases to your new instance.
MySQL
By default in Tutor, the name of the edx-platform service database is
openedx
while it’s callededxapp
in the native installation. You have two options:Add
OPENEDX_MYSQL_DATABASE: edxapp
to your$(tutor config printroot)/config.yml
file. (This is probably ideal if you are using an external database provider.)(Recommended) Edit your MySQL dump file:
Add
DROP DATABASE openedx;
to the SQL file above theCREATE DATABASE
line.Change
CREATE DATABASE /*!32312 IF NOT EXISTS*/
edxapp/*!40100 DEFAULT CHARACTER SET utf8 */;
toCREATE DATABASE /*!32312 IF NOT EXISTS*/
openedx/*!40100 DEFAULT CHARACTER SET utf8 */;
Change
USE
edxapp;
toUSE
openedx;
Run the following command to restore your data
docker exec -i tutor_local_mysql_1 sh -c 'exec mysql -uroot -p"MYSQL_ROOT_PASSWORD"' < /home/user/mysql-data-20210504T110001.sql
You can find your MYSQL_ROOT_PASSWORD
using tutor config printvalue MYSQL_ROOT_PASSWORD
.
MongoDB
Copy your MongoDB backup to
$TUTOR_ROOT/data/mongodb
.Run
tutor local exec mongodb bash
.Run
mongorestore -d openedx /data/db/edxapp/
.Remove the export
rm -r /data/db/edxapp
.
Media Files
Copy the content from /edx/var/edxapp/media
to $TUTOR_ROOT/data/openedx-media
.
Other services
OAuth Clients names
Site configurations
Discovery
Ecommerce
4. Customise your tutor instance
Approach
Identify whether there is value in config.yml
Find the patch
it's better if settings are defined directly in the python modules, to avoid code indirections.
Config.yml
Custom YAML Plugin
name: myplugin version: 0.1.0 patches: openedx-common-settings: | LOGO_URL = "<URL_TO_LOGO>" LOGO_URL_PNG = "<URL_TO_LOGO_PNG>" openedx-lms-production-settings: | PROFILE_IMAGE_SECRET_KEY = '<KEY>'
openedx-lms-production-settings: PROFILE_IMAGE_SECRET_KEY
Maintain your tutor instance
Backups
(Test it!)
https://github.com/lpm0073/edx.scripts/blob/master/tutor/tutor.backup.sh
Reference
Migrating from Native Install to Tutor (juniper -> tutor 10.x)