Upgrading Opencast from 10.x to 11.x
This guide describes how to upgrade Opencast 10.x to 11.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
- Read the release notes (especially the section of behaviour changes)
- Review the configuration changes and adjust your configuration accordingly
- Do the database migration
- Migrate, rebuild or rename Elasticsearch index
- Start Opencast if you haven't already done so
Upgrading to Opencast 11 requires a DB migration, as some tables have changed slightly.
Migration scripts can be found in
There are separate scripts for MariaDB/MySQL (
mysql5.sql) and PostgreSQL (
In Opencast 11, instead of having two separate Elasticsearch indices for the Admin UI and the External API that share most of their content, there will be only one index supporting both. Since this index will have a new name, this index will either have to be rebuilt from scratch (Option 1), or you can migrate your Admin UI index (Option 2), since its structure is completely identical to the new index. However, if you don't care about accuracy, you could just keep using the Admin UI index (Option 3).
Please read all options and commit to one before taking any action.
Option 1: Rebuild
Start your new Opencast and make an HTTP POST request to
Example (using cURL):
curl -i -u <admin_user>:<password> -s -X POST https://example.opencast.org/index/rebuild
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 “Index Endpoint” section and use the testing form on
/rebuild to issue a POST request.
In both cases you should get a 200 HTTP status.
Option 2: Migration
Some important notices before you start:
- Please take a quick look at the scripts before using them and adjust them if needed.
- Do not start your new Opencast before or during migration of the index (at least on the Admin node)!
Starting Opencast before migration will create a new empty index which will later cause the cloning process to fail.
(To fix this, delete all subindices of the new index -
opencast_version- before attempting migration again. You could use a modified version of
delete-old-indices.shto do this or pick out the relevant commands and do it manually. Make sure you remove the correct subindices for the new index, not the old ones!) Running Opencast during migration (whether with the new or old indices) can result in inconsistent data during cloning. Do not do this!
- By default the cloning process will not copy over the index metadata and the two index settings
auto_expand_replicas. The script will set
number_of_replicasto 0 (assuming you have a single node) and
auto_expand_replicasto false (the default). This should be fine for most people, but if you have a more intricate setup, you might need to change these.
- The cleanup script will also attempt to delete the group indices that are no longer used since OC 10. If you started with OC 10 or already removed them, this will fail, but that's okay.
- Before removing the old indices, please start Opencast and test the new index first!
To migrate your index, you can use the
migrate-indices.sh bash script contained in
This will clone the Admin UI index to an index with the new name. If your storage supports hardlinks, the cloning
process should be pretty quick.
If you then want to clean up the old indices, you can use
delete-old-indices.sh for this.
Option 3: Keep the Admin UI index
If you don't have time for either and if you don't care about having an exact index identifier in your Elasticsearch,
you could also just set
org.opencastproject.elasticsearch.index.ElasticsearchIndex to "adminui"
to keep using the old admin ui index. Do this before starting Opencast to avoid creating a new index.
The external API index can then be removed. (Please be aware that the External API index cannot be used any longer since
it doesn't contain the themes.) You can use a modified version of
delete-old-indices.sh to do this (make sure
to remove only the External API sub indices and not the Admin UI ones you're currently using!)