Upgrading Opencast from 8.x to 9.x

This guide describes how to upgrade Opencast 8.x to 9.x. In case you need information about how to upgrade older versions of Opencast, please refer to older release notes.

Stop your current Opencast instance
Replace Opencast with the new version
Back-up Opencast files and database (optional)
Upgrade the database
Install and configure a standalone Elasticsearch node
Review the configuration changes and adjust your configuration accordingly
Remove search index data folder
Start Opencast
Rebuild the Elasticsearch indexes
Check passwords
Static file delivery

Database Migration

There are two parts to the Opencast 9 database migration:

Two database tables become unnecessary with Opencast 9 and can be dropped. Opencast provides database upgrade script which include all necessary SQL commands. You will find them in docs/upgrade/8_to_9/. This script is suitable for both, MariaDB and MySQL.
Opencast no longer needs scripts to manually create the database structure. This will now happen automatically and Opencast 9 will create a new table on its first run. This means that Opencast's database user now needs additional priviledges. Please consult the database configuration guide for more details.

Configuration Changes

Note that this section will only highlight a few important changes. Please make sure to compare your configuration against the current configuration files.

The default for the configuration option lti.create_jpa_user_reference changed from false (Opencast 8.3) to true.
Make sure to have ?useMysqlMetadata=true appended to org.opencastproject.db.jdbc.url if you use MariaDB as database.
Opencast Studio now uses TOML instead of JSON as configuration format. Additionally, the ACL template is now specified as a string in the TOML file and not as a separate file (usually acl.xml) anymore. Finally, the variables passed into the Mustache ACL template have changed. For more information, see this document.
The configuration keys source-tags and source-flavors of the publish-configure workflow operation were renamed to download-source-tags and download-source-flavors respectively. If you use custom workflows, you may need to adjust them accordingly.

Install and configure a standalone Elasticsearch node

Although Opencast has come with its own integrated Elasticsearch node in the past, recent versions of Elasticsearch no longer support being embedded in applications. Since the Elasticsearch client was updated to version 7, Opencast requires an external Elasticsearch node of the same version to be present. This means all Opencast adopters now have to run Elasticsearch as a service.

Please check the installation guides for information about how to setup Elasticsearch.

If you already used an external Elasticsearch node in the past, please update your node to version 7. Since the index schema has changed, you will need to drop your indices and rebuild them.

Rebuild the Elasticsearch Indexes

In order to populate the external Elasticsearch index, an index rebuild is necessary.

Admin Interface

Stop Opencast, delete the index directory at data/index, restart Opencast and make an HTTP POST request to /admin-ng/index/recreateIndex.

Example (using cURL):

curl -i --digest -u <digest_user>:<digest_password> -H "X-Requested-Auth: Digest" -s -X POST \
  https://example.opencast.org/admin-ng/index/recreateIndex

You can also just open the REST documentation, which can be found under the “Help” section in the admin interface (the “?” symbol at the top right corner). Then go to the “Admin UI - Index Endpoint” section and use the testing form on /recreateIndex to issue a POST request.

In both cases you should get a 200 HTTP status.

External API

If you are using the External API, then also trigger a rebuilt of its index by sending an HTTP POST request to /api/recreateIndex.

Example (using cURL):

curl -i --digest -u <digest_user>:<digest_password> -H "X-Requested-Auth: Digest" -s -X POST \
  https://example.opencast.org/api/recreateIndex

You can also just open the REST documentation, which can be found under the “Help” section in the admin interface (the “?” symbol at the top right corner). Then go to the “External API - Base Endpoint” section and use the testing form on /recreateIndex.

In both cases you should again get a 200 HTTP status.

Check Passwords

Since Opencast 8.1 passwords are stored in a much safer way than before but to benefit from this mechanism, users have to reset their password.

You can use the endpoint /user-utils/users/md5.json to find out which users are still using MD5-hashed passwords and suggest to them that they update their passwords.

Static File Delivery

Opencast 9.2 came with a completely new system for securing static file content which is now active by default in Opencast 10. If you are deferring the file access authorization to another system using Opencast's security token mechanism, you need to deactivate this protection in:

etc/org.opencastproject.fsresources.StaticResourceServlet.cfg