[Archive] Using Tutor for local development
This page is out-of-date! For the latest Open edX development workflows with Tutor, see Open edX development — Tutor documentation.
This page is a work in progress. Reach out to #devenv-working-group on slack with questions
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
- 1 Setting up Tutor for edx-platform development
- 2 Quickstart edx-enterprise Development in Tutor
- 3 Quickstart for course-discovery Development
- 4 Notes for Debugging:
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:
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
it’s possible that this command might fail copying some requirements based on MacOS filesystem differences. Generally this won’t be an issue because we’re going to re-install requirements later
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:
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: https://docs.tutor.overhang.io/plugins/intro.html .
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
Checkout the frontend repository
On you local machine install node requirements using an npm version suitable for that codebase.
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:
Make sure to run
tutor dev
and nottutor local
commands since they point to different tutor configurations.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
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.