| Warning |
|---|
This page is out-of-date! For the latest Open edX development workflows with Tutor, see https://docs.tutor.overhang.io/dev.html. |
| Info |
|---|
This page is a work in progress. Reach out to #devenv-working-group on slack with questions |
...
| Table of Contents | ||||
|---|---|---|---|---|
|
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.
...
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 .
...
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.
...
| Note |
|---|
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.
...
| Info |
|---|
work is being done to make this a persistent configuration, in the future you won’t need to include a pile of mount arguments in every command |
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:
| Code Block |
|---|
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.
...
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
Checkout the frontend repository
On you local machine install node requirements using an npm version suitable for that codebase.
Run tutor dev with --mount
Code Block 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.
...
| Code Block |
|---|
tutor dev start authoring \
-m authoring:$YOUR_PROJECT_WORKSPACE/frontend-app-course-authoring:/openedx/app |
Quickstart edx-enterprise Development in Tutor
| Info |
|---|
Most ancillary enterprise services (catalog service, license manager, etc) and MFEs (learner portal, explore catalog, etc) are not currently supported. |
...
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 devand nottutor localcommands 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 https://discuss.overhang.io/t/quickstart-failed-on-fresh-mac/143 for more information
If you run into
port already allocatederrors when starting up CMS, check to see if you are running kubectl anywhere. It also uses port 8001 so it will cause a collision.