Install Open edX Notes & Annotations

Summary

Open edX Notes & Annotations is one of the coolest, most value-added upgrades that you can add to your Open edX Native build. Hopefully some day it will ship with the platform’s core functionality, but until then this post will help you get Notes & Annotations up and running on your Ginkgo installation (or later) in just a couple of hours. Notes itself is a Django app which largely follows the conventions of norms of the rest of the Open edX ecosystem. Technically speaking, it’s beautifully designed, works great, and really showcases the edX design team’s ability to thread the needle when it comes to enhancing the user experience while keeping the platform manageable.

Setup Procedure

We’ll use Ansible for most of the installation, leaving us with just a few chores beforehand and some cleanup activities afterwards. Here’s our installation and setup procedure:

1. Setup Oauth between LMS and the Notes API

First, we’ll use the Django admin console of the LMS to setup seamless Oauth authentication between the LMS and the Notes API. You’ll need to login using a super user account. You can review the “Managing Open EdX Tips and Tricks” page for instructions on how to convert your account. For the Python/Django uninitiated, Django apps like LMS and CMS come with a “back end” admin console where additional configuration parameters are available beyond what you’ll find in the four JSON files in /edx/app/edxapp/. Refer to this screen shot for the URL path and guidelines for creating your Oauth client.

2. Set Configuration Parameters

Take note that what follows is an unorthodox approach compared to most other configuration activities you’ll perform on your Open edX installation, but so far I haven’t come up with a better alternative.

A. Set Ansible Parameters

First, we’ll edit the Ansible Notes API defaults parameters file that is part of the edx “Configuration” github repository: /edx/app/edx_ansible/edx_ansible/playbooks/roles/edx_notes_api/defaults/main.yml. Following are the exact parameters that we’ll modify.

• EDX_NOTES_API_MYSQL_DB_PASS – Choose a new strong password that the Notes user will pass to MySQL when connecting to the Notes database.
• EDX_NOTES_API_MYSQL_HOST – This is “localhost” by default on Native installations unless you have migrated your MySQL environment elsewhere.
• EDX_NOTES_API_ELASTICSEARCH_URL – set this to “localhost:9200”
• EDX_NOTES_API_DATASTORE_NAME – This is the name of the MySQL database that Ansible will create for you. Use a simple, sensible name like “notes”
• EDX_NOTES_API_SECRET_KEY – Choose a new strong password of at least 16 characters.
• EDX_NOTES_API_CLIENT_ID – This is the “Client ID” value from the Oauth setup screen from the previous step
• EDX_NOTES_API_CLIENT_SECRET – This is the “Client Secret” value from the Oauth setup screen from the previous step
• EDX_NOTES_API_ALLOWED_HOSTS – add a new item to this list containing the fully qualified domain name of your LMS. See my example below (Row 50)

Following is an example showing how your Oauth configuration from step 1 should map to your Ansible parameter values in this step.

B. Set Application Parameters

Next we’ll edit the LMS environment configuration to enable Notes in the front end: /edx/app/edxapp/lms.env.json. There are three sets of changes within the Open edX platform json configuration files:

1. EDXNOTES_INTERNAL_API & EDXNOTES_PUBLIC_API (row 154): The Notes application relies on a REST api that is authenticated by the LMS via Oauth. The API provides the annotation highlight meta data along with descriptive and tag data that the learner might have provid