Recommendations for upgrading production environments

December 16, 2022

This page contains general recommendations and best practices concerning upgrading jExperience and/or jCustomer environments.

Downgrade is not supported

jExperience and jCustomer do not support downgrade procedures, updating versions should always be performed towards a version of a higher digit.

Review upgrade instructions and release notes

Each release of jExperience and jCustomer includes upgrade instructions that contain details specific to that precise upgrade situation.

When planning for an upgrade, please make sure to:

  • Review upgrade instructions on the Academy specific to the version you're planning to upgrade to
  • Read through all release notes (or changelog notes) published between the version you're currently running in production and the version you're planning to upgrade to.
  • For jCustomer upgrades, there might be link to release notes for Apache Unomi. Since jCustomer is based upon Apache Unomi, make sure to review these as well.
  • Plan your upgrade accordingly, some upgrades will be transparent while others will involve service disruption.

Limit service interruption

Multiple Jahia instances can be connected to the same jCustomer instance in parallel, you can reduce the possible downtime associated with the upgrade of a module by using a blue/green deployment scenario for jExperience.

For example, for the upgrade from jExperience 2.2.2 to jExperience 2.5.0 (using jCustomer 1.7.1), the following procedure could be followed:

  1. Create a clone of your Jahia/jExperience production environment. We will call this cloned environment "blue", while your current production environment will be called "green". Both "blue" and "green" will be connected to the same jCustomer instance
  2. Redirect all traffic towards "blue"
  3. Upgrade "green" to jExperience 2.5.0, at that time "green" is not serving any traffic. Verify everything is working properly
  4. Redirect all traffic towards "green", your upgrade is now complete
  5. Upgrade "blue" to jExperience 2.5.0, this will maintain version parity between the two environments although "blue" will not be receiving any traffic.

Service availability during upgrades

jExperience and jCustomer will behave differently during their upgrades, in particular, if there is a large amount of data to be migrated.

Upgrading jCustomer will generate service interruption of that jCustomer instance as it requires a service to be restarted and potentially data to be migrated. But jExperience is equipped with fallback mechanisms to handle such service interruption of its jCustomer instance(s).

On the contrary, although upgrading jExperience is unlikely to generate service interruption, if the jExperience service is stopped (or unable to start) for any reason, pages with personalizations or AB Tests will not render properly.

These characteristics can be used to better plan your migration, understand associated risks and define your rollback procedure, in particular if your objective is to upgrade both jExperience and jCustomer.