Performing a rolling upgrade of your platform

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 times (for a number of reasons ranging from security, performance improvements, and getting the latest fancy features released in each version), platform upgrade can also mean service downtime.

The rolling upgrade presented here allows you 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.

Handling generated-resources during rolling upgrade

The generated-resources folder contains temporary files that are created as needed. The names and contents of the generated files depend on the versions of the installed modules, meaning different files may be present after a migration.

To minimize issues related to generated resources during migration, it is recommended not to share the generated-resources folder across nodes. If the folder is shared, resources might be generated by nodes still running the older version of Jahia, even as other nodes are upgraded. Additionally, if load balancing is in use, sticky sessions should be enabled to ensure each node consistently accesses the correct version of the generated content.

Finally, to avoid 404 errors related to missing generated resources during the migration, it is recommended to purge the contents of the generated-resources folder only at the end of the rolling upgrade procedure. Jahia will automatically regenerate the necessary data as traffic is processed.

Performing a rolling upgrade

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

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

We advise that you perform a rolling upgrade during a period of low activity and traffic as the upgrade requires 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.

To perform a rolling upgrade:

1. Turn all nodes of the cluster in full read-only mode. See Full read-only mode.
2. Create a backup of your environment.
3. Create a copy of the database, which is DB Schema B in the example. The environment is now in the following state:
   

   

4. Remove the processing node from the load balancer so it does not serve any requests.
   

   

5. Stop the processing node.
6. Point the processing node to the copied DB Schema B database.
   

   

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 conflicts with the other nodes. For a description of this marker, see the FAQs.
9. Restart the node. Note that the node will not be in full read-only mode anymore.  
   

   

10. Traffic can be redirected to this node.
    

    

11. Repeat the steps 5 to 10 for the other non-processing nodes (remove from load balancer, stop, point to migrated database, migrate the node, create backup-restore file and restart).
    

    

Your environment is now migrated to the newer version.