Deploy new Ontoserver version

Prior to deploying a new version of Ontoserver which holds unrecoverable persistent data (typically the Authoring server), at least Ontoserver’s database should be backed up / restorable to a recent point prior to deployment of the new updated version. For a fast rollback/recovery the filesystem storage should also be backed up. It is recommended that these backups be taken immediately prior to deploying the update.

General process

The subsections below outline the general process. Specific processes will vary depending upon the endpoint the Ontoserver instance is supporting, whether it has persistent storage etc. These issues are discussed in following sections.

Installing a new update

Installing a new updated version requires

  1. pulling a new Ontoserver Docker image from a repository, or installing a image tarball (depending upon how software versions are deployed in your Docker setup)
  2. recreating the Ontoserver 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 much the same as a content deployment – see Content release process.

The boot time of Ontoserver is short (typically under a minute) and the longest part of this process is pulling the new Docker image, so this should be done before the Ontoserver container is stopped and the new one started to minimise the outage.

Database schema migration

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

Rollback

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

Rollback is performed by

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

Additionally to step 2 it may be necessary to restore Ontoserver’s filesystem state as well. Practically this may be more performant if there are a large number of historical indexes (typically SNOMED CT versions) stored on the server, or content that the Ontoserver instance is the source of and there are no syndication sources for it to get the content from. However Ontoserver can rebuild most filesystem content from its database content, with the notable exception of SNOMED CT versions. It is also quite unlikely the filesystem will change in an incompatible way with a deployment that requires rollback, database schema changes are much more likely.

Authoring server upgrades

Read/write Authoring servers are typically the source of truth of at least some content. Therefore they should have resilient, persistent storage with restore points to meet business needs. In terms of software upgrade, database backups are key and filesystem backups are prudent prior to installing an update.

Trial installations of upgrades are possible by cloning the Authoring server’s database and filesystem to running a upgrade on a parallel throw away test instance to ensure the process runs smoothly if there are any concerns or unlikely potential outage/rollback times for the Authoring server are critical. This decision depends on required service levels, and potential business impacts.

Read-only Staging and Production upgrades

More flexibility exists with read-only instances as they are not the persistent source of truth for content, and write operations do not need to be accounted for during the upgrade process. This allows for zero down time upgrade deployments if desired, although for the very small outage required to deploy an update this may be considered an unnecessary complication and cost.

The process is very similar to as described in the content release process Content release process, and considerations of whether to use persistent databases and filesystem storage for read-only instances as a deployment duration optimisation are the same.

Simplest approach – short outage

The simplest approach is to follow the General process above

  1. pull the new image
  2. shut down the existing Ontoserver container
  3. boot a new Ontoserver container using the new image

The outage time to stop and start the container is very short, and for most deployments this outage time is completely inconsequential. As this is operationally the simplest thing to do, it is the least costly and likely the best approach.

Zero down time deployment

Similar to the content zero down time deployment approach, a similar approach can be taken for software updates.

The diagram above shows that, behind a load balancer, a new container can be booted using the same feed but a new version of Ontoserver. Once ready for service it can be added to a load balancer at the same time that the existing version is detached from the load balancer for new requests. Once the old requests are drained from the old version of Ontoserver the container can be removed.

This model is possible using independent database and filesystem storage for the Ontoserver containers running different software versions, or they can share a filesystem if that is required or desirable for the particular deployment needs. However two different versions of Ontoserver cannot safely share the same database schema concurrently. If a single persistent database schema is to be used, all containers running the current Ontoserver version connected to the database schema must be shut down before containers running the new version of Ontoserver are started if they are to connect to the same database schema.

Scaled instances

Scaled instances, where multiple Ontoserver read only containers are serving a single endpoint behind a load balancer, have the same considerations as the Zero down time deployment discussed above, however rather than a single container running the current version being replaced by a single container running the new Ontoserver version, there are multiple containers.

The same process applies, new containers are booted using the new Ontoserver version and once ready for service can be added to the load balancer replacing the existing fleet of Ontoserver containers using the older software version.

As mentioned above, the new containers running the new software version cannot share a database with containers running the old software version, however containers of the same software version can share a database if that is convenient for the deployment model. This is discussed more in Content release process.