Installation with Docker

Installation with Docker#

You will need:

  • Access to a server where you can run Docker and Docker Compose. A virtual machine is fine.

  • A domain name pointed at the server you’re going to use. A subdomain (e.g. numbas-lti.youruniversity.edu) is fine.

  • An SSL certificate: LTI content must be served over HTTPS. These can be obtained easily and for free from Let’s Encrypt.

These instructions will run the Numbas LTI provider inside a Docker container, along with containers for the services it requires.

Setup#

Obtain the Docker compose recipe and its associated files either by downloading the latest release from GitHub, or by cloning the git repository:

git clone https://github.com/numbas/numbas-lti-provider-docker.git

Build the docker image:

docker build . -t numbas/numbas-lti-provider

Copy the file settings.env.dist to settings.env and write your own values for each of the variables inside.

Run the get_secret_key script to generate a value for the SECRET_KEY environment variable, and put that in settings.env:

docker compose run --rm numbas-setup python ./get_secret_key

Obtain an SSL certificate and key for the domain you will access the Numbas LTI provider from. Copy the key to files/ssl/numbas-lti.key and the certificate to files/ssl/numbas-lti.pem.

Run the installation script, to set up the database and create the superuser account:

docker compose run --rm numbas-setup python ./install

The LTI provider is ready to start.

Starting#

Run the following command:

docker compose up --scale daphne=4 --scale huey=2

You can customise the number of each of the kinds of process by changing the numbers in the –scale arguments. You’ll have to establish how many of each you need by experimentation. The daphne process handles web requests; you will need more if you have lots of simultaneous connections. The huey process runs asynchronous tasks; you will need more if you find that tasks such as reporting scores or generating report files take a very long time.

Stopping#

Stop the containers with:

docker compose down

This does not delete any permanent data such as the database, settings file or uploaded files.

Upgrading#

When there is a new version of the Numbas LTI provider, you must rebuild the Docker image and apply any database migrations.

If any other changes are required when moving to a particular version, they will be listed on the Upgrading to a new version page.

First, update the files in the Docker repository. If you used git, run:

git pull

Remake the container image:

docker build . --no-cache -t numbas/numbas-lti-provider

Then run the installation script again:

docker compose run –rm numbas-setup python ./install

Finally, restart the containers:

docker compose restart

Running in the cloud#

Docker Compose files can also be used to deploy to the cloud. See the following documents for more information about deploying Docker to the cloud:

Contents