Open edX development
In addition to running Open edX in production, Tutor can be used for local development of Open edX. This means that it is possible to hack on Open edX without setting up a Virtual Machine. Essentially, this replaces the devstack provided by edX.
First-time setup
Firstly, either install Tutor (for development against the named releases of Open edX) or install Tutor Nightly (for development against Open edX’s master branches).
Then, optionally, tell Tutor to use a local fork of edx-platform.:
tutor mounts add ./edx-platform
Then, launch the developer platform setup process:
tutor images build openedx-dev
tutor dev launch
This will perform several tasks. It will:
build the “openedx-dev” Docker image, which is based on the “openedx” production image but is specialized for developer usage (eventually with your fork),
stop any existing locally-running Tutor containers,
disable HTTPS,
set
LMS_HOST
to local.overhang.io (a convenience domain that simply points at 127.0.0.1),prompt for a platform details (with suitable defaults),
build an
openedx-dev
image,start LMS, CMS, supporting services, and any plugged-in services,
ensure databases are created and migrated, and
run service initialization scripts, such as service user creation and Waffle configuration.
Additionally, when a local clone of edx-platform is bind-mounted, it will:
re-run setup.py,
clean-reinstall Node modules, and
regenerate static assets.
Once setup is complete, the platform will be running in the background:
LMS will be accessible at http://local.overhang.io:8000.
CMS will be accessible at http://studio.local.overhang.io:8001.
Plugged-in services should be accessible at their documented URLs.
Now, use the tutor dev ...
command-line interface to manage the development environment. Some common commands are described below.
Note
If you’ve added your edx-platform to the bind-mounted folders, you can remove at any time by running:
tutor mounts remove ./edx-platform
At any time, check your configuration by running:
tutor mounts list
Read more about bind-mounts below.
Stopping the platform
To bring down the platform’s containers, simply run:
tutor dev stop
Starting the platform back up
Once first-time setup has been performed with launch
, the platform can be started going forward with the lighter-weight start -d
command, which brings up containers detached (that is: in the background), but does not perform any initialization tasks:
tutor dev start -d
Or, to start with platform with containers attached (that is: in the foreground, the current terminal), omit the -d
flag:
tutor dev start
When running containers attached, stop the platform with Ctrl+c
, or switch to detached mode using Ctrl+z
.
Finally, the platform can also be started back up with launch
. It will take longer than start
, but it will ensure that config is applied, databases are provisioned & migrated, plugins are fully initialized, and (if applicable) the bind-mounted edx-platform is set up. Notably, launch
is idempotent, so it is always safe to run it again without risk to data. Including the --pullimages
flag will also ensure that container images are up-to-date:
tutor dev launch --pullimages
Debugging with breakpoints
To debug a local edx-platform repository, add a python breakpoint with breakpoint()
anywhere in the code. Then, attach to the applicable service’s container by running start
(without -d
) followed by the service’s name:
# Debugging LMS:
tutor dev start lms
# Or, debugging CMS:
tutor dev start cms
Running arbitrary commands
To run any command inside one of the containers, run tutor dev run [OPTIONS] SERVICE [COMMAND] [ARGS]...
. For instance, to open a bash shell in the LMS or CMS containers:
tutor dev run lms bash
tutor dev run cms bash
To open a python shell in the LMS or CMS, run:
tutor dev run lms ./manage.py lms shell
tutor dev run cms ./manage.py cms shell
You can then import edx-platform and django modules and execute python code.
To rebuild assets, you can use the openedx-assets
command that ships with Tutor:
tutor dev run lms openedx-assets build --env=dev
Rebuilding the openedx-dev image
The openedx-dev
Docker image is based on the same openedx
image used by tutor local ...
to run LMS and CMS. However, it has a few differences to make it more convenient for developers:
The user that runs inside the container has the same UID as the user on the host, to avoid permission problems inside mounted volumes (and in particular in the edx-platform repository).
Additional Python and system requirements are installed for convenient debugging: ipython, ipdb, vim, telnet.
The edx-platform development requirements are installed.
If you are using a custom openedx
image, then you will need to rebuild openedx-dev
every time you modify openedx
. To so, run:
tutor images build openedx-dev
Alternatively, the image will be automatically rebuilt every time you run:
tutor dev launch
Common tasks
XBlock and edx-platform plugin development
In some cases, you will have to develop features for packages that are pip-installed next to the edx-platform. This is quite easy with Tutor. Just add your packages to the $(tutor config printroot)/env/build/openedx/requirements/private.txt
file. To avoid re-building the openedx Docker image at every change, you should add your package in editable mode. For instance:
echo "-e ./mypackage" >> "$(tutor config printroot)/env/build/openedx/requirements/private.txt"
The requirements
folder should have the following content:
env/build/openedx/requirements/
private.txt
mypackage/
setup.py
...
You will have to re-build the openedx Docker image once:
tutor images build openedx
You should then run the development server as usual, with start
. Every change made to the mypackage
folder will be picked up and the development server will be automatically reloaded.
Running edx-platform unit tests
It’s possible to run the full set of unit tests that ship with edx-platform. To do so, run a shell in the LMS development container:
tutor dev run lms bash
Then, run unit tests with pytest
commands:
# Run tests on common apps
unset DJANGO_SETTINGS_MODULE
unset SERVICE_VARIANT
export EDXAPP_TEST_MONGO_HOST=mongodb
pytest common
pytest openedx
pytest xmodule
# Run tests on LMS
export DJANGO_SETTINGS_MODULE=lms.envs.tutor.test
pytest lms
# Run tests on CMS
export DJANGO_SETTINGS_MODULE=cms.envs.tutor.test
pytest cms
Note
Getting all edx-platform unit tests to pass on Tutor is currently a work-in-progress. Some unit tests are still failing. If you manage to fix some of these, please report your findings in the Open edX forum.