Performing a rolling upgrade of your platform

November 14, 2023

Platform upgrade is a key aspect of a platform high availability. While it is essential to ensure that a platform stays up-to-date at all time (for a number of reasons ranging from security, to performance improvements and getting the latest fancy features released in each version), platform upgrade can also mean service downtime. 

Warning: Do not share the generated-resources folder across nodes if you perform rolling upgrades. If the folder is shared, resources may be generated on nodes with the older version of Jahia while the nodes on the new version are started.

The rolling upgrade presented here allows to use the existing servers and update them one at a time while serving HTTP traffic with the remaining computation power. Click on the following image to watch an animation.


rolling.gif

Prerequisites

The procedure works with the following Jahia target versions:

  • 7.3.0.0 and later
  • 7.2.3.2 and later

Performing a rolling upgrade

Consider the following environment: a cluster of 3 nodes in the version X behind a load balancer (represented by the 

nginx.PNG
 logo). The steps show how to migrate the environment to the version X+1 without service disruption.

We advise that you perform this procedure during a period of low activity and traffic as the upgrade requires to use the full read-only mode and the ability to remove a node from the load balancer at any time during the upgrade procedure.

Here is the environment is in its initial state:

upgrade-1.png

To perform a rolling upgrade

  1. Turn all nodes of the cluster in full read-only mode. The procedure is described here.
  2. Create a backup of your environment.
  3. Create a copy of the database, in what we’ll call “DB Schema B”
    Your environment is now in the following state:
    upgrade-4.png
  4. Remove the processing node from the load balancer so it does not serve any requests.
    upgrade-5.png
  5. Stop the processing node.
  6. Point the processing node to the copied database “DB Schema B”:
    upgrade-7.png
  7. Migrate the processing node.
  8. Before restarting the node, create a marker file (empty file) named "rolling-upgrade" in the <digital-factory-data> folder. This will prevent any conflict with the other nodes. The description of this marker is available here.
  9. Restart the node. Note that the node will not be in full read-only mode anymore.
    upgrade-10.png
  10. Traffic can be redirected to this node:
    upgrade-11.png
  11. Repeat the steps 5 to 12 for the other, non processing, nodes (remove from load balancer, stop, point to migrated database, migrate the node, create backup-restore file and restart):
    upgrade-final.png

Your environment is now migrated to the newer version.