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.

  1. Stop your current Opencast instance
  2. Replace Opencast with the new version
  3. Back-up Opencast files and database (optional)
  4. Upgrade the database
  5. Install and configure a standalone Elasticsearch node
  6. Review the configuration changes and adjust your configuration accordingly
  7. Remove search index data folder
  8. Start Opencast
  9. Rebuild the Elasticsearch indexes
  10. Check passwords
  11. Static file delivery

Database Migration

There are two parts to the Opencast 9 database migration:

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.

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