Running Liferay on Shared Hosting

This is a little off my usual set of topics, but something that hopefully others will find valuable, since there is such little information about this on the net.

Let's say that you have are launching a new portal website for a Java technology project (such as projavafx.com, and have the following constraints/desires:

You need a site that can handle dynamic content, access controls, forums, blogs, etc.
The underlying portal technology needs to be Java-based. No way you are hacking PHP (been there, never again...)
You are on a budget. It is a choice between server hosting and paying your cable bill, and not having the latter would impact your happiness more than the former.

So, with those constraints, you might be brave enough to try putting Liferay Portal on a Shared Tomcat Hosting plan. Would a dedicated VPS be easier? Sure, but you also pay more $$$ per bandwidth/disk/cpu.

(I am intentionally not mentioned any hosting companies by name, but if you look around you should be able to find shared Tomcat hosting for under $10/month.)

What to Download

By default Liferay directs you to a self-contained Tomcat installer that will set up a new Tomcat instance from scratch. You will need to grab this as well as the WAR distribution that is a little bit more buried on the site. There are also some ancillary downloads, such as the tunnel-web jar that are helpful as well, all of which can be found in the Additional Files section: http://www.liferay.com/web/guest/downloads/additional

At a minimum you will need:

Liferay Portal 5.x Bundled with Tomcat 6.0 (default download)
Liferay Portal 5.x WAR

(5.2.3 was the current version at the time of this writing, but feel free to grab the latest and let me know if anything has materially changed by leaving a comment.)

Basic Setup

The default Liferay configuration assumes that you have access to the Tomcat directory and can drop shared libraries and such into the base installation. This is definitely not possible in a shared environment, so instead we will hack the WAR file to make everything work cleanly instead:

Unpack liferay-portal-tomcat-6.0-5.x.zip
Look for the jar files under tomcat-6.x/lib/ext
Copy all the jar files from that folder into liferay-portal-5.x.war under WEB-INF/lib

Note: You would think that the Liferay Portal Dependencies jar from the Additional Files section would contain all the jars you need, but it only has a subset. Unfortunately, the only way to get the full set of jars is by grabbing them from the bundled Tomcat distribution.

The next problem is that you won't have access to the shared Tomcat context to setup custom context properties. Fortunately, all of this can be easily configured in a portal-ext.properties file, which is formatted as a standard Java properties file. Some of the parameters that you will need to use include:

portal.ctx - This allows you to set the LifeRay root context if you are running from a sub-folder (which is very common in a shared hosting environment)
liferay.home - Folder where liferay will store documents and artifacts. This should be set to an absolute path within your home folder that is configured to be writable by the Tomcat process.
jdbc.default.* - You can set the dirverClassName, url, username, and password that are specific to your hosting environment.

Here is an example portal-ext.properties file:

[plain] portal.ctx=/portal liferay.home=/home/widgetfx/liferay jdbc.default.driverClassName=com.mysql.jdbc.Driver jdbc.default.url=jdbc:mysql://localhost/widgetfx_liferay?useUnicode=true&characterEncoding=UTF-8&useFastDateParsing=false jdbc.default.username=xxxxxxxx jdbc.default.password=xxxxxxxx [/plain]

Once you have updated it for your server hosting settings, add it to liferay-portal-5.x.war under WEB-INF/classes.

All that is left is to make sure your database is setup and deploy this WAR file to your hosting provider. Liferay should come up by itself, or if not check catalina.out for common errors (like database access permissions).

cPanel Tip: If your shared hosting provider uses cPanel to deploy Tomcat applications, you may have trouble getting it to map requests from Apache to Tomcat under the Liferay directory. An easy way to do this without hacking Apache is to put a .htaccess file under the Liferay root directory with the following contents:

[shell] SetHandler jakarta-servlet SetEnv JK_WORKER_NAME ajp13 [/shell]

Setting up Multiple Instances

All the instructions so far assume you are only setting up one instance (and that no one else has already setup a Liferay instance on the same server). However, if you want to go multi-instance or just prevent future collisions, some more invasive hacking is required.

Inside of liferay-portal-5.x.war, hidden in portal-impl.jar there is some magical JMX and MBean magic to handle statistcs and configuration that will blow up horribly with multiple instances. To disable this you will need to:

extract WEB-INF/lib/portal-impl.jar
inside portal-impl.jar edit META-INF/hibernate-spring.xml and change the statistics key to a unique value (highlighted in bold): <entry key="Hibernate:name=statistics">
inside portal-impl.jar edit META-INF/messaging-sprint.xml and comment out the JMX bean and reference to it in MessagingConfigurator bean:

Once these changes are deployed you can now safely bring up multiple instances as separate Tomcat web applications.

Congratulations, you now have a Liferay instance working on your shared server configuration!

What Next?

While this covers the basics, here are some things that require additional tweaking:

Plug-ins cannot be cannot be installed automatically
Additional Liferay themes need to be manually deployed
Tunnel-web needs to be configured differently

If I am feeling adventurous (and there is interest), I will do a part 2 of this to go over tunnel-web and plug-in/theme configuration in a shared hosting environment.