Page Comparison

This is the process for getting edX notes running today.  There are a few gaps in automation that will require some manual steps.  , both on a shared server with the LMS and other services, and on its own server. This guide assumes that you have a running LMS.  This also assumes that you are running all your services on a single host.   While this configuration is not recommended for production deployments, this should be enough to get you started.

...

1. In order for the edx_notes_api application to authenticate against the LMS, an oauth client configuration will need to be created in your LMS.  This can be done from the Django admin application as a superuser.  The admin application is hosted at https://<your-lms.example.com-url>/admin, for example, https://courses.edx.org/admin.   The  The client details need to be available to the notes application   Note that in this document, the hostname lms.example.com will be used, but this value will need to be replaced with the appropriate value for your environment.
   
   On the admin page, to go "Oath2" and click "Add" by "Clients". Fill out the following fields (after looking up your user ID). Note: leave the ID field blank.

   Key

    name

   	On Sandbox For Example
   User	<leave blank>	<leave blank>
   Name	edx-notes	edx-notes

   url

   Url

   https://<your-notesserver-url>

   https://

   notes.example.com/redirect url

   <github_id>.sandbox.edx.org:18120
   Redirect uri	https://<your-notesserver-url>/complete/edx-oidc/	https://

   notes.example.com

   <github_id>.sandbox.edx.org:18120/complete/edx-oidc

   /client

   Client id

   edx_notes_idclient secretedx_notes_secretclient typeconfidential

   	<a big random string>	<generated>
   Client secret	<a DIFFERENT big random string>	<generated>
   Client type	Confidential (web application)	Confidential (web application)

   The values provided here correspond to the values in the Some of these values will be needed in /edx/app/edx_ansible/edx_ansible/playbooks/roles/edx_notes_api/defaults/main.yml.  You can change these values to whatever you wish as long as the values in the role defaults are also overridden, so take note of them now.
   
   

2. You will have to use master of the configuration repository to pull in some changes related to installing notes, so fetch the latest of of https://github.com/edx/configuration and  and change to the master branch. Here is are the command (details):

   Code Block
   sudo /edx/bin/update edx-platformconfiguration mastermaster

3. Install the database user for the Set the following values in /edx/app/edx_ansible/edx_ansible/playbooks/roles/edx_notes_api.  Notes needs to connect to a mysql database and an elasticsearch instance.  Review all the ALL CAPS variables defined in https://github.com/edx/configuration/blob/master/playbooks/roles/edx_notes_api/defaults/main.yml to understand what you need to override. 
   /defaults/main.yml:

   Code Block

   EDX_NOTES_API_MYSQL_DB_PASS: <desired password for your notes user> EDX_NOTES_API_MYSQL_HOST: <mysql hostname> EDX_NOTES_API_ELASTICSEARCH_URL: <url of elasticsearch cluster> EDX_NOTES_API_DATASTORE_NAME: <desired name of mysql db and elasticsearch index, e.g. "notes"> EDX_NOTES_API_SECRET_KEY: <random string, min 50 characters recommended> EDX_NOTES_API_CLIENT_ID: <client id from oauth config> EDX_NOTES_API_CLIENT_SECRET: <client secret from oauth config>

   You also need the following override:

   Code Block
   EDX_NOTES_API_ALLOWED_HOSTS: - localhost - <your-lms-url>

   If you have a load balancer running in front of multiple notes api servers, you might instead have to set it to the following:

   Code Block
   EDX_NOTES_API_ALLOWED_HOSTS: - "*"

   Also set this value in /edx/app/edx_ansible/edx_ansible/playbooks/roles/edxapp/defaults/main.yml:

   Code Block
   EDXAPP_EDXNOTES_PUBLIC_API: https://<your-notesserver-url>:18120/api/v1 EDXAPP_EDXNOTES_INTERNAL_API: https://<your-notesserver-url>:18120/api/v1 FEATURES: ENABLE_EDXNOTES: true

    

4. Now create your database users. First, you will need to activate the venv (Python virtual environment) for ansible.

   Code Block
   source /edx/app/edx_ansible/venvs/edx_ansible/bin/activate

   
   Assuming that you have a local checkout of the edx configuration repository, you can create the required database users by running

   Code Block
   cd /edx/app/edx_ansible/edx_ansible/playbooks ansible-playbook -c local -i 'localhost,' -c local ./run_role.yml -e 'role=edxlocal' -e@roles/edx_notes_api/defaults/main.yml

5. Create a file for your ansible overrides ~/ansible-overrides.yml with at least the following values

   Code Block
   EDX_NOTES_API_ALLOWED_HOSTS: - localhost - lms.example.com

6. Enable this feature flag in EDXAPP_FEATURES:

   Code Block
   ENABLE_EDXNOTES: true

7. You will need to override the value of EDXNOTES_INTERFACE for your installation.  This currently isn't handled by ansible, but will be.  The recommendation is to add the following to your lms/envs/aws.py

   Code Block
   EDXNOTES_INTERFACE = { 'url': 'http://lms.example.com:18120/api/v1', }

8. Install the edx-notes-api using ansible

   Code Blockansible-playbook -c local -

   Install the edx-notes-api using ansible

   Code Block
   cd /edx/app/edx_ansible/edx_ansible/playbooks/edx-east ansible-playbook -i 'localhost,' -c local ./notes.yml -e@/edx/app/edx_ansible/server-vars.yml

   When the installation has completed verify that the notes api is healthy by running

   Code Block
   sudo /edx/bin/supervisorctl status edx_notes_api edx_notes_api RUNNING pid 13630, uptime 11:42:01

   In order to enable the notes application in the LMS and CMS you will have to set the ENABLE_EDXNOTES feature flag to true in both lms.env.json and cms.env.json and restart both the LMS and CMS.

   Code Block
   sudo

9. Run Migrations 

   Code Block
   export EDXNOTES_CONFIG_ROOT=/edx/etc/ # Defaults to 'migrate' export DB_MIGRATION_USER=<migration_username> # Defaults to 'password' export DB_MIGRATION_PASS=<migration_password> /edx/bin/python.edx_notes_api /edx/bin/supervisorctl restart edxapp:*

   After the feature has been enabled, an

   manage.edx_notes_api migrate --settings="notesserver.settings.yaml_config"

10. An advanced setting in Studio must also be enabled on a per course basis.  From the advanced settings tab for your course, set 
    Enable Student Notes to true.  If you don't see that advanced setting, review the changes from step 7 and ensure you have restarted your LMS and CMSmake sure that FEATURES.ENABLE_EDXNOTES == true
11. Navigate to the courseware for any course with edX Notes enabled.  From the courseware you should be able to highlight text and add notes.  If there are errors, check both the LMS logs, /edx/var/log/lms/edx.log, and the edx_notes_api logs, /edx/var/log/supervisor/edx_notes_apitderr.log.

...

Related articles