How to debug a Liferay server with Eclipse

This document describes the configuration of Eclipse 3.4.1 that will allow to start, stop and debug a Liferay server. We assume that Eclipse has been installed and that the WST and JavaEE developers tools are installed. This tutorial describes a developer setup and therefore we will use MySQL database, instead of the default Hypersonic database. Therefore you will need to have administrator access to a MySQL installation. For this installation you also need a suitable JDK (1.5 and upwards). The following software must be installed on your computer Eclipse with WST and JavaEE developers installation; we used version3.4.1 JDK, we used version 1.6.0_01 MySQL database server, we used MySQL 5.0

Install Liferay server on your local machine

First download Liferay Portal 5.1.2 bundled with Tomcat the Liferay download page at http://www.liferay.com/web/guest/downloads/portal Unzip the content of the package to a location of your choice. We assume for this tutorial that this location is d:\bin\liferay. Adapt path accordingly when you choose another location. Create a new catalog called lportal in MySQL. Create a new user in MySQL that has sufficient access rights to this catalog. We use the user liferay for this purpose. We granted this user full control, which is probably not the best idea. Next we must change the Liferay configuration in order to switch from the default Hypersonic database to the MySQL database. For this you need to modify the d:\bin\liferay\conf\Catalina\localhost\Root.xml file. Comment the Hypersonic entry and uncomment the MySQL entry. Modify MySQL entry with db user details, in our case the user was liferay. To check the setup of Liferay we first launch the server by starting the startup.bat from d:\bin\liferay\bin. When the server is up and running we can open the browser at http://localhost:8080 and log in using theprovided administrator account which is test@liferay.com using the password test. Your browser should look something like this.

Setting up Eclipse
First we create a server configuration to start and stop the Liferay server from our Eclipse environment. For this we first create a new server configuration. Select FileNewOther and choose the Server entry from the dialog. See screen below.

In the Server wizard select Tomcat 5.5 Server and provide a suitable name for this server. See the screenshot below.

Press next and fill in the Tomcat installation directory which is in our case d:\bin\liferay. Make sure that you select a JDK as the JRE to use for the server.

Now press Finish. Next we need to configure the server. This can be done by opening the configuration file. To do this double click on the Liferay server in the Servers view. Change the Server location to the second option (Use Tomcat installation) and change the default deploy path to webapps. See screenshot below.

Save the modifications by clicking on the save icon (or Ctrl-S). Next we need to change the VM arguments. Click the Open launch configuration link and switch to the Arguments tab of the dialog.

Add the following parameters as first entries of the VM Arguments: -Xms128m -Xmx512m -XX:MaxPermSize=128m -Djava.io.tmpdir="D:\bin\liferay\temp" -Djava.security.auth.login.config="D:\bin\liferay\conf\jaas.config" -Dfile.encoding=UTF8 -Duser.timezone=GMT+1 Now the dialog should look something like this.

Press the Apply and OK buttons to apply the changes. If everything was configured correctly the Liferay can now be started and stopped from the server. Before you attempt this make sure you have stopped the Liferay server using the shutdown.bat in d:\bin\liferay\bin. Launch the server by pressing the start button ( should look similar to the screenshot below. ). The server should start and the output console

Installing Sources
We create a separate Eclipse project containing the sources of Liferay. This project will allow us to set specific breakpoints and it provides an easy way to lookup the source code of Lifeway when debugging. First download the Liferay Portal 5.1.2 Source from the Liferay download page at http://www.liferay.com/web/guest/downloads/additional. Unzip the source package at d:\bin\liferay-src (or to another location of your own choice). Next we create a new Eclipse Java project that references these source by clicking FileNewJava Project Give the new project a suitable name. Next select Create project from existing source and fill in the location of the source files, in our case d:\bin\liferay-src.

Press the Finish button. This can take a while as Eclipse starts building the project.

Debugging the sources

In order to debug the server must be (re)started in debug mode. Setting a breakpoint in the sources will cause Eclipse to switch to de debugging mode (when the breakpoint is reached). Now we can associate the sources by clicking Edit Souce Lookup Path

Click the Add button to associate the LiferayServer project.

For this purpose select Java Project from the list.

Choose the LiferayServer project you have created before.

Eclipse now shows the source files. You now can proceed debugging the server.