[Archive] Using Tutor for local development

Tutor is a Docker-based OpenEdX distribution. It was adopted as the primary installation method for OpenEdX with the Maple release in December 2021. It has also been widely adopted as a development platform in the greater OpenEdx community as a replacement for devstack. We hope to make this the case at 2U/edX as well.

For more general information on Tutor website, you can visit the documentation site at Tutor: the Docker-based Open edX distribution designed for peace of mind — Tutor documentation .

If you are unfamiliar with Docker, you may wish to familiarize yourself with some of the concepts here: What is a Container? | Docker Docker Compose

If you come across unknown terms, check out the Docker glossary: Glossary

Setting up Tutor for edx-platform development

These instructions are for developing in the edx-platform repository ONLY. Information about development of MFEs and other IDAs is forthcoming.

Before Doing Anything

Familiarize yourself with how tutor works by taking a look at Concepts — Tutor documentation. This will provide helpful context when following the setup steps below.

You will want to create and activate a python3 virtual environment. You will also need to have Docker Desktop set up.

Heuristically, 9.5G should be enough memory to allot to Docker to run everything successfully.

If you are still running devstack you may need to allocate additional disk space to account for duplicate images for each service.

Running Tutor Nightly

To develop off the master branch of edx-platform, you will need to install Tutor from the “nightly” branch, documented here, whose installation method is documented here: Obsolete: Tutor nightly — Tutor documentation .

Then you should be able to follow the directions for first time setup and to ensure the LMS and CMS are running and accessible. Now is a good time to familiarize yourself with the following concepts:

• Stopping/Starting the Platform

• Running Commands

  • Command Reference

At this point you are running off the master branch at the point in time when each ‘nightly’ image was built.

Setting up your Local Development Branch

In order to run the code in your local checkout of edx-platform you will need to mount that folder into the container. Additionally you will also want to mount a virtualenv folder to persist any differing pip requirements.

create local venv for edx-platform

Each service you plan to run with a local branch will need it’s own venv folder. It’s recommended you create a folder on your machine to manage these.

Use the ‘copyfrom’ command to copy the default environment into this folder. copy-files-from-containers-to-the-local-filesystem

If you used the same tutor-venvs folder above:

bind-mount project and venv folders

Read the directions to bind-mount a project folder to point Tutor towards your local branch of edx-platform and the venv folder you just created. You will need to include these mount arguments each time you run a command that starts the service if you want it to run against you locally checked out branch.

For example 'run lms bash' using the venv created above:

install requirements and run static assets

Follow the instructions at setting-up-a-development-environment-for-edx-platform to install python/node requirements and compile static assets.

done!

• LMS will be accessible at http://local.overhang.io:8000.

• CMS will be accessible at http://studio.local.overhang.io:8001

To test if you are set up for development, make a cosmetic or logging change in your local branch of edx-platform. They server should automatically reload and pick up your change.

Populating Test Data

Tutor makes adding test data pretty easy. To match the users and courses created in normal devstack provisioning, you have to stop the local server with tutor local stop (note in this case you actually do want local and not dev). You can run the createuser and importdemocourse commands as follows:

Working with edx-platform Plugins

If you are doing work on edx-platform plugins, the following steps will allow you to mount your local checkout of those plugins and install them in the platform.

start the LMS with a local venv and your plugin code mounted

install plugin as an editable requirement

Make a change in your locally checked out plugin repo, the platform should reload with your changes.

Working with MFEs

MFEs can be added to your development environment using the GitHub - overhangio/tutor-mfe: This plugin makes it possible to easily add micro frontend (MFE) applications on top of an Open edX platform that runs with Tutor. plugin. You can read more about Tutor plugins here: Introduction — Tutor documentation .

Enable tutor-mfe

Follow the instruction at GitHub - overhangio/tutor-mfe: This plugin makes it possible to easily add micro frontend (MFE) applications on top of an Open edX platform that runs with Tutor. to install and enable the tutor-mfe plugin. By default this plugin will allow you to run the account, gradebook, profile and learning MFEs.

Running your local branch

1. Checkout the frontend repository

2. On you local machine install node requirements using an npm version suitable for that codebase.

3. Run tutor dev with --mount

    

What about other frontend projects?

Most MFE projects share the same environment variables and build tasks so the tutor-mfe plugin should be able to handle other projects if given some additional configuration. At minimum you will need the project name, port, and git url. Some projects may require additional environment variables.

open your local config

add your new MFE (course-authoring as an example)

*note the MFE_ prefix, this is important for your settings to get picked up by tutor-mfe

To pick up your changes you will either need to initialize the mfe plugin. (quickstart will also do this)

The newly added MFE can be run using the name used in config.yml

Quickstart edx-enterprise Development in Tutor

• Stop all devstack docker containers

  • devstack and tutor can live side by side but its not recommended to run both simultaneously

• Install nightly tutor (see above) - be sure to have a virtualenv setup for tutor

• Configure ample resources for Docker Desktop (2+ CPU, 8+ GB ram, 4 GB swap, 150+ GB disk)

  • extra disk space is required to create the virtualenv bindmount copy

• Build the initial docker images, which we’ll need to bootstrap our bindmount virtualenv:

• Extract the supplied virtualenv and move it somewhere useful/obvious:

• Configure local mounts for venv and code checkouts:

• Use a config similar to this:

  • LMS git checkout in /Users/jnagro/edx-repos/edx-platform

  • edx-enterprise git checkout in /Users/jnagro/edx-repos/src/edx-enterprise

  • tutor-extracted venv (from above) in /Users/jnagro/tutor-venvs/edx-platform

• Install current dependencies:

  • this will use/save the mounted venv folder locally

• Install current edx-enterprise:

• Run migrations:

• Start local development server:

• Add a local development user:

• Browse to http://local.overhang.io:8000/

Quickstart for course-discovery Development

Tutor: Developing with Course Discovery

Notes for Debugging:

1. Make sure to run tutor dev and not tutor local commands since they point to different tutor configurations.

2. If you run into errors on initial migration, make sure you have allotted enough memory to Docker. See Quickstart failed on fresh mac for more information

3. If you run into port already allocated errors when starting up CMS, check to see if you are running kubectl anywhere. It also uses port 8001 so it will cause a collision.