How to migrate from a native deployment to a tutor deployment of the Open edX platform

Owned by Sofiane Bebert
Last updated: Dec 20, 2021
3 min read

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

  1. Identify tutor plugins that you need based on the Open edX services that you use.

  2. Backup data from your native installation.

  3. Install tutor and the different plugins you need

  4. Customise your tutor instance to match your native configuration

  5. (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:

  1. Search or ask in the tutor forum. Someone may have already created a tutor plugin for the service you are looking for.

  2. 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

  1. By default in Tutor, the name of the edx-platform service database is openedx while it’s called edxapp in the native installation. You have two options:

    1. (Recommended) Edit your MySQL dump file:

      1. Add DROP DATABASE openedx; to the SQL file above the CREATE DATABASE line.

      2. Change CREATE DATABASE /*!32312 IF NOT EXISTS*/ edxapp /*!40100 DEFAULT CHARACTER SET utf8 */; to CREATE DATABASE /*!32312 IF NOT EXISTS*/ openedx /*!40100 DEFAULT CHARACTER SET utf8 */;

      3. Change USE edxapp; to USE openedx;

    2. Set OPENEDX_MYSQL_DATABASE: edxapp in your $(tutor config printroot)/config.yml file. If you are using an external database provider, you should set the following

OPENEDX_MYSQL_DATABASE: edxapp OPENEDX_MYSQL_PASSWORD: <mysql_password> OPENEDX_MYSQL_USERNAME: edxapp001

  1. 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

  1. Copy your MongoDB backup to $TUTOR_ROOT/data/mongodb.

  2. Run tutor local exec mongodb bash.

  3. Run mongorestore -d openedx /data/db/edxapp/.

  4. 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

The following steps are for guidance only, make sure they are suitable for your use case.

Tutor takes care of the configuration of the different services. For a service like discovery, it includes configuring the site, the partners and the OAuth clients. Unless you have a particular use case, the easiest way forward is to let Tutor handle the initialisation of the services as this makes upgrading to different Open edX release versions easier.

Discovery

  1. Install and enable the discovery plugin.

  2. Skip the initialisation step and start the discovery service with tutor local start discovery -d.

  3. Navigate to the discovery admin panel, and delete (in that order) any partners (Core > Partners) and then your site (Sites > sites).

  4. Navigate to the LMS admin panel and delete the existing OAuth clients related to discovery.

  5. Turn off the discovery service with tutor local stop discovery.

  6. Initialise the service tutor local init -l discovery.

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.

Theme

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>'

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)