Upgrading to a new version#

When upgrading the Numbas LTI provider, follow the upgrade instructions for your platform.

Sometimes new versions of the LTI provider require changes that can’t be made automatically by the normal upgrade procedure.

For such releases, this page lists the changes that must be made.

v4.0#

Docker installation#

There are no special upgrade steps for Docker installations for this version.

Non-Docker installation#

The stable git branch for this version is v4_STABLE.

The minimum required version of Python is now 3.10.

There are changes to some values in settings.py, and new settings CACHES and REQUESTS_USER_AGENT.

There are changes to the extra Python packages required for production environments. Run this command to install them:

pip install channels_redis==4.2.0 psycopg2==2.9.9 redis==5.0.4

Add the following line to the top of numbasltiprovider/settings.py:

import pylti1p3.roles

Copy the values of the following objects from numbasltiprovider/settings.py.dist to numbasltiprovider/settings.py:

INSTALLED_APPS (adding 'daphne' and 'numbas_lti.apps.PyLTI1p3ToolConfigBigAutoField')
AUTHENTICATION_BACKENDS (replacing 'numbas_lti.backends.LTIAuthBackend' with 'numbas_lti.backends.LTI_11_AuthBackend' and 'numbas_lti.backends.LTI_13_AuthBackend')
STORAGES (replaces STATICFILES_STORAGE)
LTI_INSTRUCTOR_ROLES (there are separate lists for LTI 1.1 and LTI 1.3)
CACHES (new setting)
REQUESTS_USER_AGENT (new setting)
CANVAS_LTI_13_PRESETS (new setting)

Blackboard#

If you have an existing Numbas LTI link with Blackboard, the process for upgrading to LTI 1.3 is a bit fiddly.

When you register an LTI 1.3 connection, Blackboard will automatically upgrade all existing LTI 1.1 links to use it. However, it won’t update the launch URL automatically, effectively breaking those links.

So before registering the LTI 1.3 tool with Blackboard, you must edit the existing LTI 1.1 tool’s placement and change the target link URL. The end of the URL should change from /entry to /lti13/launch/. Note that the trailing slash on the end of the URL is important.

Once you have registered the LTI 1.3 tool, you should migrate the LTI 1.1 user aliases, so that user data for existing Numbas links is correct.

Run the following management command:

python manage.py upgrade_blackboard_lti_13

v3.2#

Docker installation#

There is a new setting for the lockdown app support:

NUMBAS_LOCKDOWN_APP_PASSWORD - a default password to use with the Numbas lockdown app.

Non-Docker installation#

There are new settings for the lockdown app support. Copy the LOCKDOWN_APP setting from numbasltiprovider/settings.py.dist into numbasltiprovider/settings.py, and change the 'password' value.

The installation instructions now recommend you regularly run the clearsessions command. See Set up regular maintenance jobs.

v3.0#

Docker installation#

There are a few new settings which must be present in settings.env. See Settings for information on the values these settings should take.

INSTANCE_NAME
TIME_ZONE
DEFAULT_FROM_EMAIL
SUPPORT_NAME
SUPPORT_URL
EMAIL_COMPLETION_RECEIPTS

Non-Docker installation#

This version updates many of the packages that the LTI tool relies on, and so introduces quite a few changes to the way that the tool is configured.

The minimum required versions of some software have increased:

Python 3.8 or newer
Redis 5 or newer

Git branch#

There are now stable git branches for each major version of the LTI provider. When upgrading to v3.0, switch to the v3_STABLE branch:

cd /srv/numbas-lti-provider
git fetch origin
git checkout v3_STABLE

After this, you can proceed with the rest of the update steps for your system. For Ubuntu, the next command will be source /opt/numbas_lti_python/bin/activate.

Packages to install#

There are changes to the required versions of packages specified in requirements.txt. In addition, if you are using Redis as the Channels backend, you will need to install channels_redis:

pip install channels_redis==3.3.1

Supervisor configuration#

Overwrite the configuration for supervisord with the new one given in the installation instructions for your system: Ubuntu, RHEL 7.

The numbas_lti_worker processes are no longer needed, and the command to launch the numbas_lti_daphne processes has changed.

Changes to settings#

There are several changes to make in the file numbasltiprovider/settings.py.

The template file, numbasltiprovider/settings.py.dist, has been rearranged and lots of comments added to better explain what the settings do. You might like to use that file as a base, and insert your existing settings, rather than just changing your existing file.

The way that Channels is configured has changed. To use Redis as the backend, replace the CHANNEL_LAYERS setting with the following:

CHANNEL_LAYERS = {
    "default": {
        "BACKEND": "channels_redis.core.RedisChannelLayer",
        "CONFIG": {
            "hosts": [os.environ.get('REDIS_URL','redis://localhost:6379')],
        }
    },
}

For other backends, see the Channels documentation.

Django now requires the DEFAULT_AUTO_FIELD setting to be set as follows:
```
DEFAULT_AUTO_FIELD='django.db.models.AutoField'
```
If you are using MySQL for your database, add the following underneath inside the 'default' entry in the DATABASES setting, in order to improve handling of Unicode characters:
```
'OPTIONS': {
    'charset': 'utf8mb4',
    'use_unicode': True,
},
```
You might need to convert the tables within MySQL to use the utf8mb4 character set and utf8mb4_unicode_ci collation rules. See this post by Mathias Bynens for instructions on how to do that.
The Huey task runner now prioritises tasks. Change the HUEY setting to the following:
```
HUEY = {
    'huey_class': 'huey.PriorityRedisHuey',
}
```
Add 'numbas_lti.context_processors.global_settings' to the TEMPLATES['OPTIONS']['context_processors'] setting.
There is a new setting INSTANCE_NAME, which should contain the name of the server, to display to users. If the server is run by the University of Somewhere, you might set:
```
INSTANCE_NAME = 'University of Somewhere'
```
There is a new setting REPORT_FILE_EXPIRY_DAYS, specifying the number of days that report files should remain available, before being deleted. The recommended length of time to keep reports is 30 days:
```
REPORT_FILE_EXPIRY_DAYS = 30
```
Remove 'django_cookies_samesite.middleware.CookiesSameSite' from MIDDLEWARE.

v2.13#

There was an error in the base settings.py file when localisation was introduced.

If you are using the English translation, in numbasltiprovider/settings.py, change LANGUAGE_CODE = 'en-us' to LANGUAGE_CODE = 'en'.

v2.11#

This release adds a dependency on the django-statici18n package to translate dynamically-generated text.

In numbasltiprovider/settings.py, add 'statici18n' to INSTALLED_APPS.

The whole list should now be:

INSTALLED_APPS = [
    'django.contrib.admin',
    'django.contrib.auth',
    'django.contrib.contenttypes',
    'django.contrib.sessions',
    'django.contrib.messages',
    'django.contrib.staticfiles',
    'channels',
    'huey.contrib.djhuey',
    'statici18n',
    'numbas_lti',
    'bootstrapform',
    'bootstrap_datepicker_plus',
]

v2.10#

This release uses the task runner huey to perform long-running tasks.

In numbasltiprovider/settings.py, add 'huey.contrib.djhuey to INSTALLED_APPS.

The whole list should now be:

INSTALLED_APPS = [
    'django.contrib.admin',
    'django.contrib.auth',
    'django.contrib.contenttypes',
    'django.contrib.sessions',
    'django.contrib.messages',
    'django.contrib.staticfiles',
    'channels',
    'huey.contrib.djhuey',
    'numbas_lti',
    'bootstrapform',
    'bootstrap_datepicker_plus',
]

Add a huey process to the supervisord configuration (in /etc/supervisor/conf.d/numbas_lti.conf on Ubuntu):

[program:numbas_lti_huey]
command=/opt/numbas_lti_python/bin/python /srv/numbas-lti-provider/manage.py run_huey -w 8
directory=/srv/numbas-lti-provider/
user=numbas_lti
autostart=true
autorestart=true
redirect_stderr=True
stopasgroup=true
environment=DJANGO_SETTINGS_MODULE="numbasltiprovider.settings"
numprocs=1
process_name=%(program_name)s_%(process_num)02d
stderr_logfile=/var/log/supervisor/numbas_lti_huey_stderr.log
stdout_logfile=/var/log/supervisor/numbas_lti_huey_stdout.log

[group:numbas_lti]
programs=numbas_lti_daphne,numbas_lti_workers,numbas_lti_huey
priority=999

Note that the [group:numbas_lti] section has changed as well.

Upgrading to a new version

Contents

Upgrading to a new version#

v4.0#

Docker installation#

Non-Docker installation#

Blackboard#

v3.2#

Docker installation#

Non-Docker installation#

v3.0#

Docker installation#

Non-Docker installation#

Git branch#

Packages to install#

Supervisor configuration#

Changes to settings#

v2.13#

v2.11#

v2.10#