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 https://docs.tutor.overhang.io/index.html .

If you are unfamiliar with Docker, you may wish to familiarize yourself with some of the concepts here: https://www.docker.com/resources/what-container/ https://docs.docker.com/compose/

If you come across unknown terms, check out the Docker glossary: https://docs.docker.com/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 https://docs.tutor.overhang.io/intro.html#how-does-tutor-work. 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: https://docs.tutor.overhang.io/tutorials/nightly.html .

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.

mkdir ~/tutor-venvs

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:

tutor dev copyfrom lms /openedx/venv $HOME/tutor-venvs/venv-openedx

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:

tutor dev run lms \
      -m $YOUR_PROJECT_WORKSPACE/edx-platform \
      -m lms,lms-worker,cms,cms-worker:$HOME/tutor-venvs/venv-openedx/venv:/openedx/venv \
      bash

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:

tutor dev createuser --staff --superuser staff staff@example.com
tutor dev importdemocourse

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

# use xblock-lti-consumer as an example
tutor dev start lms \
      -m $YOUR_PROJECT_WORKSPACE/edx-platform \
      -m lms,lms-worker,cms,cms-worker:$HOME/tutor-venvs/venv-openedx/venv:/openedx/venv \
      -m lms,lms-worker,cms,cms-worker:$YOUR_PROJECT_WORKSPACE/xblock-lti-consumer:/openedx/packages/xblock-lti-consumer

install plugin as an editable requirement

tutor dev exec lms pip install -e /openedx/packages/xblock-lti-consumer

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 https://github.com/overhangio/tutor-mfe plugin. You can read more about Tutor plugins here: https://docs.tutor.overhang.io/plugins/intro.html .

Enable tutor-mfe

Follow the instruction at https://github.com/overhangio/tutor-mfe 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

   tutor dev start learning \ -m learning:$YOUR_PROJECT_WORKSPACE/frontend-app-learning:/openedx/app

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

vim "$(tutor config printroot)"/config.yml

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

MFE_AUTHORING_MFE_APP:
  name: authoring
  port: 2001
  repository: https://github.com/edx/frontend-app-course-authoring
  env:
    development:
      APP_SPECIFIC_URL: http://blah.co

*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)

tutor dev init -l mfe

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

tutor dev start authoring \
      -m authoring:$YOUR_PROJECT_WORKSPACE/frontend-app-course-authoring:/openedx/app

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:

tutor dev dc build lms

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

tutor dev bindmount lms /openedx/venv
cp -R "$(tutor config printroot)/volumes/venv" $HOME/tutor-venvs/edx-platform

• Configure local mounts for venv and code checkouts:

vim "$(tutor config printroot)/env/dev/docker-compose.override.yml"

• 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

version: "3.7"
services:
  lms:
    volumes:
      - /Users/jnagro/edx-repos/edx-platform:/openedx/edx-platform
      - /Users/jnagro/edx-repos/src:/openedx/src
      - /Users/jnagro/tutor-venvs/edx-platform:/openedx/venv
  cms:
    volumes:
      - /Users/jnagro/edx-repos/edx-platform:/openedx/edx-platform
      - /Users/jnagro/edx-repos/src:/openedx/src
      - /Users/jnagro/tutor-venvs/edx-platform:/openedx/venv
  lms-worker:
    volumes:
      - /Users/jnagro/edx-repos/edx-platform:/openedx/edx-platform
      - /Users/jnagro/edx-repos/src:/openedx/src
      - /Users/jnagro/tutor-venvs/edx-platform:/openedx/venv
  cms-worker:
    volumes:
      - /Users/jnagro/edx-repos/edx-platform:/openedx/edx-platform
      - /Users/jnagro/edx-repos/src:/openedx/src
      - /Users/jnagro/tutor-venvs/edx-platform:/openedx/venv

• Install current dependencies:

  • this will use/save the mounted venv folder locally

tutor dev run lms pip install -r requirements/edx/development.txt

• Install current edx-enterprise:

tutor dev run lms pip install -e /openedx/src/edx-enterprise

• Run migrations:

tutor dev run lms ./manage.py lms migrate

• Start local development server:

tutor dev runserver lms

• Add a local development user:

tutor dev createuser --superuser --staff -p edx edx edx@example.org

• 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 https://discuss.overhang.io/t/quickstart-failed-on-fresh-mac/143 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.