Chapter 9. How to upgrade Platform

Purpose
Modifications details between versions
Modifications between Platform v.3.0.1 and 3.0.2
Modifications between Platform v.3.0.2 to 3.0.3
Modifications between Platform v.3.0.3 and 3.0.4
Steps to upgrade
Development mode
Production mode

Updating your Platform server is fairly easy but remains critical. This document present the detailed steps to upgrade Platform server.

ECMS Application templates

It is about some Groovy template files (.gtmpl) stored in the JCR. These templates are used by the Content List Portlet and Category Navigation Portlet to diplay content lists in a pagination mode. There are four template types available, including:

  • Content List templates.

  • Parameterized Content List templates.

  • Category Navigation templates.

  • Paginator templates.

In Platform 3.0.1, those templates are stored in the same location in the JCR. But in Platform 3.0.3, their locations are separated to be clearer for the end user.

See the Templates Structure Upgrade Notice in the document located in DeliveryFolder/upgrade-notes/PLF302CLVTemplatesStructureUpgradeNotice.pdf.

Gadgets

Gadgets predefined in Platform are stored in the JCR, so if you have already used Platform in the production mode, delete those gadgets to get the new ones defined in the new Platform package. However, in case of the development mode, meaning that JCR database could be removed, those gadgets are auto-refreshed when upgrading server.

  1. Modified gadgets:

  2. Deleted gadgets:

  3. Added gadgets:

See the instructions below to refresh those gadgets in production mode.

In this mode, you are supposed to use Platform with a clean database, which mean you can delete the database tables without impacting your development. Also, try following steps in the section Production mode below.

  1. Stop the Platform server.

  2. Clean up your JCR database tables (Drop JCR Datasource tables).

  3. Backup your files before proceeding to the upgrade.

  4. Replace the old eXo Platform binaries with the new ones:

    1. Tomcat: make sure that the new Tomcat content is used.

    2. JBoss: replace the old EAR package with the new ones, including the gatein.ear folder.

  5. Apply modifications defined in DeliveryFolder/upgrade-notes/PLF302CLVTemplatesStructureUpgradeNotice.pdf in your custom configuration files.

  6. Plug your custom configuration files and your custom datasources configuration into the new server.

  7. Start the Platform Server to complete the upgrade.

In this mode, you are supposed to keep your existing JCR data. Follow these steps:

  1. Stop the Platform server.

  2. Backup your Database and files before proceeding to the upgrade.

  3. Replace the old eXo Platform binaries with the new ones.

  4. Plug your custom configuration files and your custom datasources configuration into the new server.

  5. Deploy crash web application is not deployed.

  6. Start the new Platform Server.

  7. Connect to Platform CRaSH console by using the Telnet or SSH console to update gadgets predefined in Platform: 

       telnet localhost 5000
   connect -c portal -u root -p gtn portal-system
   rm /production/app:gadgets/app:eventslist
   rm /production/mop:workspace/mop:customizations/mop:Todo
   rm /production/app:gadgets/app:Todo
   select * from mop:workspaceclone where mop:contentid='Todo' | set mop:contentid "To-do"
   rm /production/mop:workspace/mop:customizations/mop:RSSFetch
   rm /production/app:gadgets/app:RSSFetch
   select * from mop:workspaceclone where mop:contentid='RSSFetch' | set mop:contentid "SocialRssReader"
   rm /production/app:gadgets/app:IDE
   rm /production/app:gadgets/app:pollslist
   rm /production/app:gadgets/app:Activities
   rm /production/app:gadgets/app:ViewerFriends
   rm /production/app:gadgets/app:taskslist
   commit

  8. Restart the Platform Server to complete the upgrade.

  9. The modifications defined in DeliveryFolder/upgrade-notes/PLF302CLVTemplatesStructureUpgradeNotice.pdf are automatically applied (See the section Can you safely upgrade?):

Assuming you use a Platform 3.0.1 version, you can safely upgrade with no impact on your existing website. All impacted data will be migrated automatically at startup.