8/8/2019 Liferay Portal Setup Guide

1/14

Liferay Portal

Liferay Portalby Brian Kim

Copyright 2005 bkim@liferay.com

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

1.1.Introduction

8/8/2019 Liferay Portal Setup Guide

2/14

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 http://java.sun.com. 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

3/14

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

http://ant.apache.org. 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 http://www.liferay.com/web/guest/downloads/portal_source

8/8/2019 Liferay Portal Setup Guide

4/14

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

http://www.eclipse.org/downloads/index.php. 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

5/14

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

{Liferay}\portal.

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

6/14

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 http://www.orionserver.com. 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

7/14

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

8/14

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

portal.liferay.com-web.xml within {orion}\config\web-sites\. Youre file should look

something like this:

Figure x.2. portal.liferay.com-web.xml

8/8/2019 Liferay Portal Setup Guide

9/14

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 portal.liferay.com-

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

10/14

connection-driver="com.mysql.jdbc.Driver"

url="jdbc:mysql://localhost/lportal"

username="root"

password=""

inactivity-timeout="30"

schema="database-schemas/mysql.xml"

/>

2.4.4. Configuring Your Properties

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

to your build.properties, you want to override any property settings within portal-ext.properties rather than inportal.properties itself. To configure your portal, create a

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

add the following setting:

portal.ctx=/portal

Again, note that this property setting in portal-ext.properties overrides the property

setting inportal.properties.

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

line:

app.server={orion}

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

11/14

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 Kim.properties).

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

directory of course):

lp.ext.dir={Liferay}/ext

(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

{Liferay}\ext!

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

8/8/2019 Liferay Portal Setup Guide

12/14

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

lines:

lp.ext.dir={Liferay}/ext

app.server.type=tomcat

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

http://www.sysdeo.com/eclipse/tomcatPlugin.html, 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

13/14

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:

-Djava.security.auth.login.config={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):

-Xmx512m

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

14/14

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:

http://www.liferay.com/web/guest/documentation/development/databases

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.