liferay portal setup guide

Upload: edwin-raito-nurdiansyah

Post on 10-Apr-2018




0 download

Embed Size (px)


  • 8/8/2019 Liferay Portal Setup Guide


    Liferay Portal

    Liferay Portalby Brian Kim

    Copyright 2005 [email protected]

    This is a tutorial for Liferay Portal. Liferay Portal is an open source portal that helps

    organizations collaborate more efficiently by providing a consolidated view of disparate

    applications via a web browser.

    Table of Contents1. Introduction

    1.1. Introduction

    1.2. Recommended Requirements

    2. Installation2.1. Setting Up Your Development Environment

    2.2. Obtaining Liferay Portals Source Code

    2.3. Installing Your IDE Eclipse

    2.4. Developing with Liferays Core Source

    2.4.1. Obtaining Orion Application Server2.4.2. Configuring Eclipse with Orion

    2.4.3. Setting Up Orion

    2.4.4. Configuring Your Properties

    2.4.5. Deploying to Orion

    2.5. Creating an Extension Environment

    2.5.1. Setting Up Ext

    2.5.2. Adding Plugin support

    2.5.3. Hooking Up To a Database

    2.5.4. Starting Liferay

    Chapter 1. Introduction


  • 8/8/2019 Liferay Portal Setup Guide


    In this document, my goal is to help you setup your environment so that you can begin

    developing your own custom portlets from scratch. This document assumes that you

    have some working knowledge of Servlets, JSPs, and web development in general.Although Ill be assuming that you are running on a Windows OS, Ill try to keep my

    explanations general enough so that they can be used for any operating system.

    This tutorial will cover the setup of a development environment, from using an IDE

    such as Eclipse to setting up your database connections. While my focus will be on

    using Liferay Professional the Tomcat Spring framework version I will briefly touch

    on the Enterprise version as well.

    1.2. Recommended Requirements

    Although you could probably get away with lesser requirements, when developing and

    customizing Liferay, we recommend the following hardware requirements:

    1 gig of RAM 2.0 ghz Pentium processor

    Chapter 2. Installation2.1. Setting Up Your Development Environment

    As with any enterprise Java application, setting up Liferay can be a daunting task.

    Liferay leverages several frameworks. Fortunately for you, most of these frameworks

    come bundled with Liferay already. What you do need to install, however, are some of

    the basic tools that Liferay uses. Lets first ensure that youre using the right Java JDK.

    You should be using the latest release of J2SE 1.4.2, which may already be installed on

    your machine. If not, download the latest version from Sincewell be installing several Java technologies, I typically install/unzip my files under a

    common folder such as D:\Java. Obviously you can choose to install them into any

    directory of your preference, but from here on out I will reference the installation folder

    as {Java}. Although you can use Suns default Java compiler, we recommend using

    IBMs Jikes compiler it is generally more descriptive with compile errors. Make sure

  • 8/8/2019 Liferay Portal Setup Guide


    you download version 1.21, since version 1.22 is oriented towards J2SE 1.5, which

    Liferay Portal does not use due to backwards compatibility reasons. Finally, youll need

    to download the latest version of Ant, a Java-based build tool, from Once youve downloaded and installed/unzipped all the filesdescribed above, youll need to set your environmental variables to point to them. In

    Windows, open your Control Panel, choose System properties, click the Advancedtab,

    and clickEnvironmental Variables.

    Figure 2.1. Environmental Variables

    Choose New, and then add the following three variables: JAVA_HOME,

    JIKES_HOME, and ANT_HOME. Each respective variable needs to point to the

    directory in which your tools reside. If you look at Figure 2.1, you can see that my

    JAVA_HOME variable points to {Java}\j2sdk1.4.2_05. It is recommended that you

    remove the CLASSPATH variable to prevent conflicts when compiling. It is generally

    good practice to develop without the use of a classpath variable, since doing so creates

    a dependency on the developers machine. Once you have your three System variables

    setup, you need to edit the Path variable by adding the

    following: %ANT_HOME%\bin;%JAVA_HOME%\bin;%JIKES_HOME%\bin

    2.2. Obtaining Liferay Portals Source Code

    In order to keep up-to-date with Liferays upgrades, you will want to create an extension

    environment. To start, go to

  • 8/8/2019 Liferay Portal Setup Guide


    and download the latest stable Liferay Portal Enterprise source. I would recommend

    unzipping the bundle into a directory like D:\cvsroot\liferay (I use CVS as a code

    repository), which I will refer to as {Liferay}. Then download the latest stable Liferay

    Portal bundle, in particular Liferay Portal Professional (Bundled with Tomcat) for thistutorial. Ill explain what to do with the Tomcat bundle later on in this chapter.

    2.3. Installing Your IDE Eclipse

    Despite the fact that you could modify and deploy Liferay Portal with as simple as an

    editor as Textpad, a good IDE can help speed up the process. Ill show you how Eclipse

    plugins can make life easier for editing, deploying, and running Liferay Portal.

    Download the newest version of the Eclipse from Install Eclipse into {Java}\eclipse andthen run it. Select File from the menu bar and then choose Switch WorkspaceWithin

    the input box, type the path of {Liferay}, as shown in Figure 2.2.

    Figure 2.2. Creating a new Workspace

    To setup your project within your workspace, select File from the menu bar,New, then

    Project. Select Java Projectfrom the dialogue box and clickNext. In the New Java

    Project window, enterportal as the Project Name, and then click Finish.

  • 8/8/2019 Liferay Portal Setup Guide


    Figure 2.3. Adding a new java project

    If youve setup the Workspace correctly, you should be able to see the portal project

    within the Navigator pane of the Resource perspective. If you right click on the root

    directory of the project, select Properties, choose Java Build Path from the left

    navigation, and theLibraries tab from the right, yourportal project should have all the

    necessary jars loaded already. These jars are loaded via the .classpath file that exists in


    Adding plugin support for Eclipse is even easier. Since Eclipse comes bundled with Ant,

    setting up Ant is as easy as selecting Window from the menu bar, choosing Show View

    and then Ant. You should see the Ant tab displayed within your current perspective.

    Adding Liferays build files is just as easy. Simply select the Ant tab in your

    perspective and then click the Ant icon with the + symbol. Note that each directory

    within Liferay contains its own build.xml file, which Ant reads. When clicking the Ant

    icon, select the build.xml file within the portal directory. Your Ant setup should look

    like Figure 2.3.

  • 8/8/2019 Liferay Portal Setup Guide


    Figure 2.3. Adding the Ant plugin

    2.4. Developing with Liferays Core Source

    The following section outlines how to develop and debug Liferays core source using

    Orions application server. It is important to note that working off the core source is not

    recommended. If you are trying to extend the functionality of Liferay Portal, it is

    suggested that you create an Extension Environment, as outlined in the next section

    (2.5). Development of the core portal should only be done for bug fixes or

    enhancements that potentially would make it into the next build. Typical developers willnot need to read this section.

    2.4.1. Obtaining Orion Application Server

    Although Liferays core source could be deployed to other application servers, the build

    files were written specifically with Orion in mind. An evaluation version of Orion is

    available for download at Extract the files into your

    installation folder (i.e. {Java}\orion-2.0.6), which I will reference as {orion}. To test out

    your server, from your Orion home directory, run the command: java jar orion.jar.

    2.4.2. Configuring Eclipse with Orion

    Running Orion from your Eclipse IDE takes a little more time to setup. First change

    your perspective to Debug. Underneath the menu bar, there is a bug-like icon. Click

  • 8/8/2019 Liferay Portal Setup Guide


    the small drop down arrow to the right of it and then select Debug, at which point a

    dialogue box should appear.

    Figure x.1. Debug

    If you have any existing configurations under the Java Application group that are no

    longer applicable, you can go ahead and delete them. Go ahead and click the New

    button, and then make the following changes:

    Main Tab

    1. change the Name of the configuration to orion2. set the Main class to be com.evermind.server.ApplicationServer

    Arguments Tab

    1. Program arguments: -config {orion}/config/server.xml -userThreads (note thatyou need to change the directory path)

    2. VM arguments: -Xmx256m -Dfile.encoding=UTF8 -Duser.timezone=GMT

  • 8/8/2019 Liferay Portal Setup Guide


    Classpath Tab

    1. under the User Entries group, remove the portal (default classpath) entry2. clickAdd External JARs, and then browse to your orion.jar to add it

    Note: make sure that within your JRE Tab, your Project JRE points to a SDK as

    opposed to just a JRE (i.e. my Project JRE has j2sdk1.4.2_05 next to it in parenthesis.

    This may require you to add another entry within Java (from the left navigation)

    Installed JREs.

    2.4.3. Setting Up Orion

    There are three key files when configuring Orion. The first, {orion}\config\server.xml,

    lets you specify which web-sites will be accessible when started up. Add a new

    website by inserting the element:

    You can also specify for Orion to use another compiler by adding:

    Now that youve specified a new website, you need to create a file called within {orion}\config\web-sites\. Youre file should look

    something like this:

    Figure x.2.

  • 8/8/2019 Liferay Portal Setup Guide


    Finally, in {orion}\config\application.xml, you need to add both web-module elements

    and ejb-module elements. All web-app elements declared in your

    web.xml must be defined in your application.xml:

    Figure x.3. application.xml

    Add the references to your EJBs as well by inserting the ejb-module elements. Note that

    by using the file: prefix, you can have Orion look for the direct files. An advantage

    of using this prefix is that you dont have to deploy your files to the server. This can be

    particularly useful for quickly debugging JSPs (simply save your JSP and refresh).

    Another advantage is that for class files, you can just compile the source files rather

    than having to compile anddeploy.

    Note: When using the file: prefix for the portal-ejb module, you need to ensure thatthe portal-ejb.jar does not exist within your {orion}\applications\ directory.

    Finally, you must edit your {orion}\config\data-sources.xml to allow your application to

    access your database. If you are using MySQL, make sure that the mysql.jar gets

    deployed to your {orion}\lib\ directory, and configure your data-sources.xml file like so:

  • 8/8/2019 Liferay Portal Setup Guide









    2.4.4. Configuring Your Properties

    Most of Liferays configuration is set using a flat file called Similar

    to your, you want to override any property settings within rather than itself. To configure your portal, create a

    new file within {Liferay}\portal\util-java\ called Within there,

    add the following setting:


    Again, note that this property setting in overrides the property


    2.4.5. Deploying to Orion

    In order for your ant scripts to know where to deploy to, you need to create an extension

    file named like app.server.{username}.properties. Within the file, add the following



    Remember that {orion} represents your orion home directory, and for this property,

    should also use forward slashes (i.e. app.server=D:/Java/orion-2.0.5). Finally, from yourAnt View in Eclipse, run the start and deploy targets from your portal directory. If

    youve used the file: prefix, dont forget to delete portal-ejb.jar after deploying!

    Youre all set! Go ahead and click the bug icon in yourDebug perspective, and within

    your console you should see Orion startup.

  • 8/8/2019 Liferay Portal Setup Guide


    2.5. Creating an Extension Environment

    It is in your best interest to develop your portlets via an Extension Environment. Thiswould allow you to upgrade your portal without any headaches. Any time a new stable

    version of Liferay Portal is released, all you would need to do is drop in the new jars

    and youre set to go. With that said, your development should only be done within the

    Extension Environment as well. Meaning, all new classes, JSPs, and all changes in

    general, should be within {Liferay}\ext.

    2.5.1. Setting Up Ext

    Setting up your Extension Environment is simple. Before anything, you will need tochange a property file (.properties) within {Liferay}\portal. Note that you should never

    change the values of the default .properties files. Instead, follow the instructions

    commented at the top of each .properties file, which states that you should instead create

    an extension file named like release.{username}.properties. You can find out what your

    ${username} value is by opening a command prompt from Start Run and seeing

    what name shows up after Documents and Settings (i.e. release.Brian

    Within your new .properties file, add just one line (with {Liferay} being the actual

    directory of course):


    (Note that its a forward slash)

    Next, in the Ant View described in 2.3, you should be able to expandportals build.xml

    target list. Among the targets, you should see clean, start, build-ext. Go ahead and

    double click those targets (in that order) while watching the Console View. You should

    see a whole lot of text scrolling by indicating that your Extension Environment is

    being built. To double check, quickly skim the Console output for any red errors. Youmay find that you might have incorrectly set some of your properties. If all goes well,

    you should be able to browse to your new extension directory by going to


    Remember the Liferay Portal Professional (Bundled with Tomcat) that I had you

  • 8/8/2019 Liferay Portal Setup Guide


    download in section 2.2? Well, heres what you need to do with it. Simply unzip the file

    into {Liferay}\ext\servers\tomcat. Like before, you need to create an

    app.server.{username}.properties file within {Liferay}\ext that includes only the two




    This designates where your Extension Environment is to copy files from, and what

    server directory to deploy to.

    In order to develop in Eclipse using the Extension Environment, follow the same

    instructions for adding a New Java Project (as described earlier for portal). However,this time, use the name extas the Project name instead.

    2.5.2. Adding Plugin Support

    If you are planning on using Liferay Portal Professional, which implements the Spring

    framework, it would be a good idea to download the Sysdeo Eclipse Tomcat plugin.

    This plugin would allow you to troubleshoot Liferay Portal using Eclipses debugger.

    Download the latest version (I have version 3.0) of the Sysdeo plugin from, and then unzip it into the pluginsfolder (i.e. {Java}\eclipse\plugins\com.sysdeo.eclipse.tomcat_3.0.0). Close and then

    restart Eclipse and you should see the Tomcat icons just below the Search menu.

    Lets configure your Tomcat plugin now. Choose Windows from the menu bar,

    Preferences, then select Tomcat from the left navigation. Youll need to select the

    appropriate Tomcat version. If you downloaded Liferay Portal Professional (Bundled

    with Tomcat), then checkVersion 5.x. Youll also need to set the following variables:

    Tomcat home: {Liferay}\ext\servers\tomcatConfiguration file: {Liferay}\ext\servers\tomcat\conf\server.xml

  • 8/8/2019 Liferay Portal Setup Guide


    Figure 2.4. Setting up Tomcat in Eclipse

    Since Liferay uses JAAS for authentication, you need to add a JVM parameter. Select

    JVM Settings from the left navigation (under the Tomcatnode) and click the Add button

    respective to theAppend to JVM Parameters section. When the small prompt comes up,

    add this:{Liferay}/ext/servers/tomcat/conf/jaas.config

    To allocate enough memory for Tomcat when Liferay is running, you need to add the

    following parameter as well (assuming you have at least 512 megs of RAM):


    Note: make sure that within yourJVM Settings your JRE points to a SDK as opposed to

    just a JRE (i.e. my JRE has j2sdk1.4.2_05 showing in the dropdown box). This may

    require you to add another entry within Java (from the left navigation) Installed

    JREs. Otherwise, youll find that your Tomcat runs correctly the first time, but not on

    successive attempts.

    If youre wondering what port your portal will be running on, check out your

    {Liferay}\ext\servers\tomcat\conf\server.xml and search for your Connector port

  • 8/8/2019 Liferay Portal Setup Guide


    setting. To test to see if youve setup Tomcat correctly, click on the cat-like icon at the

    upper left of your Eclipse window, and it should start up. Remember that you still have

    a database to setup, however.

    2.5.3. Hooking Up To a Database

    Unfortunately, writing documentation of how to hook up to a database would take too

    long (and probably bore you) since there are so many different databases you can use

    with Liferay Portal. The best reference for this would be on Liferays website,

    specifically here:

    There it will go in depth into how to setup and connect to your database of choice

    depending on your server.

    2.5.4. Starting Liferay

    Now that you have your environment all configured, go ahead and click the Tomcat

    icon to start up your web server. As long as youve left the default settings, you should

    be able to browse to http://localhost and see Liferay Portal load up!

    Note: because of the nature of Hypersonic, the Sysdeo plugin will not work correctly

    with our configuration. If you plan on using Hypersonic as your database, you will need

    to actually browse to {Liferay}\ext\servers\tomcat\bin in your command prompt, and

    manually type in startup to start Tomcat.