Recommendations for upgrading production environments

November 14, 2023

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.

Unlock jExperience upgrade

Upgrading between major versions of jExperience can significantly impact availability if the upgrade is not performed jointly with a jCustomer upgrade, for example if you're upgrading from jExperience 2.7.2 to jExperience 3x while the jCustomer instance has not been upgraded to jCustomer 2x.

Starting with jExperience 2.8.0 and to prevent incorrect manipulations in Jahia Module Manager UI (for example clicking on jExperience upgrade by mistake), Jahia implemented a mechanism to lock jExperience upgrade to the same first-digit versions. This means that if you're running jExperience 2.8.0, you will be able to upgrade to jExperience 2.x.y but not to jExperience 3.x.y.

If you're preparing the upgrade to the next major version of jExperience (change of first digit), one of the first activities will consist in removing that protection.

This operation does not impact jExperience operation and can be performed anytime before triggering the upgrade of jExperience.

Via the GraphQL API

You can remove the upgrade lock by executing the following GraphQL query.


mutation {
  admin {
    jahia {
      configuration(
        pid: "org.jahia.modules.modulemanager.configuration.constraints", identifier: "jexperience"
      ) {
      	remove(name: "moduleLifeCycleConstraints")
      }
    }
  }
}

Via the filesystem

You can remove the upgrade lock by removing the following file:  digital-data/karaf/etc/org.jahia.modules.modulemanager.configuration.constraints-jexperience.yaml

The restriction will be automatically added again, just after the new version of jExperience has started.

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.