Liferay 5.2.3 on Ubuntu/Debian
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
Why
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 -->
<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"
/>
</Context>
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/catalina.sh 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/catalina.properties and change the line
common.loader=${catalina.base}/lib,${catalina.base}/lib/*.jar,${catalina.home}/lib,${catalina.home}/lib/*.jar,/var/lib/tomcat6/common/classes,/var/lib/tomcat6/common/*.jar,
in
common.loader=${catalina.base}/lib,${catalina.base}/lib/*.jar,${catalina.home}/lib,${catalina.home}/lib/*.jar,/var/lib/tomcat6/common/classes,/var/lib/tomcat6/common/*.jar,${catalina.home}/lib/ext/*.jar,${catalina.base}/lib/ext/*.jar
Configuration parameters
Liferay's configuration parameters are all in a file named portal.properties that lives in jar in Liferay's lib. The way to override one of these parameters is to write it in a file named portal-ext.properties. 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
resource.repositories.root=/data/liferay
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 jdbc.default.username=username jdbc.default.password=password
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
auto.deploy.deploy.dir=/data/liferay/deploy
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 company.com domain. Create a file dev-server in /etc/apache2/sites-available so that it contains :
#LoadModule proxy_ajp_module modules/mod_proxy_ajp.so
NameVirtualHost dev-server.company.com:80
ErrorLog /var/log/apache2/ajp.error.log
CustomLog /var/log/apache2/ajp.log combined
<VirtualHost dev-server.company.com:80>
<Proxy *>
AddDefaultCharset off
Order deny,allow
Deny from none
#Allow from .example.com
</Proxy>
ProxyPass / ajp://localhost:8009/
ProxyPassReverse / ajp://localhost:8009/
</VirtualHost>
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
xxx.xxx.xxx.xxx dev-server.company.com
where xxx.xxx.xxx.xxx is the ip address of the machine where you have installed Liferay. Open the browser and go to the address http://dev-server.company.com and you shall see your Liferay up and running !