Installing Liferay on Tomcat 7

Installing Liferay on Tomcat 7

Liferay Home is one folder above Tomcat’s install location.

For this section, we will refer to your Tomcat server’s installation location as $TOMCAT_HOME. If you do not already have an existing Tomcat server, we recommend you download a Liferay/Tomcat bundle from http://www.liferay.com/downloads/liferay-portal/available-releases. If you have an existing Tomcat server or would like to install Liferay on Tomcat manually, please follow the steps below.

Before you begin, make sure you have downloaded the latest Liferay .war file and Liferay Portal dependencies from http://www.liferay.com/downloads/liferay-portal/additional-files. The Liferay .war file should be called liferay-portal-6.1.x-<date>.war and the dependencies file should be called liferay-portal-dependencies-6.1.x-<date>.zip.

Next, let’s get started by addressing Liferay’s library dependencies.

Dependency Jars

Liferay Portal needs to have the Liferay Portal Dependency JARs, an appropriate JDBC driver and a few other JARs installed.

Create folder $TOMCAT_HOME/lib/ext.

Extract the Liferay dependencies file to $TOMCAT_HOME/lib/ext. If the files do not extract to this directory, you can copy the dependencies archive to this directory, extract them and then delete the archive.

Next, you need several .jar files which are included as part of the Liferay source distribution. Many application servers ship with these already on the class path but Tomcat does not. The best way to get the appropriate versions of these files is to download the Liferay source code and get them from there. Once you have downloaded the Liferay source, unzip the source into a temporary folder. We’ll refer to the location of the Liferay source as $LIFERAY_SOURCE.

Copy the following jars from $LIFERAY_SOURCE/lib/development to your $TOMCAT_HOME/lib/ext folder:

activation.jar

jms.jar

jta.jar

jutf7.jar

mail.jar

persistence.jar

Copy the following jar from $LIFERAY_SOURCE/lib/portal to your $TOMCAT_HOME/lib/ext folder:

ccpp.jar

Note: Tomcat 6 users should not copy the ccpp.jar file into their $TOMCAT_HOME/lib/ext folder and should delete it from this folder if it already exists.

Copy the following jars from $LIFERAY_SOURCE/lib/development to your $TOMCAT_HOME/temp/liferay/com/liferay/portal/deploy/dependencies folder:

resin.jar

script-10.jar

Make sure the JDBC driver for your database is accessible by Tomcat. Obtain the JDBC driver for your version of the database server. In the case of MySQL, use mysql-connector-java-{$version}-bin.jar. You can download the latest MySQL JDBC driver from http://www.mysql.com/products/connector/. Extract the JAR file and copy it to $TOMCAT_HOME/lib/ext.

Liferay requires an additional .jar on Tomcat installations to manage transactions. This is included in the bundle but you need to add it if you’re installing Liferay manually. You may find this .jar here: http://www.oracle.com/technetwork/java/javaee/jta/index.html. Place this file in Tomcat’s lib/ext folder.

Now that you have the necessary libraries in place, we’ll move on to configuring your domain.

Tomcat Configuration

The steps in this section focus on:

Setting environment variables

Creating a context for your web application

Modifying the list of classes/JARs to be loaded

Specifying URI encoding

Let’s get started with our configuration tasks.

Create a setenv.bat (Windows) or setenv.sh file (Unix, Linux, Mac OS) in the $TOMCAT_HOME/bin directory. When you start Tomcat, Catalina calls setenv.bat or setenv.sh. Edit the file and populate it with following contents:

setenv.bat:

if exist "%CATALINA_HOME%/jre@java.version@/win" (

if not "%JAVA_HOME%" == "" (

set JAVA_HOME=

)

set "JRE_HOME=%CATALINA_HOME%/jre@java.version@/win"

)

set "JAVA_OPTS=%JAVA_OPTS% -Dfile.encoding=UTF8 -Djava.net.preferIPv4Stack=true -Dorg.apache.catalina.loader.WebappClassLoader.ENABLE_CLEAR_REFERENCES=false -Duser.timezone=GMT -Xmx1024m -XX:MaxPermSize=256m"

setenv.sh:

JAVA_OPTS="$JAVA_OPTS -Dfile.encoding=UTF8 -Dorg.apache.catalina.loader.WebappClassLoader.ENABLE_CLEAR_REFERENCES=false -Duser.timezone=GMT -Xmx1024m -XX:MaxPermSize=256m"

This sets the character encoding to UTF-8, sets the time zone to Greenwich Mean Time and allocates memory to the Java virtual machine.

Create the directory $TOMCAT_HOME/conf/Catalina/localhost and create a ROOT.xml file in it. Edit this file and populate it with the following contents to set up a portal web application:

<Context path="" crossContext="true">

<!-- JAAS -->

<!--<Realm

className="org.apache.catalina.realm.JAASRealm"

appName="PortalRealm"

userClassNames="com.liferay.portal.kernel.security.jaas.PortalPrincipal"

roleClassNames="com.liferay.portal.kernel.security.jaas.PortalRole"

/>-->

<!--

Uncomment the following to disable persistent sessions across reboots.

-->

<!--<Manager pathname="" />-->

<!--

Uncomment the following to not use sessions. See the property

"session.disabled" in portal.properties.

-->

<!--<Manager className="com.liferay.support.tomcat.session.SessionLessManagerBase" />-->

</Context>

Setting crossContext="true" allows multiple web apps to use the same class loader. In the content above you will also find commented instructions and tags for configuring a JAAS realm, disabling persistent sessions and disabling sessions in general.

Open $TOMCAT_HOME/conf/catalina.properties and replace the line:

common.loader=${catalina.base}/lib,${catalina.base}/lib/*.jar,${catalina.home}/lib,${catalina.home}/lib/*.jar

with:

common.loader=${catalina.base}/lib,${catalina.base}/lib/*.jar,${catalina.home}/lib,${catalina.home}/lib/*.jar,${catalina.home}/lib/ext,${catalina.home}/lib/ext/*.jar

...