This section is about upgrading Engine from one minor/maintenance release version to another such version within the same major version (e.g., 2018.1.11.318 to Engine 2018.1.19.535). If you are looking to change major versions of Engine (e.g., 2015.1 to 2018.1), see the Upgrading Engine page of the documentation.
Maintenance releases of Engine are intended to be "drop-in" replacements for earlier versions of Engine in the same major version. Generally, upgrading to a more recent maintenance release is an easy task and shouldn't require much effort on your part (compared to a major version upgrade).
The bulk of the changes that go into minor version releases are fixes for bugs, though we often add smaller new features into minor releases as well. Generally speaking, the following things will not change during maintenance releases:
- The structure of Engine's database
- The interface for existing Engine REST API calls
- The signatures of existing integration methods
- The signatures of existing ScormEngineManager methods
- The interface of legacy web services
- The behavior of existing configuration settings
- Support for versions of a platform that were supported at the beginning of a release cycle. (For example, we stopped supporting MySQL 5.5 in 2016, when Oracle dropped support for it, but releases of Engine 2015.1 released in 2016 and 2017 still worked with MySQL 5.5.)
There are occasionally exceptions to the above, but we generally take care to make changes as non-disruptive as possible. (For example, sometimes we add new tables or columns to Engine's database, but the maintenance release will be written such that it will make sure the tables or columns exist before using them, to ensure compatibility with the original schema.)
While we attempt as far as possible to make maintenance releases as non-disruptive as possible, there is always a risk which switching between versions of a given piece of software. Therefore, we recommend that you deploy the maintenance release in a development or staging environment for minimal testing before you deploy it in production.
When restarting an Engine server, there will be a service interruption while your server is restarting, which will likely cause currently-launched registrations to fail if they happen to send requests while the restart is happening, which means their registration progress could be lost. For this reason, if you are using a single Engine server, it is best to take a few minutes of scheduled downtime (but it doesn't need to be long).
If you use a load balancer, it is much easier to do a true zero-downtime deployment. Most load balancers have a feature such that you can upgrade half of your servers and configure the load balancer to switch to the upgraded half while letting the requests on the other half finish in-progress requests.
How to Upgrade
Deploying a new maintenance release should generally be a simple matter of copying the
entire RusticiEngine and overwriting what you currently have, except for your
RusticiEngineSettings.config file. If you have an integration layer, you will have to make sure
that the assembly containing it gets deployed along with Engine. If you've made any modifications
to Engine's player files, you'll also need to make sure those modifications are merged into the
latest version of the player files. And if you've modified or removed our
web.config, you should
make sure to keep your modified version.
If you are running MySQL, you will also need to deploy the MySQL.Data connector along with Engine
(since licensing concerns prevent us from bundling that dependency with our releases). You must use
the exact version against which Engine's MySQL plugin was compiled or use assembly binding
redirects in your
web.config. We will try to avoid updating the required version of the MySQL plugin
in a maintenance release, but we will sometimes have to in the case of security updates; always
deploy to a staging environment first to make sure everything is working correctly.
Upgrading is generally a matter of deploying the new WAR file. We have found on Tomcat that it is sometimes necessary to remove the old deployed/unzipped RusticiEngine folder before redeploying the WAR file.
If you bundle your
RusticiEngineSettings.properties file or your integration layer inside the WAR
file, you will of course need to add these to the new WAR file before deploying it.