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:
- LMS App Demo & Architecture
- LMS App Code Design Patterns
- Speed Grader Workshop (about the design of the first version of our Canvas Speed Grader support)
-
The LMS app integrates h, the Hypothesis client, Via 3, and Via, so you will need to set up development environments for each of those before you can develop the LMS app:
-
Node and npm. On Linux you should follow nodejs.org's instructions for installing node because the version of node in the standard Ubuntu package repositories is too old. On macOS you should use Homebrew to install node.
-
Docker. Follow the instructions on the Docker website to install "Docker Engine - Community".
-
pyenv Follow the instructions in the pyenv README to install it. The Homebrew method works best on macOS.
-
pg_config. On Ubuntu:sudo apt install libpq-dev. On macOS:brew install postgresql.
git clone https://github.com/hypothesis/lms.git
This will download the code into an lms directory in your current working
directory. You need to be in the lms directory from the remainder of the
installation process:
cd lms
Start the services that the LMS app requires using Docker Compose:
make services
Create the database contents and environment variable settings needed to get lms working nicely with your local development instances of the rest of the Hypothesis apps, and with our test LMS sites (Canvas, Blackboard, ...):
make devdata
Creating data and settings manually instead
make devdata requires you to have a git SSH key set up that has access to the
private https://github.com/hypothesis/devdata repo. Otherwise it'll crash. If
you aren't a Hypothesis team member and don't have access to the devdata repo,
or if you're installing the app in a production environment, you can follow
these instructions to create the necessary data and settings manually:
make dev
The first time you run make dev it might take a while to start because it'll
need to install the application dependencies and build the client assets.
This will start the server on port 8001 (http://localhost:8001), reload the application whenever changes are made to the source code, and restart it should it crash for some reason.
That's it! You’ve finished setting up your lms development environment. Run
make help to see all the commands that're available for running the tests,
linting, code formatting, Python and SQL shells, etc.
You should now be able to run the tests successfully by typing:
make test
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.