Course Discovery plugin for Tutor

This is a plugin for Tutor that integrates the Course Discovery application in an Open edX platform. it is useful for integration with, for example, Ecommerce or an external course catalog.

Installation

This plugin requires tutor>=3.6.0. If you have installed tutor from a pre-compiled binary, it already comes bundled with the discovery plugin. Otherwise:

tutor plugins install discovery

Then, to enable this plugin, run:

tutor plugins enable discovery

Restart and initialize your platform with:

tutor dev|local|k8s launch

Operations

Creating a user

The discovery user interface will be available at http://discovery.local.openedx.io for a local test instance, and at DISCOVERY_HOST (by default: http(s)://discovery.<your lms host>) in production. To run commands from the UI, a user must be created:

tutor local run discovery ./manage.py createsuperuser

Then, you must log in with this user at http://discovery.local.openedx.io/admin.

Using SSO with LMS

If you want to log in using Single Sign-On (SSO) with the LMS, ensure that the superuser you created above in discovery has the same username and email as an existing admin user in the LMS/CMS. You can then access the discovery interface via http(s)://discovery.<your lms host>/login. Make sure that the proper domain names are configured and point to the production server.

Index configuration

Discovery uses separate indices for different models (the names are: course, course_run, person, and program by default). And you can overwrite these names by configuring DISCOVERY_INDEX_OVERRIDES:

DISCOVERY_INDEX_OVERRIDES:
  course_discovery.apps.course_metadata.search_indexes.documents.course: your-course-index-name
  course_discovery.apps.course_metadata.search_indexes.documents.course_run: your-course-run-index-name
  course_discovery.apps.course_metadata.search_indexes.documents.person: your-person-index-name
  course_discovery.apps.course_metadata.search_indexes.documents.program: your-program-index-name

Re-indexing courses

While running tutor in production mode:

tutor local run discovery ./manage.py refresh_course_metadata --partner_code=openedx
tutor local run discovery ./manage.py update_index --disable-change-limit

While running tutor in development mode:

tutor dev run discovery ./manage.py refresh_course_metadata --partner_code=dev
tutor dev run discovery ./manage.py update_index --disable-change-limit

Caching programs

To cache programs in the LMS, you will need to manually create a catalog integration. Make sure you use staff user for the below command. If lms_catalog_service_user is not a staff user, then make it a staff user in your LMS User model. This step should be performed just once:

tutor local run lms ./manage.py lms create_catalog_integrations --enabled \
    --internal_api_url="" \
    --service_username=lms_catalog_service_user

Then run the below command, this command will cause errors every time it tries to cache programs from all sites that are added to your LMS sites model:

tutor local run lms ./manage.py lms cache_programs

The above command will give some errors as it tries to cache programs for all sites. So make use of an extra argument to the command. i.e. --domain. While running tutor in production mode:

tutor local run lms ./manage.py lms cache_programs --domain="local.openedx.io"

While running tutor in development mode:

tutor dev run lms ./manage.py lms cache_programs --domain="local.openedx.io:8000"

This last step should be performed every time you create new or make changes to existing programs.

Show Programs Tab

By default, the Programs tab is available in the LMS dashboard. Users can enable or disable this tab as needed. To Disable Programs, run the following command:

tutor config save --set ENABLE_PROGRAMS=False

To Enable Programs, run the following command:

tutor config save --set ENABLE_PROGRAMS=True

Only programs in which learners are registered will appear on this page. If a learner is enrolled in any course that is part of a program, that program will be displayed here.

In the image above, the Explore Programs button points to http://localhost:8080/programs by default. This link does not exist, so users can change it to their custom-built marketing site URL to display all programs. To Modify the Link:

1. Go to the Site Configurations model in the LMS Admin Panel: http://local.openedx.io/admin/site_configuration/siteconfiguration/
2. Open the respective LMS site configuration.
3. Add the following dictionary in the site values field like in the below image:

"MKTG_URLS": {
    "ROOT": "https://custom-marketing-site-here.com"
}

By following above instructions, this link (https://custom-marketing-site-here.com) will be replaced by http://localhost:8080. Additionally, users can also replace "/programs" by following these below steps:

1. Go to: http://local.openedx.io/admin/programs/programsapiconfig/
2. Add Marketing path equal to "/programs" or your desired marketing site path and enable it.

Install extra requirements

To install extra requirements, use DISCOVERY_EXTRA_PIP_REQUIREMENTS and re-build the docker image.

tutor config save --set 'DISCOVERY_EXTRA_PIP_REQUIREMENTS=["git+https://github.com/myusername/myplugin"]'

Then, build the image, pointing to your fork if necessary:

tutor images build discovery

Debugging

To debug the course discovery service, you are encouraged to mount the course-discovery repo from the host in the development container:

tutor dev start --mount /path/to/course-discovery/ discovery

You can then access the development server at http://discovery.local.openedx.io:8381. Feel free to add breakpoints (import pdb; pdb.set_trace()) anywhere in your source code to debug your application.

Once a local repository is mounted in the image, you will have to install nodejs dependencies and collect static assets:

tutor dev run discovery npm install --development
tutor dev run discovery make static.dev

Max retries exceeded with url

When running in production with HTTPS enabled, you may face this error during the init phase of tutor local launch:

requests.exceptions.ConnectionError: HTTPSConnectionPool(host='<LMS_HOST>', port=443): Max retries exceeded with url: /api/courses/v1/courses/?page=1&page_size=10&username=discovery

This error may be due to an incorrect DNS resolution of the LMS DNS record. With some cloud providers (for instance: DigitalOcean) the /etc/hosts file on the host automatically contains the following entry:

127.0.1.1 <LMS HOST>

This entry may be present if you named your server with the LMS hostname.

Using event-bus with tutor-discovery

Although tutor-discovery does not start event bus consumption by default, it supports running it. To consume events from event bus with tutor-discovery, follow these instructions provided by event-bus-redis.

Troubleshooting

This Tutor plugin is maintained by Muhammad Faraz Maqsood from Edly. Community support is available from the official Open edX forum. Do you need help with this plugin? See the troubleshooting section from the Tutor documentation.

License

This work is licensed under the terms of the GNU Affero General Public License (AGPL).