An app for integrating Hypothesis with Learning Management Systems (LMS's).

See also:

• Configuration - Details of environment variables and setup
• Setting up a region - How to setup a new geographic region

First you'll need to install:

• Git. On Ubuntu: sudo apt install git, on macOS: brew install git.
• GNU Make. This is probably already installed, run make --version to check.
• pyenv. Follow the instructions in pyenv's README to install it. The Homebrew method works best on macOS. The Basic GitHub Checkout method works best on Ubuntu. You don't need to set up pyenv's shell integration ("shims"), you can use pyenv without shims.
• Docker Desktop. On Ubuntu follow Install on Ubuntu. On macOS follow Install on Mac.
• Node and npm. On Ubuntu: sudo snap install --classic node. On macOS: brew install node.
• Yarn: sudo npm install -g yarn.

Then to set up your development environment:

git clone https://github.com/hypothesis/lms.git
cd lms
make services
make devdata
make help

To run LMS locally run make dev and visit http://localhost:8001.

To change what version of Python the project uses:

1. Change the Python version in the cookiecutter.json file. For example:

   "python_version": "3.10.4",

2. Re-run the cookiecutter template:

   make template
   

3. Re-compile the requirements/*.txt files. This is necessary because the same requirements/*.in file can compile to different requirements/*.txt files in different versions of Python:

   make requirements
   

4. Commit everything to git and send a pull request

Add the package to the appropriate requirements/*.in file(s) and then run:

make requirements

Remove the package from the appropriate requirements/*.in file(s) and then run:

make requirements

We rely on Dependabot to keep all our dependencies up to date by sending automated pull requests to all our repos. But if you need to upgrade or downgrade a package manually you can do that locally.

To upgrade a package to the latest version in all requirements/*.txt files:

make requirements --always-make args='--upgrade-package <FOO>'

To upgrade or downgrade a package to a specific version:

make requirements --always-make args='--upgrade-package <FOO>==<X.Y.Z>'

To upgrade all packages to their latest versions:

make requirements --always-make args=--upgrade

By default make dev runs the web application on two ports: 8001 for HTTP and 48001 for HTTPS with a self-signed certificate.

Using HTTPS is required in most LMS's for LTI 1.3 and for example in D2L it's required for any usage of their API in all LTI versions.

To use HTTPS you'll need to instruct your browser to trust the self-signed certificate.

In Chrome you can do do this with the following flag:

chrome://flags/#allow-insecure-localhost

If you use our hosted Canvas instance at https://hypothesis.instructure.com/ to test your local dev instance of the app you'll get "unsafe scripts" or "mixed content" warnings from your browser. This is because hypothesis.instructure.com uses https but your local dev app, which is running in an iframe in hypothesis.instructure.com, only uses http.

You'll see a blank iframe in Canvas where the app should be, along with a warning about "trying to launch insecure content" like this:

If you open the browser's developer console you should see an error message like:

Mixed Content: The page at 'https://hypothesis.instructure.com/...' was loaded over HTTPS,
but requested an insecure form action 'http://localhost:8001/...'. This request has been
blocked; the content must be served over HTTPS.

Fortunately you can easily bypass this mixed content blocking by your browser. You should also see an "Insecure content blocked" icon in the top right of the location bar:

Click on the Load unsafe scripts link and the app should load successfully.

Some services that the LMS app integrates with (eg. Canvas Studio) do not allow the use of localhost in OAuth callback URLs. For this reason we use https://hypothesis.local URLs in some places. To make this work you must declare hypothesis.local as an alias for 127.0.0.1 in your /etc/hosts file.

There are three presentations for developers that describe what the Hypothesis LMS app is and how it works. The speaker notes in these presentations also contain additional notes and links:

1. LMS App Demo & Architecture
2. LMS App Code Design Patterns
3. Speed Grader Workshop (about the design of the first version of our Canvas Speed Grader support)