Upgrading Opencast from 9.x to 10.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. Upgrade Java
  3. Replace Opencast with the new version
  4. Back-up Opencast files and database (optional)
  5. Upgrade the database
  6. Install and configure a standalone Elasticsearch node
  7. Review the configuration changes and adjust your configuration accordingly
  8. Remove search index data folder
  9. Start Opencast
  10. Rebuild the Elasticsearch indexes
  11. Check passwords
  12. Static file delivery

Upgrade Java

While Opencast 9 worked with both Java 8 and Java 11, Opencast 10 requires Java 11. Trying to start Opencast 10 with Java 8 will fail.

Either install both java versions and set Java 11 as default using something like:

update-alternatives --config java

Or replace the old Java version like this:

% dnf shell
> remove java-1.8.0-openjdk.x86_64
> install java-11-openjdk.x86_64
> run

Note that these commands can differ based on your distribution and your set-up. Make sure to adjust them accordingly.

Finally, check you have the correct version using:

% java --version
openjdk 11.0.11 2021-04-20
OpenJDK Runtime Environment 18.9 (build 11.0.11+9)
OpenJDK 64-Bit Server VM 18.9 (build 11.0.11+9, mixed mode, sharing)

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.

Wowza streaming configuration changes

In pull request #1179, the configuration of Wowza servers was made tenant-specific and has been moved to etc/org.opencastproject.distribution.streaming.wowza.WowzaStreamingDistributionService.cfg.

Additionally, support for RTMP was dropped. This shouldn't be a problem in most cases, as RTMP usually wasn't used before, despite being specified in the URL. If your streaming URL started with rtmp://, try changing it to https://.

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