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.
Then, launch the developer platform setup process:
tutor dev quickstart
This will perform several tasks for you. It will:
stop any existing locally-running Tutor containers,
prompt for a platform details (with suitable defaults),
openedx-devimage, which is based
openedxproduction image but is specialized for developer usage,
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.
Once setup is complete, the platform will be running in the background:
Stopping the platform
To bring down your platform’s containers, simply run:
tutor dev stop
Starting the platform back up
Once you have used
quickstart once, you can start the platform in the future with the lighter-weight
start command, which brings up containers but does not perform any initialization tasks:
tutor dev start # Run platform in the same terminal ("attached") tutor dev start -d # Or, run platform the in the background ("detached")
quickstart is idempotent, so it is always safe to run it again in the future without risk to your data. In fact, you may find it useful to use this command as a one-stop-shop for pulling images, running migrations, initializing new plugins you have enabled, and/or executing any new initialization steps that may have been introduced since you set up Tutor:
tutor dev quickstart --pullimages
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 collect 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
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).
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 dev dc build lms
Setting up a development environment for edx-platform
tutor dev start -d --mount=/path/to/edx-platform lms
But to achieve that, you will have to make sure that your fork works with Tutor.
Then, you should run the following commands:
# Run bash in the lms container tutor dev run --mount=/path/to/edx-platform lms bash # Compile local python requirements pip install --requirement requirements/edx/development.txt # Install nodejs packages in node_modules/ npm clean-install # Rebuild static assets openedx-assets build --env=dev
After running all these commands, your edx-platform repository will be ready for local development. To debug a local edx-platform repository, you can then add a python breakpoint with
breakpoint() anywhere in your code and run:
tutor dev start --mount=/path/to/edx-platform lms
The default debugger is
PYTHONBREAKPOINT can be modified by setting an environment variable in the Docker imamge.
If LMS isn’t running, this will start it in your terminal. If an LMS container is already running background, this command will stop it, recreate it, and attach your terminal to it. Later, to detach your terminal without stopping the container, just hit
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"
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
# Run tests on common apps unset DJANGO_SETTINGS_MODULE unset SERVICE_VARIANT export EDXAPP_TEST_MONGO_HOST=mongodb pytest common pytest openedx # 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
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.