Versions Compared


  • This line was added.
  • This line was removed.
  • Formatting was changed.


  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-url>/admin, for example,  The client details need to be available to the notes application   Note that in this document, the hostname 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.

    On Sandbox For Example
    User<leave blank><leave blank>
    Redirect urihttps://<your-notesserver-url>/complete/edx-oidc/https://<github_id>
    Client id<a big random string><generated>
    Client secret<a DIFFERENT big random string><generated>
    Client type

    Confidential (web application)

    Confidential (web application)

    Some of these values will be needed in /edx/app/edx_ansible/edx_ansible/playbooks/roles/edx_notes_api/defaults/main.yml, 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 and change to the master branch. Here are the command (details):

    Code Block
    sudo /edx/bin/update configuration master 
  3. Set the following values in /edx/app/edx_ansible/edx_ansible/playbooks/roles/edx_notes_api/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
      - 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
      - "*"

    Also set this value in playbooksin /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


  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 -i 'localhost,' -c local ./run_role.yml -e 'role=edxlocal' -e@roles/edx_notes_api/defaults/main.yml
  5. 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
  6. 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/manage.edx_notes_api migrate --settings="notesserver.settings.yaml_config"
  7. 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, make sure that FEATURES.ENABLE_EDXNOTES == true
  8. 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.