Table of Contents
There are a lot of great ORA resources:
Where's the code?
ORA is broken into two separate repositories:
There is a useful test course which contains a variety of configurations of ORA problems:
Using ORA with docker devstack
Note - anytime I say "from inside the lms", that means you've run 'make lms-shell' from the devstack directory and are on a command prompt inside the lms container.
- Clone edx-ora2 repo into ../src/ directory (relative to your 'devstack' repo location). If https://github.com/edx/devstack/pull/202 has been merged (or you're using my in flight branch), this will mount the directory in a way that is accessible to the lms container.
- From inside the lms, uninstall ora2 and reinstall your local copy. You can just copy the following line:
pip uninstall ora2 -y; pip install -e /edx/src/edx-ora2/
Now, get your edx-ora2 development environment set up: (the virtual environment MUST be named edx-ora2)
ensure that your virtual environment is named edx-ora2. Using a different name will cause errors when trying to generate translations.
- Now, in the devstack directory on your host, run:
make lms-restart lms-logs
- That's it, you're good to go! See Makefile for all the available commands, most are fairly self-explanatory
- In order to simulate a given tox environment (django18, django111, quality, js), run
tox -e <env> for the env in question (after re-activating your edx-ora2 virtual environment).
- Usually, you can just run the underlying make commands for quicker tests, as requirements aren't re-installed.
If you keep your containers running, you can return to your configured env very quickly - just cd /edx/src/edx-ora2; source edx-ora2/bin/activate from inside the lms and you're good to go. As of right this second, you need to repeat all these steps after restarting your container (because solving that problem is still in progress).
Special testing note: If your python tests fail with UnicodeEncodeErrors that look like this:
UnicodeEncodeError: 'ascii' codec can't encode character u'\xeb' in position 42: ordinal not in range(128), there's an easy fix. What's happening is that there are python tests (for the filesystem-based file upload backend) which will attempt to locate paths on the current box. One of these paths contains a weird unicode value that can cause problems. The fix is to ensure that your local system (the lms container) is using unicode. First, try
export LC_ALL='en_US.UTF-8'. If that failed with
/bin/bash: warning: setlocale: LC_ALL: cannot change locale (en_US.UTF-8), that just means your system doesn't have the required locale generated. Run
sudo locale-gen en_US.UTF-8, then retry the initial command.
Working with submission dependencies
ORA code also depends on edx-submissions. As a result, anytime a new version of edx-submissions is released, ORA code must be updated as follows.
make lms-shell # get into docker container
cd /edx/src/edx-ora2 # goto into ora2 folder
source edx-ora2/bin/activate # activate ora2 virtual environment
pip install -U edx-submissions # installs latest version of submissions from pypi
pip install -e /edx/src/edx-submissions # istalls local version of submissions
Available make commands
Release process documentation has moved to ORA2 Release Process
Running acceptance tests
The ORA acceptance and accessibility tests are written as Bok Choy tests that run against a sandbox.
First create a sandbox following the steps at Creating an ORA2 Sandbox
Now you can run the acceptance tests:
- Read the documentation: https://github.com/edx/edx-ora2/blob/master/test/acceptance/README.rst/
On your devstack, do the following:
(as edxapp user)
export ORA_SANDBOX_URL=https://staff:firstname.lastname@example.org (replace with name of your sandbox)
Debugging Python with PyCharm
The first step is to be able to debug into ORA2 source code when running Studio or LMS:
- Click on Run > "Edit Configurations..." (or choose it from the toolbar)
- For each configuration that might need ORA 2
- Select the configuration in question
- Click the "..." icon for the "Path Mappings" property
- In the modal that appears, click "+" to add a new mapping
- In the new row that appears, specify the local path to your ORA2 source code
- Then specify the remote path as:
- Hit OK
- Hit OK to save all the changes
The next step is to add a new remote interpreter which uses the ORA2 virtual env:
- Follow the steps to create a remote interpreter here:
- Before saving the new interpreter, change the "Python interpreter path" to point to the ORA2 virtual env:
- Note that this will have changed the default project interpreter to be your new one, so switch it back to your original
The final step is to add a debug configuration for running ORA2 tests:
- The simplest option is to clone an existing configuration, e.g. the one you use for running LMS
- Rename the configuration as "ORA Tests"
- Make sure that the script path is relative (./manage.py)
- Change the "Script Parameters" to "test" (this will run all the tests)
- Click on "Environment Variables":
- Click on "+" to add a new environment variable
- Specify the name as "DJANGO_SETTINGS_MODULE"
- Specify the value as "settings.test"
- Change the "Python interpreter" to select your new ORA2 remote interpreter
- Change the working directory to
- Click on "Path Mappings":
- Verify that you have a mapping for edx-ora2 (you should have created one in the previous section above)
- If not, follow the steps above to add one