Upgrading the clustering bundle of Jahia

Question

In some very specific situations, the Jahia Support team might request that the clustering bundle be upgraded in your environment.

Typically, new releases of the clustering bundle are made available via releases of Jahia, this procedure makes it possible to upgrade the clustering bundle independently.

This procedure requires access to the enterprise-customers-releases Nexus repository, you will need to reach-out to Jahia Support team to obtain credentials to this repository.

Solution

Upgrading the clustering bundle must be thoroughly tested and will not be possible between all versions:

Make sure to test the combination of versions (source and target) you're planning to update before applying the procedure to live environments.
Make sure to have a tested rollback procedure before proceeding.
It is strongly encouraged to perform this operation starting with a "healthy" system (Server Availability Manager in a "GREEN" state, ...)
Do NOT perform module operations (install/update/refresh/...) while executing the procedure
Do NOT modify the config on any nodes while executing the procedure (other than modifications listed in the procedure itself).
Do NOT refresh wiring when performing uninstall or install commands. The "-r" is used to NOT perform a refresh.
Make sure to follow this procedure PRECISELY.

Step1: Add the Enterprise Customers maven repository

The clustering bundle is made available in Jahia Enterprise Customers nexus repository, if you do not yet have an access to this repository, contact our support team.

Add the following maven repositories to the file org.ops4j.pax.url.mvn.cfg by adding those two values to the list in the property org.ops4j.pax.url.mvn.repositories

org.ops4j.pax.url.mvn.repositories = {REDACTED}, \
  https://{USERNAME}:{PASSWORD}@devtools.jahia.com/nexus/content/repositories/jahia-enterprise-customers-releases@id=jahia-enterprise-customers, \
  https://{USERNAME}:{PASSWORD}@devtools.jahia.com/nexus/content/repositories/thirdparty-releases@id=jahia-thirdparty

The {USERNAME}:{PASSWORD} credentials must be replaced with credentials with read access to the listed repositories and {REDACTED} corresponds to repositories that might already exist in your configuration file. You should verify {USERNAME}:{PASSWORD} credentials are correct by connecting to nexus using a browser and trying to access these repositories/groups. Do not proceed until you confirmed proper access to these repositories.

Step2: Identify the version of the existing clustering feature

In Step 3, you will need to specify the version of dx-clustering to remove, and that version will be dependent upon your environment.

You can identify that version using the following command:

cluster:bundle-list -s default | grep clustering

Command output:

308 │ Active    │     │ local         │ in/out  │ 8.1.0.9               │ org.jahia.bundles.clustering

Look for the version of org.jahia.bundles.clustering bundle, which is "8.1.0.9" is the command output above.

For reference, Jahia releases shipped with the following versions of dx-clustering by default:

dx-clustering-8.2.1 (for Jahia 8.2.0.6)
dx-clustering-8.2.0.0 (for Jahia 8.2.0.5)
dx-clustering-8.1.0.11(for Jahia 8.1.8.1)
dx-clustering-8.1.0.9 (for Jahia 8.1.7.0)
dx-clustering-8.1.0.8 (for Jahia 8.1.6.0)
dx-clustering-8.1.0.7 (for Jahia 8.1.5.0)
dx-clustering-8.1.0.4 (for Jahia 8.1.3.0)

Additionally, dx-clustering-8.1.1 is available for Jahia 8.1.5.0 and above but is not, at the time of writing the page, bundled with a Jahia version.

Step3: Uninstall and remove the existing clustering feature

Starting with the processing node, uninstall and remove the clustering bundle on all nodes of the cluster.

feature:uninstall -r -v dx-clustering
feature:repo-remove dx-clustering-{VERSION}

Replace {VERSION} with the version of the clustering bundle currently running on the node (see step 2)

About the feature:uninstall and feature:install options:

-r: do not refresh wiring
-v: enable verbose mode (logs to be printed in catalina.out)

Step4: Install the new cluster feature

Starting with the processing node, install the new feature on all nodes of the cluster.

feature:repo-add mvn:org.jahia.bundles/dx-clustering/{VERSION}/xml/features
feature:install -r -v dx-clustering

Replace {VERSION} with the desired version of the clustering feature (for example: 8.1.0.9)

Step5: Perform a rolling restart

Once dx-clustering has been updated on all nodes, perform a rolling restart of the Jahia cluster. This rolling restart is necessary to ensure all of the cluster bundles and their wiring are in the correct status.

Step6: Check the status of all bundles

You can run the following command on all nodes to ensure the new version was properly installed and started.

cluster:bundle-list -s default

The cluster bundles (308, 309 and 310) in the list below should display as "Active":

Bundles in cluster group default
 ID │ State     │ Lvl │ Located       │ Blocked │ Version               │ Symbolic Name
────┼───────────┼─────┼───────────────┼─────────┼───────────────────────┼───────────────────────────────────────────────────────────────
  0 │ Active    │     │ local         │ in/out  │ 5.6.12                │ org.apache.felix.framework
...
308 │ Active    │     │ local         │ in/out  │ 8.1.0.9               │ org.jahia.bundles.clustering
309 │ Active    │     │ local         │ in/out  │ 8.1.0.9               │ org.jahia.bundles.clustering.tools
310 │ Active    │     │ local         │ in/out  │ 8.1.0.9               │ org.jahia.bundles.hazelcast.discovery

If any of the three Clustering bundles listed above are not "Active" (for example in a "Resolved" state), these bundles should be started.

A bundle can be started with the following command:

bundle:start org.jahia.bundles.clustering

(Optional) Rolling back to a previous version

Rollback to previous versions of the clustering bundle is possible by following the same procedure.

In a similar fashion, do not attempt a rollback of the clustering bundle until you have received instructions to do so or if you identified a clear need for such a rollback.