Upgrading Liferay

Liferay upgrades are fairly straightforward. A consistent set of steps is all you need to follow to upgrade a standard Liferay installation. Things do get more complicated if your organization has used the extension environment to customize Liferay, as it will need to be converted to an Ext Plugin for Liferay 6, and it is possible that API changes in the new version will break your existing code. This, however, is usually pretty easy for your developers to fix. Portlet plugins are generally backwards compatible, as they are written to the Java standard. This includes Portlet 1.0 (JSR-168) portlets, as the Portlet 2.0 (JSR-286) standard has also been designed to be backwards-compatible. Theme plugins may require some modifications in order to take advantage of new features. Much effort has been made to make upgrades as painless as possible; however, this is not a guarantee that everything will work without modification. Extension environment code is the most complicating factor in an upgrade, so it is important to test as much as possible.

As a general rule, you can upgrade from one major release to the next major release. For example, you can upgrade directly from Liferay 5.1.x to 5.2.x, but not from 5.1.x to 6.0.x. If you need to upgrade over several major releases, you will need to run the upgrade procedure for each major release until you reach the release you want. This doesn't mean you need to run the procedure for every point release (i.e., 4.3.5 to 4.3.6 to 4.4.0 to 4.4.1, etc.); you only need to run the procedure for the major releases. A good practice is to use the latest version of each major release to upgrade your system.

Liferay Upgrade Procedure

Liferay can auto-detect whether the database requires an upgrade the first time the new version is started. When Liferay does this, it will automatically upgrade the database to the format required by the new version. In order to do this, Liferay must be accessing the database with an ID that can create, drop, and modify tables. Make sure that you have granted these permissions to the ID before you attempt to upgrade Liferay. It is also a good idea to backup your database before attempting an upgrade in case something goes wrong during the process.

Tip: Liferay versions prior to 4.3.0 require that you manually run SQL scripts on your database to perform an upgrade. If you need to upgrade from Liferay 4.1.x to 4.2.x in preparation for an upgrade to a current version of Liferay, you can find these SQL scripts in the source code archive for the version of Liferay you are running. They will be in the SQL folder of the archive.

Upgrade Steps

It takes only five steps to upgrade a standard Liferay installation to Liferay 6:

• Copy your customized portal-ext.properties file to a safe place, and then undeploy the old version of Liferay and shut down your application server.

• Copy the new versions of the dependency .jars to a location on your server's class path, overwriting the ones you already have for the old version of Liferay.

• Deploy the new Liferay .war file to your application server. Follow the deployment instructions in Chapter 2 .

• Modify your portal-ext.properties file and set permissions.user.check.algorithm=5.

• Start (or restart) your application server. Watch the console as Liferay starts: it should upgrade the database automatically. Verify that your portal is operating normally, and then run the upgrade procedure to upgrade to permissions algorithm 6 (see below) and restart.

That's all there is to it. Everything else is handled by Liferay's upgrade procedure. Note that as stated above, if you have to upgrade over several Liferay versions, you will need to repeat these steps for each major release. You can now deploy your own plugins to the system.

Once your upgrade is complete, you may wish to review the portal.properties changes for this version of Liferay to see whether the new defaults (see below) are appropriate for your implementation.

What follows are instructions for upgrading for specific versions.

Upgrading From Liferay 5.1 to Liferay 5.2

Always use the latest version of 5.2 available as it will have fixed all the potential upgrade issues that may have been found.

Prerequisite

It's recommended to upgrade first at least to 5.1.2SE if you are running any previous version.

Changes in configuration properties

How to keep the old values

The default values of some properties has been changed. In order to keep the previous values you have to run Liferay passing the following system property:

java ... -Dexternal-properties=portal-legacy-5.1.properties

Each application server has different methods to add this system property. In Tomcat modify setenv.sh/setenv.bat and append that option to the environment variable JAVA_OPTS. The scripts setenv.sh or setenv.bat are not delivered with Tomcat but if they exist, Tomcat will use them in the startup process, so it's a nice way to separate your own settings from tomcat's default shell scripts.

Here are the complete contents of that file (portal-legacy-5.1.properties) for reference:

resource.repositories.root=${user.home}/liferay

theme.portlet.sharing.default=true

organizations.country.required[regular]=true
organizations.assignment.auto=true
organizations.assignment.strict=false
organizations.membership.strict=true

lucene.dir=${resource.repositories.root}/lucene/

jcr.jackrabbit.repository.root=${resource.repositories.root}/jackrabbit

dl.hook.impl=com.liferay.documentlibrary.util.JCRHook

dl.hook.file.system.root.dir=${resource.repositories.root}/document_library

Important changes in the configuration of Database access and mail integration

One very important aspect of the upgrade is that now the configuration of the database parameters and those for mail integration are handled through the portal-ext.properties file to unify the configuration through all application servers.

It's still possible to use application server specific data sources and pools if desired by using certain configuration properties. This is documented in Chapter 2.

Theme Upgrade

Instructions for maintaining customized themes built in 5.1 without redeploying with the new SDK :

• Change the header of /WEB-INF/liferay-plugin-package.xml to:

<!DOCTYPE plugin-package PUBLIC "-//Liferay//DTD Plugin Package 5.2.0//EN" "http://www.liferay.com/dtd/liferay-plugin-package_5_2_0.dtd">

• Change the header of /WEB-INF/liferay-look-and-feel.xml to:

<!DOCTYPE look-and-feel PUBLIC "-//Liferay//DTD Look and Feel 5.2.0//EN" "[http://www.liferay.com/dtd/liferay-look-and-feel_5_2_0.dtd">]

• Upgrade compatibility version in liferay-look-and-feel.xml:

<compatibility>
        <version>5.2.2+</version>
</compatibility>

• In portal.vm, delete the following lines :

$theme.include($bottom_ext_include)
$theme.include($session_timeout_include)
$theme.include($sound_alerts_include)

If you don't remove these, you will see a blank page and an exception.

• In order to display the control panel in the dock, add the following lines in dock.vm:

#if ($show_control_panel)
<li class="control-panel">
<a href="$control_panel_url">$control_panel_text</a>
</li>
#end

• In navigation.css:

.lfr-dock li.control-panel a {
        background-image: url(../images/dock/control_panel.png);
}

• Then copy /images/dock/control_panel.png from the classic theme (ROOT/html/themes/classic) into your theme.

• In WEB-INF/web.xml, change the deprecated declaration com.liferay.portal.servlet.filters.compression.CompressionFilter into com.liferay.portal.servlet.filters.gzip.GZipFilter.

API Changes

Usage of ServiceContext in Liferay's Services Layer

The most significant API change in 5.2 is that most APIs of the service layer have been adapted to use the Service Context Pattern. The Service Context is an object that contains context information about a given API call. All of the fields in this object are optional, although the services that store any type of content will require you to specify at least the scopeGroupId. Here is a simple example of how to create a ServiceContext instance and pass it to a service API:

  ServiceContext serviceContext = new ServiceContext();
  serviceContext.setScopeGroupId(myGroupId);

  BlogsEntryServiceUtil.addEntry(...., serviceContext);

If you are invoking the service from a servlet, a Struts action, or any other front end class which has access to the portletRequest, you can use a utility method that will create the ServiceContext object and fill it with all the necessary values automatically. In that case the above example should be rewritten as follows:

ServiceContext serviceContext = ServiceContextFactory.getInstance(BlogsEntry.class.getName(), portletRequest);

BlogsEntryServiceUtil.addEntry(...., serviceContext);

Upgrading From Liferay 5.2 to Liferay 6.0

Always use the latest version of 6.0 available as it will have fixed all the potential upgrade issues that may have been found.

Prerequisite

It's recommended to upgrade first at least to 5.2.3 CE if you are running any previous version.

Upgrading Your Permissions Algorithm

Liferay 6.0 introduces permissions algorithm 6. Algorithm 6 is an enhancement to our permissions system which drastically improves performance by reducing the number of queries necessary to determine permissions for any individual asset within Liferay portal.

Liferay 6 by default is configured to use algorithm 6. This is appropriate for new installations, but requires additional configuration for upgrades, because the table structure for this algorithm is different from the structures for the previous algorithms. For this reason, before you start Liferay 6 for the first time and run the upgrade process, you need to tell Liferay 6 to use Algorithm 5, and then run a separate conversion utility later, after you have verified that the upgrade was successful. To temporarily switch your Liferay 6 installation to algorithm 5, add the following entry to your portal-ext.properties:

permissions.user.check.algorithm=5

This will tell Liferay that you are still using algorithm 5. Next, start Liferay and allow it to upgrade your database. Once the upgrade has completed, verify that everything is working properly. You can now leave the algorithm setting as is, or if you want to take advantage of the performance of the new algorithm, you can upgrade to algorithm 6 by going through a few simple steps in the Control Panel.

To upgrade to Algorithm 6, log in as an Administrator and navigate to the Control Panel. Go to Server Administration and select Data Migration from the menu along the top of the screen. You should see a section entitled Legacy Permissions Migration at the bottom of the page.

Illustration 116: Dialog to update your permissions algorithm to the latest version.Algorithms 5 and 6 do not support adding permissions at the user level. If you have permissions set to individual users, the converter can simulate this for you by auto-generating roles with those permissions, and assigning those roles to the users who have individualized permissions. If you have a lot of these, you'll likely want to go through and clean them up after the conversion process. To generate these roles, check the Generate Custom Roles box. If you do not generate the roles, all custom permissions set for individual users will be discarded.

Click Execute to convert all existing users and roles to algorithm 6.

Upgrading EXT to EXT Plugins

With Liferay 6.0, the Ext environment no longer exists in its previous form. Instead, Ext is now a plugin. If you are using the Ext Environment to change core code, you will find that Ext Plugins handle core customizations better than the Ext Environment did, so developers can spend less time with deployments and maintaining changes than they did previously. There is now only one SDK needed for Liferay development, which also simplifies things for the developer.

Before using any code previously developed in Ext, you will need to migrate your Ext environments to Ext plugins. If you are on a version of Liferay prior to 5.2, you will also need to upgrade your existing Ext environment to Liferay 5.2 before attempting to convert it to a plugin. The upgrade process will not work on earlier versions of Liferay's Ext environment.

In the Plugins SDK, under the ext directory you can find the build.xml file to convert your existing Ext Environment to a plugin. The script creates the shell of an Ext plugin with the ext.zip file included with the Plugins SDK and merges your existing Ext Environment into the new plugin.

To run the script, use the following command:

ant upgrade-ext -Dext.dir=[path to existing Ext] -Dext.name=[new plugin name] -Dext.display.name="[friendly name for new plugin]"

This will create a directory with the name you specified, with the merged changes from your Ext Environment and the default .zip file. Both build-service (Service Builder) and build-db (DB Builder) have been ported to Ext Plugins to allow developers to regenerate their services and SQL code in Ext Plugins. However, Service Builder in Ext plugins will be deprecated in future versions, and custom services should be migrated to portlet plugins. Try to migrate your custom services to portlet plugins as soon as possible as this is the recommended practice.