Liferay is a Gartner Magic Quadrant Leader for the Sixth Year! Find out why
« Back to Upgrade Instructions

Upgrade Instructions from 5.1 to 5.2

This upgrade is recommended to anyone running Liferay Portal 5.1SE and wants to benefit from the New Features in Liferay Portal v5.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. You should at least use v5.2.2 (there is no need to update to 5.2.0 or 5.2.1 first!)

Prerequisite #

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

Basic Installation Outline #

This instructions should be enough if you haven't made any customizations to the out-of-the-box release. Otherwise you will also have to follow the steps in the next sections.

  1. Make sure you've got your last complete backup at hand - not just the database backup: e.g. you most likely would like to have your portal-ext.properties available to restore the applicable settings later (The settings most likely will have to be changed, but still: you want to know your customizations to redo them later)
  2. Undeploy the old version of Liferay, and then shut down your application server. For Tomcat, you'd delete the ROOT folder from <Tomcat Home>/webapps.
  3. Copy the new versions of the dependency .jars to a location on your server's classpath, overwriting the ones you already have for the old version of Liferay. For Tomcat, these are stored in <Tomcat Home>/common/lib/ext.
  4. Deploy the new Liferay .war file. This is different by application server. For Tomcat, you'd create a ROOT folder in <Tomcat Home>/webapps and unzip the .war file there.
  5. Delete your tomcat class cache ie <Tomcat Home>/work/Catalina/localhost/ as sometimes tomcat will load class' from the previous version of Liferay instead of the new version
  6. Start (or restart) your application server. Liferay should come up.

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 (other documentations suggest catalina.sh/catalina.bat or catalina.conf, depending on the exact version you are using. setenv.sh or setenv.bat is not delivered with tomcat but - if existing - it will be embedded in the startup process, so it's a nice way to separate your own settings from tomcats 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.properties to unify the configuration through all application servers.

It's still possible to use application server specific datasources and pools if desired by using certain configuration properties.

Check Database Configuration for further details on how to adapt your existing configuration.

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 (Note: Remove the square brackets surrounding the dtd link as this code outline is formatted wrong):
<!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 (Note: Remove the square brackets surrounding the dtd link as this code outline is formatted wrong):
<!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_normal.vm", delete the following lines :
$theme.include($session_timeout_include)
$theme.include($sound_alerts_include)

(If you let them 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 the /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 ServiceContext Pattern. The Service Context is an object that contains context information about a given API call. All of the fields of 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, an struts action or any other frontend 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 could be rewritten as follows:

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

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

Please see this forum thread for more discussion on the topic.

0 Attachments
54406 Views
Average (0 Votes)
The average rating is 0.0 stars out of 5.
Comments
Threaded Replies Author Date
Hi! I'm upgrading a LR5.1.2 theme to 5.2.2, but... Juan Fernández June 16, 2009 8:12 AM
I have found these lines in portal_normal.vm. I... Juan Fernández June 16, 2009 8:35 AM
I removed $theme.include($bottom_ext_include)... Milan Jaroš June 23, 2009 3:54 AM
Hi. What about to add smtp configuration... Milan Jaroš October 13, 2009 7:55 AM
Very good text but...As usual: smallest detail... Behemoth . February 4, 2010 5:08 AM
What are the configuration changes need to be... ArunaSudha K February 5, 2013 9:27 AM

Hi!
I'm upgrading a LR5.1.2 theme to 5.2.2, but I don't have a file called portal.vm...does it matter? Where can I find it?
Thanks!
Posted on 6/16/09 8:12 AM.
I have found these lines in portal_normal.vm. I suppose it's the same, isn't it?
Posted on 6/16/09 8:35 AM in reply to Juan Fernández.
I removed $theme.include($bottom_ext_include) and I changed portal.vm to portal_normal.vm because it seem that it is correct.
Posted on 6/23/09 3:54 AM.
Hi. What about to add smtp configuration changes? http://www.liferay.com/web/guest/community/wiki/-/wiki/Main/Configuring+gmail+sm­tp+server+with+Liferay
Posted on 10/13/09 7:55 AM.
Very good text but...As usual: smallest detail is reason for biggest delay. Here is directory tree changing. Below my own (from my experience) step-by-step procedure.

Upgrade LR from v.5.1.2 to v.5.2.3
Here:
- LRold – root point for LR v.5.1.2
- LRnew – root point for LR v.5.2.3
- used: Tomcat 6.0, HSQLDB, Linux
- own (changed) files:
LRold/conf/server.xml
LRold/webapps/ROOT/WEB-INF/classes/portal-ext.properties

1.Stop server.

2.Create tree:
LRnew
LRnew/data/sql
LRnew/tomcat

3. Copy
- LRold/* -> LRnew/tomcat

4. Delete
- LRnew/logs/*
- LRnew/temp/*
- LRnew/wepapps/ROOT/*
- LRnew/work/*
- LRnew/conf/*.bat

5. Unzip
- liferay-portal-dependencies-5.2.3.zip -> LRnew/tomcat/lib/ext/*.*
(overwrite existing files)
- liferay-portal-5.2.3.war -> LRnew/tomcat/wepapps/ROOT/*

6. RESET
- copy portal-ext.properties -> LRnew/tomcat/webapps/ROOT/WEB-INF/classes

7.Upgrade DB
- move LRnew/tomcat/bin/lportal.* -> LRnew/data/hsql

8.Start server, SignIn
- ControlPanel->ServerAdministration->Reindex all search index

9. Reset themes, portlets, layouts:
- external items - by update manager
- internal items – by new SDK
(Comment: not all used items updated at the same moment as Liferay. Better to save used items at the own comp and re-compile whet it needs)

10. Test
-entry as Admin:
check existed sites, users, organization, roles, articles...
Posted on 2/4/10 5:08 AM.
What are the configuration changes need to be followed when upgrading tomcat with liferay.
Posted on 2/5/13 9:27 AM.