Although lesser hardware requirements may work when developing and customizing Liferay, we recommend the following:

As with any enterprise Java application, setting up Liferay can be a daunting task. Liferay leverages several frameworks. Fortunately, most of these frameworks come bundled with Liferay. What you do need to install are some of the basic tools that Liferay uses. First ensure that you are using the right Java JDK. You should be using the latest release of J2SE 1.4.2 or J2SE 5.0, which may already be installed on your machine. If not, download the latest version from http://java.sun.com. Since we will be installing several Java technologies, install/unzip your files under a common folder such as D:\Java. You can choose to install them into any directory of your preference, but from here on out the installation folder will be referred to as {Java}. Although you can use Sun’s default Java compiler, we recommend using IBM’s Jikes compiler – it is faster and generally more descriptive with compile errors. Make sure you download version 1.21 if you are using J2SE 1.42 or version 1.22 if you are using J2SE 1.5. Finally, you will need to download the latest version of Ant, a Java-based build tool, from http://ant.apache.org. Once you have downloaded and installed/unzipped all the files described above, you will need to set your environmental variables to point to them. In Windows, open your Control Panel, choose System properties, click the Advanced tab, and click Environmental 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 the 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 developer’s 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

In order to keep current with Liferay’s upgrades, you will want to create an extension environment. First, go to http://www.liferay.com/web/guest/downloads and download the latest stable Liferay Portal Enterprise source. Unzip the bundle into a directory like D:\svnroot\liferay (we use SVN as a code repository), which we will refer to as {Liferay}. Then download the latest stable Liferay Portal bundle, in particular Liferay Portal Professional (Bundled with Tomcat) for this tutorial. The Tomcat bundle will be explained later on in this chapter.

Despite the fact that you could modify and deploy Liferay Portal with a simple editor like Textpad, a good IDE can help speed up the process. We will now see 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 and then run it. Select File from the menu bar and then choose Switch Workspace. Within 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 Project from the dialogue box and click Next. In the New Java Project window, enter “portal‿ as the Project Name, and then click Finish.

Figure 2.3 Adding a new java project

If you have 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 the Libraries tab from the right, your portal 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. To add Liferay’s build files, 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.

Figure 2.3 Adding the Ant plugin

It is recommended that you develop your portlets via an Extension Environment. This will allow you to upgrade your portal easily. Any time a new stable version of Liferay Portal is released, all you would need to do is drop in the new jars and you’re set to go. With that said, your development should only be done within the Extension Environment—meaning, all new classes, JSPs, and all changes in general should be within {Liferay}\ext. This will be further explained later.

Setting up your Extension Environment is simple. Before anything, you will need to change 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

Next, in the Ant View described in 2.3, you should be able to expand portal’s build.xml target list. Among the targets, you should see clean, start, and build-ext. Double click these targets (in that order) while watching the Console View. You should see a 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. You may find that you might have incorrectly set some of your properties. If all goes well, you should be able to browse your new extension directory by going to {Liferay}\ext!.

Remember the Liferay Portal Professional (Bundled with Tomcat) that you downloaded in section 2.2? Well, here’s what you need to do with it.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 ext as the Project name instead.

If you are planning on using Liferay Portal Professional, which implements the Spring framework, it is recommended that you download the Sysdeo Eclipse Tomcat plugin. This plugin will allow you to troubleshoot Liferay Portal using Eclipse’s 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 plugins folder (i.e. {Java}\eclipse\plugins\com.sysdeo.eclipse.tomcat_3.0.0). Close and then restart Eclipse. You should see the Tomcat icons just below the Search menu.

Let’s configure your Tomcat plugin now. Choose Windows from the menu bar, Preferences, then select Tomcat from the left navigation. You will need to select the appropriate Tomcat version. If you downloaded Liferay Portal Professional (Bundled with Tomcat), then check Version 5.x. You will also need to set the following variables:

Tomcat home: {Liferay}\ext\servers\tomcat

Configuration file: {Liferay}\ext\servers\tomcat\conf\server.xml

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 Tomcat node), and click the Add button respective to the Append 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 your JVM 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, you’ll find that your Tomcat runs correctly the first time, but not on successive attempts.

If you are 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‿ setting. To test to see if you have 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.

The Liferay bundles come with Hypersonic SQL as the built-in database. But, if you would like to setup Liferay to run on a database, take a look at the Database section of the User Guide. There it will go in depth into how to setup and connect to your database of choice depending on your server.

Now that you have your environment all configured, click the Tomcat icon to start up your web server. As long as you have left the default settings, you should be able to browse to http://localhost and see Liferay Portal load.

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