By Robert Hall
When using a portal platform/app server such as Liferay, major version upgrades are a periodic fact of life. Having a set of standard steps to follow in migrating from one version to another is essential in easing the process and making it repeatable across environments--never do an upgrade in a production environment first, and never do an upgrade without sufficient backups of your current Liferay install folder, database, and document library. This post will cover repeatable steps to upgrading a Liferay EE installation from 6.1 to 6.2. For this example, you will need a valid Liferay customer account with access to the Customer Portal to download Liferay and related artifacts. In this example, we have an existing installation with Liferay 6.1 EE GA3 and we are migrating to Liferay 6.2 EE SP4 (the latest version available as of this writing).
This example assumes MySQL is the Liferay target database. Other databases would have a similar process.
- Back up the existing database.
mysqldump -h dbhost -u dbuser -pdbuserpw dbname > dbdbackup.sql
where 'dbhost', 'dbuser', 'dbuserpw', and 'dbname' are the values for the environment of the database that the Liferay 6.1 EE instance being upgraded uses.
- Create a new MySQL database.
Using the MySQL command shell, create a new MySQL database for use by Liferay 6.2.
./mysql -u root -p
Create the blank database:
mysql> Show Databases;
mysql> create database dbname62 default character set utf8;
mysql> grant all on dbname62.* to dbuser@'localhost' identified by 'dbuserpw';
mysql> grant all on dbname62.* to dbuser@'%' identified by 'dbuserpw';
mysql> flush privileges;
- Import the backup copy into the new database.
mysql -h dbhost -u dbuser -pdbuserpw dbname62 < dbdbackup.sql
- Liferay zip file--- From the Liferay Customer Portal, download the latest 6.2 zip with your preferred servlet container (in this example, it is Tomcat and the file name is liferay-portal-tomcat-6.2-ee-sp4-20140509104816263.zip). Copy the zip file to your folder (such as /opt on a Linux or Mac OSX environment) and unzip it. It's recommended to keep the Liferay instance in the folder it was zipped up in when unzipped in the target folder. In the /opt folder of this installation we have multiple versions of Liferay installed:
drwxr-xr-x 8 ec2-user ec2-user 4096 Feb 26 19:56 liferay-portal-6.1.20-ee-ga2
drwxr-xr-x 8 root root 4096 Apr 11 14:57 liferay-portal-6.1.30-ee-ga3
drwxr-xr-x 8 root root 4096 Apr 14 16:32 liferay-portal-6.2-ee-sp3
drwxr-xr-x 8 root root 4096 May 10 08:43 liferay-portal-6.2-ee-sp4
When coupled with multiple databases and multiple document libraries, having multiple versions of Liferay installed in parallel is very useful for testing without wiping out the previous installation.
- portal-ext.properties--- Copy the existing portal-ext.properties from your 6.1 installation to the 6.2 install folder and configure the database properties to point to the new database that was created.
- portal-legacy-6.1.properties--- Some properties are considered 'legacy' to 6.1 and need to be specified in a separate, specially named portal-ext.properties file. For example, in this installation:
For more examples of this, the first reference below at Liferay discusses legacy properties.
- License--- a valid Liferay 6.2 EE license of the appropriate type (developer, non-production production, or production) must be purchased from Liferay and installed on this server prior to startup. Per the instructions with the license, it would be installed in the deploy folder prior to startup:
Simply copy the document library folder and its content from the data folder of the 6.1 EE instance to the new 6.2 EE instance. In this example, that would be:
sudo cp -rf /opt/liferay-portal-6.1.30-ee-ga3/data/document_library /opt/liferay-portal-6.2-ee-sp4/data
After creating the database, setting up the document library, installing and configuring Liferay with a license, start the instance.
Liferay will recognize the newer version of the Liferay instance and correctly migrate the document library and database during the startup. The process will take several minutes. The amount of time depends on how large the database and document library are. During startup, watch the liferay log file:
tail -f /opt/liferay-portal-6.2-ee-sp4/logs/liferay.*.log
You should see update messages in the log file, of this sort immediately after startup:
17:31:17,704 INFO [localhost-startStop-1][UpgradeProcess:175] Upgrading com.liferay.portal.upgrade.UpgradeProcess_6_2_0
17:31:17,706 INFO [localhost-startStop-1][UpgradeProcess:175] Upgrading com.liferay.portal.upgrade.v6_2_0.UpgradeSchema
17:32:01,775 INFO [localhost-startStop-1][UpgradeProcess:175] Upgrading com.liferay.portal.upgrade.v6_2_0.UpgradeAnnouncements
17:32:01,787 INFO [localhost-startStop-1][UpgradeProcess:175] Upgrading com.liferay.portal.upgrade.v6_2_0.UpgradeAssetPublisher
17:32:04,043 INFO [localhost-startStop-1][UpgradeProcess:175] Upgrading com.liferay.portal.upgrade.v6_2_0.UpgradeBlogs
17:32:04,192 INFO [localhost-startStop-1][UpgradeProcess:175] Upgrading com.liferay.portal.upgrade.v6_2_0.UpgradeBlogsAggregator
17:32:04,225 INFO [localhost-startStop-1][UpgradeProcess:175] Upgrading com.liferay.portal.upgrade.v6_2_0.UpgradeCalendar
17:32:04,379 INFO [localhost-startStop-1][UpgradeProcess:175] Upgrading com.liferay.portal.upgrade.v6_2_0.UpgradeCompany
17:32:04,712 INFO [localhost-startStop-1][UpgradeProcess:175] Upgrading com.liferay.portal.upgrade.v6_2_0.UpgradeCustomizablePortlets
17:32:04,757 INFO [localhost-startStop-1][UpgradeProcess:175] Upgrading com.liferay.portal.upgrade.v6_2_0.UpgradeDocumentLibrary
Eventually the logs will show it recognizing the new license and startup will be complete.
Portlets, Hooks, Themes and Layouts
For 3rd party portlets installed from the Liferay Marketplace, the appropriate versions for Liferay 6.2 EE will have to be installed. If you have any custom developed portlets, hooks, themes or layouts, these will need to be recompiled with the 6.2 Liferay libraries and make some configuration property changes. For developing with Maven, download from the Liferay Customer Portal the Liferay Maven Dependencies package (liferay-portal-maven-6.2-ee-sp3-20140407093552703.zip at the time of this posting) and install to your Maven repository as specified in the included instructions (specified in a readme.txt file provided in the zip file).
Change the portlet pom.xml Liferay version setting to the version number of the Liferay libraries that were installed in the Maven repository.
If you have a custom theme for Liferay, it may have a property file called 'liferay-look-and-feel.xml'. It may have a 'compatability' parameter that will need to be updated to 6.2 as follows:
After making these changes, recompile your custom portlets, hooks, themes and layouts and deploy to the 6.2 Liferay instance.
Things to watch for include changes in Liferay APIs. If your plugins, hooks, etc use Liferay APIs, the updated libraries may have API changes that cause build errors and require refactoring of your code.
By following the process described in this post, upgrades of Liferay can be made in a repeatable manner in dev, integration, qa and production environments, hopefully without too much drama. Though the focus here was on Liferay EE, the process would be essentially the same with Liferay CE, except without the need for access to the Customer Portal for downloads or the need for Liferay-issued licenses.