In eXo Platform 4, the upgrade to the latest 4.x.y version is guaranteed and tested from previous version's latest maintenance release to current version's latest release . For example to upgrade from 4.2.0 version to 4.3.1, it is highly recommended to move from 4.2.0 then to 4.2.1 then to 4.3.0 and finally move to 4.3.1 version. In case you want to skip a version and in order to ensure a correct upgrade, it would be better to take a look and to carefully read the related section for each upgrade :
Upgrade to a new eXo Platform version
For Tomcat and JBoss packages
Stop the old version of eXo Platform.
Apply your customizations into the new version.
If you have changed the configuration properties via $PLATFORM_TOMCAT_HOME/gatein/conf/exo.properties (Tomcat) or $PLATFORM_JBOSS_HOME/standalone/configuration/gatein/exo.properties (JBoss), you can update them to the same file in the new eXo Platform version.
Disable-user Feature
Activating the Disable-user Feature requires to migrate the entire user base. Since this operation may be long, the feature has been made optional and you can upgrade without being forced to migrate.
If you don't want the disable-user feature (so you don't need to upgrade your user database when using PicketlinkIDM), you can add this to exo.properties configuration file :
exo.disable.user.activated=false
. The feature will be hidden from eXo Platform, and the disable-user upgrade plugin is also ignored.
If your eXo Platform is connected to an active directory and if you want to ignore the DisableUserUpgradePlugin ,
you should in addition of disabling it in exo.properties, add this below configuration in idm-configuration.xml
<field name="filterDisabledUsersInQueries">
<boolean>true</boolean>
</field>
<field name="disableUserActived">
<boolean>${exo.disable.user.activated:true}</boolean>
</field>
Password encryption
From eXo Platform 4.3.0 version, we used SHA-256 by default for encrypting password.
Default Encoder class: org.picketlink.idm.impl.credential.DatabaseReadingSaltEncoder Default Hash algorithm: SHA-256
So for accounts prior to eXo Platform 4.2.1, the two following properties in exo.properties must be used.
exo.plidm.password.class=org.picketlink.idm.impl.credential.HashingEncoder exo.plidm.password.hash=MD5
If an Active Directory is used, it's important to verify that the MD5 credentialEncoder.hashAlgorithm is used in the picketlink-idm-msad-readonly-config.xml file.
<!-- XML : generated by JHighlight v1.0 (http://jhighlight.dev.java.net) --> <span class="xml_plain"></span><br /> <span class="xml_plain"> </span><span class="xml_tag_symbols"><</span><span class="xml_tag_name">option</span><span class="xml_tag_symbols">></span><span class="xml_plain"></span><br /> <span class="xml_plain"> </span><span class="xml_tag_symbols"><</span><span class="xml_tag_name">name</span><span class="xml_tag_symbols">></span><span class="xml_plain">credentialEncoder.hashAlgorithm</span><span class="xml_tag_symbols"></</span><span class="xml_tag_name">name</span><span class="xml_tag_symbols">></span><span class="xml_plain"></span><br /> <span class="xml_plain"> </span><span class="xml_tag_symbols"><</span><span class="xml_tag_name">value</span><span class="xml_tag_symbols">></span><span class="xml_plain">MD5</span><span class="xml_tag_symbols"></</span><span class="xml_tag_name">value</span><span class="xml_tag_symbols">></span><span class="xml_plain"></span><br /> <span class="xml_plain"> </span><span class="xml_tag_symbols"></</span><span class="xml_tag_name">option</span><span class="xml_tag_symbols">></span><span class="xml_plain"></span><br />
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.
As of eXo Platform 4.1, SMTP and JODConverter configuration has been included in the exo.properties file. See the corresponding sections in Configuration chapter.
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.
Go to the new eXo Platform package ($PLATFORM_TOMCAT_HOME/gatein/conf/ or $PLATFORM_JBOSS_HOME/standalone/configuration/gatein/),
then rename the sample upgrade file regarding the version you want to upgrade (known as upgrade-ABC-to-XYZ-sample.properties) into upgrade.properties as described in
Release Notes file.(You should check the Release Notes file of your eXo Platform version.)
You can also find the Release Notes file under the eXo Platform package with RELEASE-NOTES.txt naming.
Start the eXo Platform server. The upgrade will run automatically. You will notice an info in the log file which indicates that the upgrade is started, for example :
INFO | New version has been detected: proceed upgrading from 4.3.0 to 4.3.1.
For each upgrade plugin, we will notice in the log a message which indicates that the upgrade is started then another message which indicates that is successfully upgraded, for example :
INFO | Proceed upgrade plugin: name = Upgrade-Gadgets from version 4.3.0 to 4.3.1 with execution order = 0
INFO | gadget MemoryCharts upgraded successfully.
When the upgrade is completed successfully, we will notice the message below in the log :
INFO | Version upgrade completed.
the startup is successful when you see a message like :
INFO | Server startup in XXXX ms.
Stop the server.
Remove or rename the upgrade.properties in Step 6 in order to avoid running the upgrade again.
Restart the server, then do some tests on the upgraded version. See Best practices for more details.
In this section, we will illustrate the upgrade process for a cluster with two nodes as an example.
Copy the $CURRENT_INSTALLATION_DIR_NODE_1/apps/exoplatform/gatein/data folder to a known location.
Copy the $CURRENT_INSTALLATION_DIR_NODE_2/apps/exoplatform/gatein/data folder to a known location.
It's sufficient to upgrade only the master node by following the same steps indicated in the previous section.
Copy the $CURRENT_INSTALLATION_DIR_NODE_1/apps/exoplatform/gatein/data in the new master node.
launch the upgrade for the master node, ensure that the process is run successfully as indicated in the previous section.
Copy the $CURRENT_INSTALLATION_DIR_NODE_2/apps/exoplatform/gatein/data in the new node2.
Restart all nodes.
For the Native Installer (Bitnami)
Stop the Tomcat server of the current installation and back up its data.
Copy the $CURRENT_INSTALLATION_DIR/apps/exoplatform/gatein/data folder to a known location.
Back up the data from the Postgresql database (notice that the Postgresql server must be running, see this guide). To do this:
-p database_port is optional if you use the default port (5432) for the Postgresql server.
When prompted for password of the postgres user, enter the password of the root user set during the installation.
Stop the Postgresql server if you want to use the same port for the new installation.
Download the new installation, and install it.
Stop the Tomcat server of the new installation.
Go to $NEW_INSTALLATION_DIR/apps/exoplatform/gatein/conf/, then rename the sample upgrade file regarding the installation you want to upgrade into upgrade.properties, then copy the content of the upgrade.properties file link of each “From version” listed in the previous section.
Replace the $NEW_INSTALLATION_DIR/apps/exoplatform/gatein/data folder with the folder copied in step 2.
Restore the database from the current installation to the new one (notice that the Postgresql server must be running, see this guide). To do this:
Copy the backup.sql file generated in step 3 from $CURRENT_INSTALLATION_DIR/postgresql/bin to $NEW_INSTALLATION_DIR/postgresql/bin.
Go to the $NEW_INSTALLATION_DIR/postgresql/bin folder.
Run the command psql.exe -U postgres -p database_port and enter the password of the user postgres. In the Postgres shell, do as follows:
Drop the database bitnami_exoplatform with the command drop database bitnami_exoplatform;.
Recreate the database bitnami_exoplatform with the command create database bitnami_exoplatform;.
Run the command psql -U postgres -p database_port bitnami_exoplatform < backup.sql.
Start the Tomcat server. The upgrade will run automatically.
Stop the Tomcat server.
Remove or rename the upgrade.properties file under the $NEW_INSTALLATION_DIR/apps/exoplatform/gatein/conf folder.
Restart the Tomcat server. Now, go to the next section to do some tests on the upgraded version.
Read and understand these information
For the native installer (Bitnami), take care about these information.
The available memory allocated by default for the JVM Heap is defined to 1G in the file $BITNAMI_HOME\apps\exoplatform\scripts\setenv.bat (setenv.sh for Linux installers).
To modify this value, you just have to uncomment the following parameter in the file $BITNAMI_HOME\apps\exoplatform\scripts\setenv-customize.bat(setenv-customize.sh for Linux installers):
# Maximum Heap Size to use (Default : 3g) EXO_JVM_SIZE_MAX="4g"
Then restart your Tomcat server.
PS : For Windows installers and in order to change any memory- or environment-related variable for Tomcat, a service re-install is necessary to take the modification into account. For that, you have to execute the following commands after modifying the parameter and before restarting the Tomcat server:
Access to the folder of installation (cd "C:\Bitnami\eXo Platform Enterprise")
Enter the command : serviceinstall.bat REMOVE
Finally, put this command : serviceinstall.bat INSTALL