Installing Liferay 6.x on Tomcat 6.x bundled with Ubuntu

If you are attempting to install LifeRay on Tomcat 6.x under Ubuntu and are receiving the following as the only error when starting your new context, follow this guide to fix it. Note: this guide assumes and covers using a local MySQL backend database.

SEVERE: Error listenerStart

Installing LifeRay on Tomcat 6.x is usually a relatively straightforward task. Unfortunately, the Tomcat package bundled with Ubuntu does not adhere strictly to the locations of the default Tomcat package documented in the LifeRay installation guide. Further, the Tomcat error logs tend to provide little to no information that will help you to troubleshoot if you did not complete a step properly.

Unpacking Liferay

• Visit the Liferay SourceForge site and download the liferay-portal-6.x.x.war and the liferay-portal-dependencies-6.x.x.zip.
• Unpack the contents of liferay-portal-dependencies-6.x.x.zip. The contents will unpack into a sub-directory, liferay-portal-dependencies-6.x.x:  unzip liferay-portal-dependencies-6.x.x.zip
• Shut down tomcat: /etc/init.d/tomcat6 stop
• Copy the jar files in the liferay-portal-dependencies-6.x.x directory into /var/lib/tomcat6/common: cp liferay-portal-dependencies-6.x.x/* /var/lib/tomcat6/common
• Copy the liferay-portal-6.x.x.war file into your webapps directory, /var/lib/tomcat6/webapps: cp liferay-portal-6.x.x.war /var/lib/tomcat6/webapps

By default, Liferay will unpack into a directory named liferay-portal-6.x.x and the context for Liferay will match. If you wish to use a different context, simply rename the war file. For example, if you wish the context to be /portal, rename the file to portal.war. If you wish to unpack Liferay as the root context, simply rename the file to ROOT.war and delete the contents of /var/lib/tomcat6/webapps/ROOT: rm -rf /var/lib/tomcat6/webapps/ROOT/*; mv /var/lib/tomcat6/webapps/liferay-portal-6.x.x.war /var/lib/tomcat6/webapps/ROOT.war

Configuring MySQL

• If you have yet to install the mysql java plugin, install it now: apt-get install libmysql-java
• Link the MySQL jar file to the Tomcat common directory: ln -s /usr/share/java/mysql-connector-java.jar /var/lib/tomcat6/common/
• Connect to your mysql: mysql -u<username> -p<password>
• Create a new database instance named lportal: create database lportal;
• Create a new user named lportal that can only connect from localhost: grant all on lportal.* to lportal@localhost identified by 'lportal';

Configuring Liferay

• Create a new portal-ext.properties file: vi /var/lib/tomcat6/webapps/ROOT/WEB-INF/classes/portal-ext.properties
• Put the following into the contents of the portal-ext.properties file:

jdbc.default.driverClassName=com.mysql.jdbc.Driver
jdbc.default.url=jdbc:mysql://localhost/lportal?useUnicode=true&characterEncoding=UTF-8&useFastDateParsing=false
jdbc.default.username=lportal
jdbc.default.password=lportal
liferay.home=/var/lib/tomcat6

• Create the data directory: mkdir /var/lib/tomcat6/data; chown tomcat6:tomcat6 /var/lib/tomcat6/data
• Create the deploy directory: mkdir /var/lib/tomcat6/deploy; chown tomcat6:tomcat6 /var/lib/tomcat6/deploy

Installing Geronimo Packages
You will likely need a few more java dependencies setup before you can start Tomcat.

• Install geronima-jta: apt-get install libgeronimo-jta-1.0.1b-spec-java
• Link the JTA file to the Tomcat common directory: ln -s /usr/share/java/geronimo-jta-1.0.1b-spec.jar /var/lib/tomcat6/common/
• Install geronima-javamail: apt-get install libgeronimo-javamail-1.4-spec-java
• Link the Javamail file to the Tomcat common directory: ln -s /usr/share/java/geronimo-javamail-1.4-spec.jar /var/lib/tomcat6/common/

Starting up Tomcat with Liferay

• When you are ready, start Tomcat: /etc/init.d/tomcat6 start
• Tail the Tomcat log file to check for errors: tail -f /var/log/tomcat6/catalina.out

The first launch will likely take quite a bit of time as Liferay will create its initial database. Once the database has been created, you should see the following which is generally a good indication that Liferay is working:

00:05:44,777 INFO  [PluginPackageUtil:1109] Reloading repositories
00:05:45,980 INFO  [HotDeployUtil:69] Initializing hot deploy manager 1866282093
00:05:46,162 INFO  [AutoDeployDir:105] Auto deploy scanner started for /var/lib/tomcat6/deploy

Additional Tips

• If you receive, "java.lang.OutOfMemoryError: PermGen space" add, "-XX:MaxPermSize=256m" to JAVA_OPTS in /etc/default/tomcat6.
• If you receive, "java.lang.OutOfMemoryError: Java heap space" add, "-Xmx256M" to JAVA_OPTS in /etc/default/tomcat6. I saw a significant performance increase when this was set to 512.
• If you have other applications deployed, ensure that they do not have their own copies of mysql or other jars in their WEB-INF/lib directory.
• If you choose to install Liferay in a context other than ROOT, define that context as portal.ctx in the portal-ext.properties file.

Leave a comment and let me know if this worked for you.