Liferay Part 1 – Setting up Liferay with MySQL

I recently got the opportunity to work on a project involving Liferay, which is an open source Java based enterprise portal. I was new to Liferay at the start, and thought of sharing my experiences of working with Liferay. I’ve broken down my thoughts/experiences into a series of blog posts that will get published over the course of next month or two.

This is the first part of that series and details simple steps for getting started with Liferay and configuring it to work with MySQL back-end database.

Other articles of the Liferay series:

  1. Setting up Liferay with MySQL database
  2. Setting up Liferay Extensions environment
  3. Inter-portlet communication (both within a war and different wars)
  4. Step-by-step guide to creating a Liferay Hook
  5. Customizing Liferay login process

Installing and setting up Liferay portal

I assume that you have installed Java on your machine and have configured it properly.

  • First step is to download the Liferay portal from their download site
  • . Liferay comes either as a standalone portal that you can deploy within an existing portal container (e.g. jboss, tomcat etc.) or a bundle containing both Liferay and a container. I would recommend getting bundle to get started (specially if you are completely new to Liferay) since it makes your life easier. Check out the links at the end of this tutorial if you want a specific version of Liferay.

  • Once the file is downloaded, unzip it to a folder of your choosing (e.g. C:Devappsliferay5). I will be referring to this base directory as %LIFERAY_BASE% for the remainder of the article. For example, after installing a jboss+tomcat+liferay bundler, your should have a folder structure similar to Figure 1 below. I will be referring to the jboss/container installation path (C:Devappsliferay5tomcatjboss-tomcat-5.0.0) as %LIFERAY_JBOSS% from here on.
  • We are now at a stage of starting up the Liferay server. Open up a command prompt and navigate to %LIFERAY_JBOSS%bin folder, and execute the run.bat file. After about a minute or so (might take slightly longer depending on your machine specifications) you should see a new browser window at localhost:8080/web/guest/home. The location and the file to execute can vary depending on your chosen container (e.g. jboss, tomcat, resin etc.)

Figure 1 - Liferay folder structure

Configuring the Liferay development environment

Liferay development process is built around Apache ANT, and the first step is to download the latest version of ANT and setup the following environment variables:

  • ANT_HOME with the fully qualified path of where you installed/unzipped ant (e.g. C:Devant-1.8)
  • Update PATH variable to add %ANT_HOME%bin to the end of existing value (separate by a semi-colon in windows systems or by a colon in Linux)

Open up a new command line window and type in ant and hit enter. If everything is properly setup, you should get a message similar to “Buildfile: build.xml does not exist!”. Ant is properly set up and you are ready to move on to actually setting up Liferay development environment!

Step 1 – Setup Liferay Plugin SDK

Since Liferay 5, the recommended way of enhancing Liferay functionality (e.g. changing default Liferay behaviour and/or adding new Portlets etc.) is by using the Liferay Plugin SDK.

  1. Download the plugin sdk for your installed version of Liferay from here and unzip it under %LIFERAY_BASE% (see Figure 1 above for the correct folder structure)
  2. The settings for your Liferay installation and development environment are specified in the file found under plugin SDK folder (e.g. %LIFERAY_BASE%liferay-plugins-sdk-5.2.3). Create a new file called build.{}.properties to modify the properties based on your local installation (where {} is the login name of your windows/linux account). The changes will depend on the type of your Liferay installation (e.g. whether it is bundled with tomcat, jboss or glassfish etc.). The snippet below shows my build.{}.properties file based on my folder structure and jboss/tomcat server:
    [sourcecode language="xml"]
    ## contents of file
    ## (based on the section labeled ‘Specify the paths to an unzipped JBoss+Tomcat 5.0.x bundle’
    ## in file)

    # my tomcat/jboss server (i.e. %LIFERAY_JBOSS% path) relative to plugin SDK folder
    # folder in %LIFERAY_JBOSS% where the global libraries (e.g. jar files) are stored)${app.server.dir}/server/default/lib
    # folder where the liferay will be deployed to

Step 2 – Setup Portal Source

The source code for the Liferay Portal will be handy when you are developing Portlets, Hooks, Themes etc. with Liferay Plugin SDK. You can easily refer to Liferay code when needed directly from your preferred IDE (such as Eclipse or NetBeans). Besides, whenever you create a new plugin using the Plugin SDK and setup as an Eclipse project, the classpath will assume that you already have the Portal source project in your Eclipse workspace!

  1. Simply download the correct portal source (based on the installed Liferay version) from here (e.g. look for the zip file named “liferay-portal-src-{version}.zip“), and unizp the file to a folder called ‘portal‘ under %LIFERAY_BASE% as shown in Figure 1.
  2. Create a new file called app.server.{}.properties with the following content under %LIFERAY_BASE%portal folder. This file will customise your portal source depending on your local setup of Liferay installation.
    [sourcecode language="xml"]
    ## content for file
    ## see file for other possible values

    ## set the path for application server directory (i.e. %LIFERAY_BASE%tomcat) relative to the portal source folder

    ## Properties modified for JBoss+Tomcat setup
    ## see file for other configurations
    NOTE: app.server.jboss-tomcat.dir value can be a fully qualified path (e.g. C:/Dev/apps/liferay/tomcat/jboss-tomcat-5.0.0)

  3. Create build.{}.properties file with the following content under %LIFERAY_BASE%portal folder
    [sourcecode language="xml"]
    ## content for file

    ## Following properties are optional.
    ## Only include/un-comment if encounter out of memory issues

  4. Open up a command prompt, navigate to %LIFERAY_BASE%portal folder (there should be a build.xml file in here, otherwise you haven’t unziped it properly) and type the following command to build an Eclipse project:
    [sourcecode language="xml"]
    ant setup-eclipse
  5. Open up Eclipse IDE and import the ‘portal’ folder as an existing project (from folder). You should not see any errors after Eclipse finish building the workspace

Configuring Liferay to use MySQL database

Liferay comes pre-configured with a default database called HSQL or “hypersonic.” This is a flat-file based simple database and is not meant for production use! It is easier (and recommended) to switch to a real database from the very beginning. I am outlining the steps to configure Liferay to use MySQL at the back-end.

  1. Download and install MySQL on your machine. The download package can be found here
  2. Create a new file called liferay-ds.xml at %LIFERAY_JBOSS%serverdefaultdeploy folder with the following content. This maps the data source to be used when liferay is loaded. Ensure that you change the variables {mysql-port}, {mysql-root-username} and {mysql-root-password} properties in the xml file based on your local MySQL environment setup.
    <?xml version="1.0" encoding="UTF-8"?>
  3. Create a new file called at %LIFERAY_JBOSS%serverdefaultdeployROOT.warWEB-INFclasses with the following content. Ensure that you change {mysql-port} value in the file based on your MySQL configuration.
    [sourcecode language="xml"]
    # Username and pw are set to blank by default

  4. Go to MySQL (either workbench GUI or console) and create database named ‘lportal
    [sourcecode language="sql"]
    create database lportal character set utf8;
  5. Delete the tmp and work directories from the %LIFERAY_JBOSS%serverdefault folder. This step is necessary to remove cached files created by default (hypersonic) database.
  6. Restart the liferay server and login with username: and password ‘test’ (without quotes)

I have purposefully left out instructions on how to create your first Portlet, Hook etc in Liferay. You can find a good example at Liferay site. Please feel free to ask me if you encounter any issues or have questions. I am open to writing a simple hello-portlet example if there is enough interest.

Other Tips

Here are some of the tips that a budding Liferay developer might find useful:

Changing the Timezone for Application Server

Liferay sets the timezone to GMT for the application server (e.g. tomcat/jboss), which could affect the DateTime values used within the portlets or other applications running within the same app server. For development purposes, it can be desirable to set this to the timezone of your local machine (e.g. “Pacific/Auckland” for NZ).

  • Open %LIFERAY_JBOSS%binrun.bat file in a text editor (or in Linux).
  • Change the –Duser.timezone to an appropriate value. You can find a full set of timezone values from here. E.g.
    [sourcecode language="xml"]
    rem this line already exists in run.bat file. Just change ‘GMT’ to your desired timezone value.
    set JAVA_OPTS=%JAVA_OPTS% -Xmx1024m -XX:MaxPermSize=256m -XX:SurvivorRatio=10 -Dfile.encoding=UTF-8 -Duser.timezone=Pacific/Auckland

Working with common library files

Place all your common jar files that are shared by multiple portlets, hooks etc in %LIFERAY_JBOSS%serverdefaultlib folder. This helps to reduce the size of your portlets and avoid version conflicts. I recommend to include jars as part of portlet’s lib folder only if that library is only used by that specific portlet.

Remote debugging Liferay with Eclipse

Remote debugging is very handy when you want to test out something in a client-server setup during development phase. To accomplish this with Liferay and Eclipse:

  1. Open the %LIFERAY_JBOSS%binrun.bat file (under windows) and add the following line before printing out the JAVA_OPT variables:
    [sourcecode language="xml"]
    set JAVA_OPTS=%JAVA_OPTS% -Xdebug -Xrunjdwp:transport=dt_socket,address=8000,server=y,suspend=n
  2. Go to Eclipse and open the Debug Dialog setup window. Create a new “Remote Java Application” under ‘Debug Configurations’. Modify the ‘Host’ and ‘Port’ values under ‘Connection Properties’ to the Liferay instance you want to remote debug. If you are debugging on the same machine you can use ‘localhost‘ as the ‘Host’. The port number should be the same number as the ‘address=‘ value that you set for the JAVA_OPTS above (in this example the port number is 8000). Next you should go to the ‘Source’ tab and attach code to debug against. At least add the ‘portal’ project you imported to Eclipse earlier (i.e. Portal source) and any other projects for the portlets/hooks you might want to debug.
  3. Once you have the Liferay installation up and running, simply go to Eclipse->Debug and select the remote debug configuration you created earlier to hook up Eclipse with Liferay! It will automatically suspend when Liferay executes the code with a debug point!

Useful references

  1. Download previous releases of Liferay (standalone, source, bundled packages etc.) from the download repository
  2. Download the latest version of Apache ANT from
  3. More information about the Liferay Plugin SDK can be found at Liferay Wiki

2 Responses to Liferay Part 1 – Setting up Liferay with MySQL

  1. Pingback: Liferay Part 2 – Setting up Liferay extensions environment | Thiranjith's Blog

  2. Your reference links is great and useful to improved my knowledge and problem solving for liferay development.

Leave a Reply

Your email address will not be published. Required fields are marked *


You may use these HTML tags and attributes: <a href="" title=""> <abbr title=""> <acronym title=""> <b> <blockquote cite=""> <cite> <code> <del datetime=""> <em> <i> <q cite=""> <strike> <strong>