eXo Platform aims at providing a transparent upgrade experience so that the upgrade to a newer version is seamless for an administrator.
As eXo Platform makes changes between versions, it is sometimes required to run some routines that will alter data. For that purpose, eXo Platform provides a service dedicated to it, called the Upgrade Service. This generic framework can detect a version change and identify which upgrade routines to be executed.
Since the framework leverages the eXo plugins mechanism, eXo Platform refers to these routines as upgrade plugins. At startup, eXo Platform will load and execute the upgrade plugins identified by the Upgrade Service.
This chapter outlines requirements before the upgrade and helps you get familiar with the upgrade process between versions of eXo Platform via the following topics:
- Breaking Changes Breaking changes you should be aware about before starting the upgrade to 5.2 version.
- Prerequisites A list of things you need to do before the upgrade.
- Upgrade process How to upgrade from eXo Platform 5.1 to eXo Platform 5.2.
- Best practices Some tips that help you monitor the upgrade.
- Upgrading add-ons Common steps for upgrading your add-ons along with the new Platform version.
In this section, we will present all the breaking changes you should know before starting the upgrade to 5.2 version.
JBoss EAP upgrade
JBoss EAP 7.1 version is used in eXo Platform 5.1.
This version comes with a bunch of improvements, including the use of the new security framework WildFly Elytron and the support of HTTP/2. More information on this new version are available at https://www.redhat.com/en/blog/red-hat-releases-jboss-eap-71.
You can find here, a full documentation about the upgrade to JBoss EAP 7.1.
Some Groovy templates have been changed in eXo Platform 5.2, check out the complete list. If your custom extension overrides some Groovy templates, you must check if it has been changed, and update it if it is the case.
This is the list of templates changed in eXo Platform 5.2.
Before the upgrade, you need to:
- Back up data, as described in Backup and Restore, before upgrading. In case anything turns badly, your data is safe and you can start over.
- Back up customizations (including configuration, deployed extensions and applications) that you plan to reuse in the new version.
- Download eXo Platform 5.2 version.
- Perform one or more dry-run upgrade(s) to find out potential problems and estimate the upgrade time.
- Rename all caches.
The configuration properties names for caches have been changed for eXo Platform 5.1 in order to use the same names in standalone and cluster modes. In case you changed default cache configuration, take care to update the cache properties names as documented at this documentation.
The dry-run upgrade allows you to:
- Detect and handle issues to make sure they will not happen during the real upgrade.
- Estimate how long the upgrade will take in your production environment.
- Find out if you need to adjust anything to make your upgrade faster and more efficient.
JBoss EAP was upgraded to 7.1 version to benefit from its last updates and improvements. You can check changelogs for JBOSS.
When you upgrade to eXo Platform, notice that default password encryption algorithm has changed so you need to reconfigure it back to the one that you used before, otherwise old users will not be able to log in. See details in Password Encryption.
The upgrade procedure is only guaranteed and tested to be transparent from the previous maintenance version (x.y.z from x.y.z-1). So, we recommend to apply upgrade procedures for all versions between your current one and the target one. In this case it is from the latest maitenance version of 5.1 to 5.2. If you are on 5.1.1 version, you should move into the 5.1.2 and then move to 5.2 version. However, if you still insist on skipping versions, we strongly advise to read all upgrade notes of the versions you are skipping to see if your project is impacted by any previous upgrade procedure.
Upgrade to a new eXo Platform version
For Tomcat and JBoss packages
- Stop the old version of eXo Platform, in this case the 5.1 version.
- Apply your customizations into eXo Platform 5.2.
- If you have changed the configuration properties via
$PLATFORM_JBOSS_HOME/standalone/configuration/gatein/exo.properties(JBoss), you can update them to the same file in the new eXo Platform version.
- If you use a populated organizational data source (such as LDAP), activate the Organization Integration Service so that the data is synchronized. See Synchronization for more details.
- If you have changed the configuration properties via
- Configure the JCR and IDM databases. Refer to Database for more details.
- Configure the EXO_DATA_DIR variable. Refer to Data directory configuration for more details.
- Start the eXo Platform server. The upgrade will be run automatically. The startup is successful when you see a message like INFO | Server startup in XXXX ms.
Here are good ways you can follow during and after upgrading:
Monitor the server console/log file to be aware of the upgrade status or any issues during the upgrade. By default, eXo Platform records all information in
A successful upgrade typically logs the followings:
The first important message like:
| INFO | Start transparent upgrade framework [o.e.c.upgrade.UpgradeProductService<Catalina-startStop-1>]
The list of activated plugins:
| INFO | Proceed upgrade the plugin (async = true): name = PushNotificationSettingsUpgradePlugin from version 5.0.3 to 5.1.0 [o.e.c.upgrade.UpgradeProductService<Catalina-startStop-1>]
| INFO | Proceed upgrade the plugin (async = false): name = NodeTypeTemplateUpgradePlugin from version 5.0.3 to 5.1.0 [o.e.c.upgrade.UpgradeProductService<Catalina-startStop-1>]
| INFO | Proceed upgrade the plugin (async = false): name = MetadataTemplateUpgradePlugin from version 5.0.3 to 5.1.0 [o.e.c.upgrade.UpgradeProductService<Catalina-startStop-1>]
| INFO | Proceed upgrade the plugin (async = false): name = QueryUpgradePlugin from version 5.0.3 to 5.1.0 [o.e.c.upgrade.UpgradeProductService<Catalina-startStop-1>]
| INFO | Proceed upgrade the plugin (async = false): name = ScriptUpgradePlugin from version 5.0.3 to 5.1.0 [o.e.c.upgrade.UpgradeProductService<Catalina-startStop-1>]
| INFO | Proceed upgrade the plugin (async = false): name = WCMTemplateUpgradePlugin from version 5.0.3 to 5.1.0 [o.e.c.upgrade.UpgradeProductService<Catalina-startStop-1>]
| INFO | Proceed upgrade the plugin (async = false): name = UpgradeSecureJCRFoldersPlugin from version 5.0.3 to 5.1.0 [o.e.c.upgrade.UpgradeProductService<Catalina-startStop-1>]
The message informing that the upgrade plugin execution is completed for each executed plugin:
| INFO | Upgrade of plugin PushNotificationSettingsUpgradePlugin completed. [o.e.c.upgrade.UpgradeProductService<pool-6-thread-1>]
| INFO | Upgrade of plugin NodeTypeTemplateUpgradePlugin completed. [o.e.c.upgrade.UpgradeProductService<Catalina-startStop-1>]
A message informing the successful startup:
| INFO | Server startup in 102839 ms [org.apache.catalina.startup.Catalina<main>]
Check the PRODUCT version via the REST service (http://[your_server]:[your_port]/rest/platform/info), for example: “platformVersion”:”5.1.0”.
Or, you can see the new version in the footer of Login page as follows:
Log in and check some functions, components and customizations to see if they are working correctly.
After upgrading Platform, you have to re-install your add-ons and re-configure them.
Check the version.
The old add-on version might be compatible with the new Platform version, or not, so it is recommended you always install newer compatible version if any.
Before installing an add-on, you can use
describe command to check
its versions. The command usage is documented
You can also find the compatibility information at this page.
Check the configuration.
If the add-on version does not change, typically you just need to copy the old configuration. Otherwise you are recommended to check Add-ons Guide for configuration changes.
Check if any extra upgrade step required.