General update considerations

General update considerations#

In preparation of performing an update of nJAMS Server, please read the following notes.

nJAMS Server Update Path#

Updating nJAMS Server is basically straight forward. nJAMS updates are cumulative, which means you can update to the most recent version of nJAMS Server from any prior version. However, there are some preconditions that have to be considered:

  • Updating nJAMS Server from 5.2 to 5.3 is required to be performed by nJAMS installer.

  • Updates should always be performed while keeping the major/minor version sequence. For example, updating from 5.1 to 5.3 while skipping 5.2 is not supported. Instead you have to update from 5.1 to 5.2 first, before you can finally update to 5.3.

  • Updating nJAMS Server should always be considered in context with upgrading Elasticsearch. Do you want to stay with current version of Elasticsearch or do you want to upgrade Elastisearch along with updating nJAMS Server? Certainly, it is also possible to update Elasticsearch without updating nJAMS Server, provided that the supported version constraints are respected.

The following chart shows the natural update path of nJAMS Server:

nJAMS Update path

The diagram shows the natural update path of nJAMS Server including the corresponding Elasticsearch versions.

Natural update path means the approach to regularily update to the next available verson. For example, you started initially with nJAMS Server 4.4, updated to version 5.0, 5.1, and 5.2 in succession, and you are now planning to update to version 5.3.

As long as the version of Elasticsearch you are currently using in your nJAMS instance is supported by the version of nJAMS Server you want to update to, the update process is rather simple. If you are coming from an nJAMS Server version that uses a version of Elasticsearch, which is not supported by the new version of nJAMS Server, you have to consider an upgrade of your Elasticsearch Cluster.

Note

It is not recommended to update nJAMS Server 5.1 directly to 5.3. Please update first to nJAMS Server 5.2 and afterwards update to 5.3.

Upgrade Elasticsearch#

Since nJAMS Server is tightly linked with Elasticsearch, upgrading nJAMS Server must consequently be aligned with upgrading Elasticsearch. Before updating nJAMS Server, you have to make sure you are on the right version of Elasticsearch.

nJAMS Server 5.0 supports Elasticsearch 6, while nJAMS Server 5.1, 5.2, 5.3 also support Elasticsearch 7.

If you are already running nJAMS Server with Elasticsearch 7, everything is fine. This is the best scenario for directly updating to nJAMS Server 5.3.

When you are still using nJAMS Server 5.1 or 5.2 with Elasticsearch 6, you have to upgrade from Elasticsearch 6 to Elasticsearch 7, before you update to nJAMS Server 5.3!

Update WildFly#

nJAMS installer requires a plain HTTP connection to the WildFly in order to be able to update an nJAMS instance automatically. That means the nJAMS installer requires your WildFly to allow HTTP connections. In case you secured your WildFly to use HTTPS/TLS connections, you have to make sure an HTTP connection is allowed for localhost. Since nJAMS installer is executed on the WildFly machine, an HTTP connection for localhost should be no security issue. Temporary availability of HTTP and immediate turn-off when it is no longer needed should always be possible. Follow these instructions to Temporarily enable http for WildFly.

Migrate internal database#

Starting with nJAMS Server 5.2, nJAMS comes with a new version of H2 database (v2). The new format is incompatible with the old format. Therefore, an update of nJAMS Server to version 5.2, 5.3 also requires a conversion from H2 database format v1 to v2.

When you update an existing nJAMS Server instance, the nJAMS installer automatically converts an existing v1 database into the new v2 format.

If you plan to manually update your nJAMS instance, please consider to convert your nJAMS H2 database file. Please refer to chapter How to convert H2 database to v2 format for more details.

However, if you are using an external RDBMS, this step is not required.

Plan maintenance time#

Updating your nJAMS instance may take some time. During that time monitoring data cannot be processed by nJAMS Server and will be accumulated on your JMS server. Keep an eye on the limits of your JMS server and consider that processing the backlog of monitoring data may also take time.

Backup#

It is always recommended to have a current backup of your nJAMS instance before you start the upgrade process. In an emergency, you can easily restore your nJAMS instance.

Note

In general, it is recommended to frequently create backups of the H2 database file njams-v2.mv.db and the keystore file keyfile.bin. You can find both at <njams-install>/data.