Deploy new Ontocloak version

From time to time new Ontocloak versions will need to be deployed to add enhancements, update dependencies (e.g. for security updates), and fix defects. This is particularly true to keep up to date with the underlying Keycloak software.

Ontocloak, like all of the CSIRO components, is delivered as a Docker image, significantly simplifying update processes.

Prior to deploying a new version of Ontocloak, the database Ontocloak is using should be backed up / restorable to a recent point prior to deployment of the new updated version. It is recommended that a backup be taken immediately prior to deploying the update.

Installing a new update

Installing a new updated version requires

  1. pulling a new Ontocloak Docker image from a repository, or installing a image tarball (depending upon how software versions are deployed in your Docker setup)
  2. recreating the Ontocloak container

Step 2 above requires a short outage to stop the old container and create a new container which uses the new image, both versions cannot coexist using the same database at the same time. To gain confidence prior to performing this update, a test update can be performed by booting the Docker image against a clone of Ontocloak’s database schema to trial run the update.

The boot time of Ontocloak is short (typically a minute) and the longest part of this process is pulling the new Docker image, so this should be done before the Ontocloak container is stopped and the new one started to minimise the outage. A short outage is likely to have very little impact on system usage as access tokens do not require refresh for some time, therefore the complexity of designing a zero down time software upgrade process for Ontocloak deployments is unnecessary.

Database schema migration

Any database schema changes required by the new version of Ontocloak will be made by the new instance of Ontocloak when it is booted from the new Docker image by underlying functionality in Keycloak. There are no manual steps required.

Rollback

Unlike automated forward database migration in new Ontocloak versions, no automated downgrade capability is built into Ontocloak.

Rollback is performed by

  1. Shutting down the Ontocloak container
  2. Restoring the Ontocloak’s database to a state prior to the upgrade
  3. Recreate the Ontocloak container using the previous Docker image