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 Ext plugins to customize Liferay. It's 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 which use Liferay APIs should be reviewed and their services rebuilt against the new release. Theme plugins may require some modifications in order to take advantage of new features, and if they're using Liferay APIs, they should be reviewed. Much effort has been made to make upgrades as painless as possible; however, this is not a guarantee that everything will work without modification. Ext plugins are 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.2.x to 6.0.x, but not from 5.2.x to 6.1.x. If you need to upgrade over several major releases, you'll 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 or service pack; 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.
Now that we've gotten the general philosophy of upgrading out of the way, let's outline the procedure you'll undergo for upgrading a Liferay 6.0 installation to a 6.1 installation. If you're running a previous version of Liferay and need to upgrade to 6.0 first, please see the instructions in the previous version of this document.
Upgrading Liferay Portal 6.0 to Liferay Portal 6.1
There are a few things you'll want to prepare before you actually perform the upgrade. Specifically, you'll need to review your image gallery usage, review new Liferay 6.1 defaults, and catalog all the plugins you have installed. After you've performed these three tasks, you'll be ready to upgrade.
Liferay 6.1 introduces a major change to how Liferay handles files. No longer do we have a separate Document Library and Image Gallery; instead, these have been combined into Documents and Media. If you were using Liferay's Image Gallery to store images, these can be migrated over during an upgrade, but you'll have to take some extra steps first.
In Liferay 6.0, you had three ways you could store images in the Image Gallery. You could use the
DatabaseHook
and store them as BLOBs in the database; you could use the
DLHook
to store them in the Document Library, or you could use the
FileSystemHook
to store them in a folder on your server's file system. Before you upgrade, you'll need to set whichever property you were using in your 6.0
portal-ext.properties
file, because by default, none of them are enabled in 6.1. Setting one of the properties triggers the migration during the upgrade process. Below are the three properties; you'll need to set only
one
of them (the one you were using).
image.hook.impl=com.liferay.portal.image.DatabaseHook image.hook.impl=com.liferay.portal.image.DLHook
image.hook.impl=com.liferay.portal.image.FileSystemHook
The next thing you'll need to look at are the defaults that have changed from 6.0 to 6.1. These are preserved in
portal-legacy-6.0.properties
in the source. The 6.0 values are:
users.last.name.required=true layout.types=portlet,panel,embedded,article,url,link_to_layout editor.wysiwyg.portal-web.
docroot.html.portlet.message_boards.edit_message.bb_code.jsp=bbcode
setup.wizard.enabled=false discussion.subscribe.by.default=false message.boards.subscribe.by.default=false
The 6.1 values have changed to:
users.last.name.required=false layout.types=portlet,panel,embedded,url,link_to_layout editor.wysiwyg.portal-web.
docroot.html.portlet.message_boards.edit_message.bb_code.jsp=ckeditor_bbcode
setup.wizard.enabled=true discussion.subscribe.by.default=true message.boards.subscribe.by.default=true
If you don't like the defaults, you can change them back in one shot by adding a system property to your JVM's startup. This differs by application servers. In Tomcat, you'd modify
setenv.sh
/
setenv.bat
and append the option
-Dexternal-properties=portal-legacy-6.0.properties
to the environment variable JAVA_OPTS. The scripts
setenv.sh
or
setenv.bat
are not delivered with default Tomcat, but do exist in the bundles. If they're there, Tomcat uses them in the startup process, so it's a nice way to separate your own settings from Tomcat's default shell scripts. Alternatively, of course, you can override some or all of them in your
portal-ext.properties
along with your other overrides.
Finally, you need to take note of any plugins you have installed. Liferay's plugins are usually version-specific, so you'll need to obtain new versions of them for the new release of Liferay. If you have custom plugins created by your development team, they'll need to build, test, and optionally modify them to work with the new release of Liferay. Don't attempt an upgrade without collecting all the plugins you'll need first.
Once you've reviewed your properties and collected all the plugins you'll need, you're ready to follow the upgrade procedure. Remember to back up your system before you begin.
There are two different procedures to upgrade Liferay. The first one, upgrading a Liferay bundle, is the most common. The second procedure is for upgrading a Liferay installation on an application server. We'll go over both.
In both cases, Liferay auto-detects whether the database requires an upgrade the first time the new version is started. When Liferay does this, it upgrades the database to the format required by the new version. In order to perform this task, 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. And, of course, we'll run the risk of overly repeating ourselves: back up your database.
Let's look at upgrading a bundle, which is the easiest upgrade path.
Upgrading a bundle
If you're running a Liferay bundle, the best way to do the upgrade is to follow the steps below. The new Liferay is installed in a newer version of your bundle runtime. For example, the Liferay/Tomcat bundle for 6.0 used Tomcat 6 by default; the 6.1 bundle uses Tomcat 7. Though there is a Tomcat 6 bundle of Liferay 6.1, that bundle also uses a newer release of Tomcat than the one from 6.0. This is the case for all runtimes that Liferay supports. We generally recommend that you use the latest version of your runtime bundle, as it will be supported the longest.
- Obtain the new bundle. Unzip the bundle to an appropriate location on your system.
-
Copy your
portal-ext.properties
file and your
data
folder to the new bundle.
-
Review your
portal-ext.properties
file as described above. If you were using the Image Gallery, make the necessary modifications so that your files are migrated to Documents and Media. Review the new defaults and decide whether you want to use them. Review any other modifications you've made.
- Start your application server. Watch the console as Liferay starts: it should upgrade the database automatically.
-
When the upgrade completes, install any plugins you were using in your old version of Liferay. Make sure you use the versions of those plugins that are designed for Liferay 6.1. If you have your own plugins, your development team will need to migrate the code in these ahead of time and provide .war files to you.
- Browse around in your new installation and verify that everything is working. Have your QA team test everything. If all looks good, you can delete the old application server with the old release of Liferay in it from the bundle directory. You have a backup of it anyway, right?
As you can see, upgrading a bundle is generally pretty simple. But not everybody can use bundles: sometimes, specific application servers or application server versions are mandated by the environment you're in or by management. For this reason, Liferay also ships as an installable .war file that can be used on any supported application server.
Upgrading using a .war file
Running a manual upgrade is almost as easy as upgrading a bundle:
-
- Obtain the Liferay Portal .war file and the dependency .jars archive.
-
Copy your customized
portal-ext.properties
file to a safe place and review it as described above, making all the appropriate changes.
- Undeploy the old version of Liferay and shut down your application server.
- Copy the new versions of Liferay's dependency .jars to a location on your server's class path, overwriting the ones you already have for the old version of Liferay. This location is documented for your application server in chapter 11.
- Deploy the new Liferay .war file to your application server. Follow the deployment instructions in chapter 11.
- Start (or, if your app server has a console from which you've installed the .war, 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 install any plugins you were using in your old version of Liferay. Make sure you use the versions of theose plugins that are designed for Liferay 6.1. If you have your own plugins, your development team will need to migrate the code in these ahead of time and provide .war files to you.
- Browse around in your new installation and verify that everything is working. Have your QA team test everything. If all looks good, you're finished.
That's all there is to it. Most everything 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.
.
One of the often overlooked features of
![More actions available through the dockbars. For instance the action \](http://portal.krypthonas.de/wp-content/gallery/liferay-61-ca/Bildschirmfoto%202012-01-07%20um%2021.26.11.png "More actions available through the dockbars. For instance the action \")
Liferay
follows a Model Driven Architecture approach. In the traditional sense
it requires a Platform Independent Model (PIM) from which we derive and
Platform Specific Model (PSM) and subsequently generate implementation
logic. In Liferay however, we begin with a Domain Specific Model(DSM)
since the root model is only specific to Liferay domain and it defines
all the nouns of the system with their interactions and is translated to
a Platform Specific Model(PSM) which constitutes the EJB’s, Spring
Framework, Hibernate Layer, Web Services and then generates the
implementation classes by extending the appropriate services. This is
made possible due to the implementation of Service Builder which is the
most integral tool provided by Liferay and enforces the same standards
throughout. The services builder is the Model Driven Transformation
(MDT) Tool in this context.
Posts
