Liferay 5.2.3 on Ubuntu/Debian

en it

Before you continue

This how-to is meant to be used by people that wants to install Liferay on a Debian/Ubuntu system using Tomcat as servlet container and Apache as webserver


I have never been able to find a .deb package for Liferay, so I put together the documentation I could find online and created this guide.

What you need

I will imply that you have installed Apache Tomcat and a JDK using the standard apt-get package

Installing Liferay

The easiest and quicker way I found is that on downloading a "bundle" with tomcat, possibly the same version of Tomcat that is running on your system. The Tomcat version I have is 6, thus you will download from this link on Sourceforge; once you unzip the bundle you have a directory tree like this :

 ├── data
 │   └── hsql
 ├── deploy
 ├── license
 └── tomcat-6.0.18
     ├── bin
     ├── conf
     │   └── Catalina
     │       └── localhost
     ├── jre1.5.0_17
     ├── lib
     │   └── ext
     ├── logs
     ├── temp
     ├── webapps
     │   ├── chat-portlet
     │   ├── google-maps-portlet
     │   ├── mail-portlet
     │   ├── ROOT
     │   ├── sevencogs-hook
     │   ├── sevencogs-theme
     │   ├── tunnel-web
     │   ├── web-form-portlet
     │   └── wol-portlet
     └── work
         └── Catalina
             └── localhost

The simple thing is copy the content of webapps in /usr/share/tomcat6/webapps; I strongly invite you to make a backup copy of the original webapps that comes with Tomcat, so that you can always revert your changes. You can safely skip copying sevencogs-hook and sevencogs-theme since they install the example content of Liferay. Once you are done with the webapps you need to adjust ROOT.xml in /etc/tomcat6/Catalina/localhost so that it looks like this :

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

        <!-- JAAS -->


if you need to disable persistent session across reboots add this before </Context>

 <Manager pathname="" />

Now, make sure that Tomcat has enough resources to run the portal : you have to pass the JVM the parameters -Xms ( configures the initial heap size ) and -Xmx ( configures max heap size ); these are parameters that depend on the machine configuration and the number of deployment you need to accomplish. In my server ( there are seven people working on it ) the values are -Xms1024 -Xmx3072; another parameter to pass to Tomcat is -server : this slows Tomcat's startup but the benefit on the long run are performance and stability . Edit /usr/share/tomcat6/bin/ and add the line

 CATALINA_OPTS="-server -Xms512m -Xmx1024m -XX:MaxPermSize=256m "

just after the comments. This line makes Tomcat run 1. in server mode 2. with 512m RAM of initial heap 3. with 1Gig RAM of maximum heap 4. with 256m RAM reserved for deployment

Parameters 2 and 3 are to be increased if you recieve a java.lang.OutOfMemoryError: Java heap space, parameter 4 is to be increased if you recieve a java.lang.OutOfMemoryError: PermGen space

Now, create a directory ext in /usr/share/tomcat6/lib, assign the ownership to tomcat6 user and copy the content of the directory (/ is the bundle directory) /tomcat-6.0.18/lib/ext : these are the libraries required to run the Portal in Tomcat. Now we need to tell Tomcat to load the jar files from the newly created dir; edit /etc/tomcat6/ and change the line




Configuration parameters

Liferay's configuration parameters are all in a file named that lives in jar in Liferay's lib. The way to override one of these parameters is to write it in a file named This file, in the bundle version of Liferay, is looked up in liferay.home which is the root of the directory that is created when you unzip the bundle. If the file is not found in liferay.home, is looked up in the classpath thus you can safely write your own in /ROOT/WEB-INF/classes.

The first parameter that we need to override is the one for the Liferay's data path : resource.repository.root; personally, I have created a directory /data, set the permission to user tomcat6 and set that parameter to


The second parameter to set is the databse connection. You can do this by setting the following parameters

 jdbc.default.driverClassName=driver class 
 jdbc.default.url=jdbc connection string

If you do not set a database, Liferay runs with HSQL db : nice for developing but simply doesn't suit a production environment. Liferay is compatible with the major database engines both open and closed source ( Oracle included ) so you can use the one you like the most, just remember to copy the jdbc jar file in /usr/share/tomcat6/lib/ext

Another handy parameter is auto.deploy.dir : is a directory that's monitored by Liferay in which one can copy war files and they are automatically patched and deployed within the portal or servlet container; if you kept the directory structure I proposed, a decent value for this parameter is


The complete list of configurable parameters is here

Serving the portal through Apache

If you run the tomcat6 service you will have your portal up and running at the address http://localhost:8080 and all the requests will be handled by Tomcat servlet container. You could change Tomcat's listening port from 8080 to 80 but there's a better solution and it's name is mod_proxy_ajp. First of all, you need to enable the module :

 a2enmod proxy_ajp

Then you need to configure a host so that the requests are "proxied" to Tomcat; we will create a dev-server in the domain. Create a file dev-server in /etc/apache2/sites-available so that it contains :

 #LoadModule proxy_ajp_module modules/
 ErrorLog /var/log/apache2/ajp.error.log
 CustomLog /var/log/apache2/ajp.log combined

         <Proxy *>
                 AddDefaultCharset off
                 Order deny,allow
                 Deny from none
                 #Allow from
         ProxyPass / ajp://localhost:8009/
         ProxyPassReverse / ajp://localhost:8009/

and enable the site by issuing the command

 a2ensite dev-server

then, in your client machine, edit the hosts file ( if using a *nix /etc/hosts ) and add the line

where is the ip address of the machine where you have installed Liferay. Open the browser and go to the address and you shall see your Liferay up and running !