Why this document? #

This is a document for beginners. As a beginner, you want to know exactly what works and what doesn't. For instance, a document may say "Windows". Which version of Windows? Windows XP, 32-bit Vista, 64-bit Vista, 32-bit Server 2003, 64-bit Server 2003, 32-bit Server 2008, 64-bit Server 2008?

I now know that "64-bit Windows Server 2008" does NOT work with "Eclipse-3.3.2". Does "64-bit Vista" works with "Eclipse-3.3.2"? What about Eclipse-3.3.1? JDK 1.6.0_05 instead of JDK 1.6.0_06? I don't know. If you were a beginner, you might not want to spend a week to find out.

This document does not provide links to the required files. As I am providing the exact file names, you could find them easily using Google.

Configuration #

The following configuration has been tested with "32-bit Windows Server 2008":

• Liferay 5.01 RC bundle with Tomcat 5.5
• jdk1.6.0_06
• jikes-1.22-1.windows (necessity for Jikes may be doubted, see Jikes, section "Liferay v4.4+" )
• apache-ant-1.7.0
• eclipse-SDK-3.3.2-win32

32-bit Vista proved to be good too. These guidelines are generally valid for Liferay 5.1.0 and Tomcat 6.0 bundle also.

Required Files #

Download all of these files below and set aside for installation. They are all required for the development environment. Some of these tools, you can use alternatives but I haven't tested them:

 JDK 6: jdk-6u6-nb-6_1-windows.exe

 Ant 1.7: apache-ant-1.7.0-bin.zip

 Jikes 1.22: jikes-1.22-1.windows

 Liferay Extension Source: liferay-portal-ext-5.0.1.zip

 Liferay-Tomcat5.5 Bundle for JDK 5: liferay-portal-tomcat-5.5-5.0.1.zip

The bundle is an instance of Apache Tomcat preloaded with Liferay Portal. Not only does it have a build of the portal source, but also the required files in order to run this web application.

 Eclipse 3.3: eclipse-SDK-3.3.2-win32.zip (What you want is Eclipse Classic.)

 Tomcat Plug-In for Eclipse: tomcatPluginV321.zip

 Liferay Plug-In for Eclipse: liferay-ide-eclipse-1.0.2.jar

Installation and Setup #

Let's install the files that have been downloaded.

Setup D:\Java #

JDK 1.6.0_06 #

Install JDK to D:\Java\jdk1.6.0_06

Set JAVA_HOME. Right click "My Computer" and go to "Properties". Go to the "Advanced" tab and click on "Environment Variables" and you will need to add a new System variable. Set JAVA_HOME to "D:\Java\jdk1.6.0_06". Edit the PATH. Add the following to the beginning of the PATH system variable: %JAVA_HOME%\bin; Click OK.

Check that Windows recognizes Java and the correct version:

Ant 1.7.0 #

Unzip the ant archive to D:\Java\apache-ant-1.7.0

Set ANT_HOME. Right click "My Computer" and go to "Properties". Go to the "Advanced" tab and click on "Environment Variables" and you will need to add a new System variable. Set ANT_HOME to "D:\Java\apache-ant-1.7.0" Edit the PATH. Similar to JAVA_HOME, add the following to the PATH system variable: %ANT_HOME%\bin; Click OK.

Check that Windows recognizes Ant and the correct version:

Jikes 1.22-1 Windows #

(necessity for Jikes may be doubted, see Jikes, section "Liferay v4.4+" )

Unzip the jikes archive to D:\Java\jikes-1.22-1.windows . It should look something like this:

Set JIKES_HOME. Right click "My Computer" and go to "Properties". Go to the "Advanced" tab and click on "Environment Variables" and you will need to add a new System variable. Set JIKES_HOME to "D:\Java\jikes-1.22-1.windows"

Edit the PATH. Similar to JAVA_HOME and ANT_HOME, add the following to the PATH system variable: %JIKES_HOME%\bin;

Click OK.

Check that Windows recognizes Jikes and the correct version:

Setup D:\projects\liferay5.0.1\tomcat (Liferay-Tomcat5.5 Bundle) #

The Tomcat bundle is an instance of Apache Tomcat with Liferay Portal pre-installed and ready to run against an embedded Hypersonic database. Aside from installing the JDK, no configuration is required. You can simply download the bundle, unzip the archive into a directory of your choice and run startup.bat in the "bin" directory. Please do NOT use Hypersonic/HSQL in production! It is for demo purposes only.

Unzip liferay-portal-tomcat-5.5-5.0.1.zip to D:\projects\liferay5.0.1\tomcat

Go to the bin directory and double click startup.bat to start up the bundle. If the portal starts up it means you have installed Java correctly. Look at the Tomcat console and you should see a message that the Tomcat has started: You can also try logging on to the portal by pointing your browser to http://localhost:8080/ and using the username/password: test@liferay.com/test.

OK. Enough of fun. Shut it down for now by runing "shutdown.bat".

Setup D:\projects\liferay5.0.1\eclipse #

Unzip eclipse-SDK-3.3.2-win32.zip to D:\projects\liferay5.0.1\eclipse\

Unzip tomcatPluginV321.zip to D:\projects\liferay5.0.1\eclipse\plugins\

Copy liferay-ide-eclipse-1.0.2.jar to D:\projects\liferay5.0.1\eclipse\plugins\

Later in the document, you will start the eclipse IDE. (Not now)

Setup D:\projects\liferay5.0.1\ext #

Unzip liferay-portal-ext-5.0.1.zip to D:\projects\liferay5.0.1\ext\

This is the place where you will do all development, and from where you will do future deployments. Your EXT is a fully self-contained version of your entire portal source. You do not need the portal source any more in order to build.

Find your username by opening a command prompt and typing "env" and you will see your "username" there.

Assuming your username is "james", create a new file D:\projects\liferay5.0.1\ext\app.server.james.properties. Add the following line to the file

 app.server.tomcat.dir=D:/projects/liferay5.0.1/tomcat

Run the following in command prompt

 cd D:\projects\liferay5.0.1\ext
 ant deploy

At this point, starting up Tomcat and browsing to http://localhost:8080/ should give you the same result as starting the bundle.

Congratulations! You have successfully deployed from EXT and are ready to develop!

Configure Eclipse 3.3.2 #

Set up the Java Projects #

Startup eclipse by double clicking on D:\projects\liferay5.0.1\eclipse\eclipse.exe . Choose D:\projects\liferay5.0.1 as your workspace

Go to the Workbench:

Switch to "Java" perspective (if not yet), go to menu Window ==> Show View and open up "Navigator" and "Ant"

Go to menu File ==> New ==> Java Project

Name your project "ext" and use the "Create project from existing source" option. Point to: D:\projects\liferay5.0.1\ext

Click "Finish"

Now, let's set up the ant plugin so you can do your builds directly from within Eclipse! All you have to do is open up the "ext" project tree, and drag the build.xml file to the Ant window.

Now all you have to do is double click the "deploy" and task to do your build!

Set up the Tomcat Plug-In in Eclipse #

Go to the menu Windows ==> Preferences

Expand the "Tomcat" node on the side bar. Click the "Tomcat" node. Set Tomcat Version to "Version 5.x". Tomcat Home to "D:\projects\liferay5.0.1\tomcat". Choose Server.xml and select the "Configuration file" as "D:\projects\liferay5.0.1\tomcat\conf\server.xml"

Click the "Advanced" node on the side bar. Set "Tomcat base" as "D:\projects\liferay5.0.1\tomcat" Add "ext" in to Tomcat classpath.

Click the "JVM Settings" node on the side bar.

Add the following into the "Append to JVM Parameters"

 -Xms128m -Xmx512m -Dfile.encoding=UTF8 -Duser.timezone=GMT
 -XX:MaxPermSize=128m
 -Djava.security.auth.login.config=D:/projects/liferay5.0.1/tomcat/conf/jaas.config
 -Djava.endorsed.dirs=D:/projects/liferay5.0.1/tomcat/common/endorsed
 -Dcatalina.base=D:/projects/liferay5.0.1/tomcat
 -Dcatalina.home=D:/projects/liferay5.0.1/tomcat
 -Djava.io.tmpdir=D:/projects/liferay5.0.1/tomcat/temp

Or, in case of using Tomcat 6.0 bundle:

-Xms128m
-Xmx1024m
-XX:MaxPermSize=128m
-Dfile.encoding=UTF8
-Duser.timezone=GMT
-Djava.security.auth.login.config=D:/projects/liferay5.0.1/tomcat/conf/jaas.config
-Dorg.apache.catalina.loader.WebappClassLoader.ENABLE_CLEAR_REFERENCES=false
-Djava.util.logging.manager=org.apache.juli.ClassLoaderLogManager
-Djava.util.logging.config.file=D:/projects/liferay5.0.1/tomcat/conf/logging.properties
-Djava.endorsed.dirs=D:/projects/liferay5.0.1/tomcat/endorsed
-Dcatalina.base=D:/projects/liferay5.0.1/tomcat
-Dcatalina.home=D:/projects/liferay5.0.1/tomcat
-Djava.io.tmpdir=D:/projects/liferay5.0.1/tomcat

Set up the Debugger #

Let's set up the debugger. This way, you can run tomcat from within Eclipse, and step through any break points you have set.

Go to the menue Run ==> Open Debug Dialog...

Click on the "tomcat" Java Application and fill in these values in the Main tab:

Project: ext
Main class: org.apache.catalina.startup.Bootstrap

Click on the Arguments tab and fill in these values:

Program arguments: start
VM arguments:

  -Xms128m -Xmx512m -Dfile.encoding=UTF8 -Duser.timezone=GMT
  -XX:MaxPermSize=128m
  -Djava.security.auth.login.config=D:/projects/liferay5.0.1/tomcat/conf/jaas.config
  -Djava.endorsed.dirs=D:/projects/liferay5.0.1/tomcat/common/endorsed
  -Dcatalina.base=D:/projects/liferay5.0.1/tomcat
  -Dcatalina.home=D:/projects/liferay5.0.1/tomcat
  -Djava.io.tmpdir=D:/projects/liferay5.0.1/tomcat/temp

Or, in case of using Tomcat 6.0 bundle the VM arguments are:

-Xms128m
-Xmx1024m
-XX:MaxPermSize=128m
-Dfile.encoding=UTF8
-Duser.timezone=GMT
-Djava.security.auth.login.config=D:/projects/liferay5.0.1/tomcat/conf/jaas.config
-Dorg.apache.catalina.loader.WebappClassLoader.ENABLE_CLEAR_REFERENCES=false
-Djava.util.logging.manager=org.apache.juli.ClassLoaderLogManager
-Djava.util.logging.config.file=D:/projects/liferay5.0.1/tomcat/conf/logging.properties
-Djava.endorsed.dirs=D:/projects/liferay5.0.1/tomcat/endorsed
-Dcatalina.base=D:/projects/liferay5.0.1/tomcat
-Dcatalina.home=D:/projects/liferay5.0.1/tomcat
-Djava.io.tmpdir=D:/projects/liferay5.0.1/tomcat

Working Directory: D:/projects/liferay5.0.1/tomcat/bin

Click on the JRE tab and make sure the JRE you installed earlier (JDK 5 installation) is selected:

Click on the Classpath tab. Remove the "Invalid path" entry and the bootstrap.jar from User Entries so that only the JRE is left. Then, click on the User Entries tree, then click on the "Add External JARs..." button.

Navigate to D:\projects\liferay\tomcat\bin\boostrap.jar and select it with the "Open" button

Click on the Source tab and click on the "Add..." button. Choose "Java Project" and add the portal project so you can have the source to debug through as well.

Finally, in case of using a non-English environment, it may be a good idea to go to the Common tab and force the console encoding be UTF-8 instead of the default one. This is likely to make more console error messages readable.

Click on "Apply" and "Debug" to see the portal start up! Now you can set break points and step through your code.

Similarly, you can choose "Run..." instead of "Debug" if you just want to run Tomcat.

If you have problems running Tomcat from within Eclipse, a suggestion is to delete the Tomcat application from with the Run dialog and create a new Java Application from scratch with all of the above information.

Portal Configuration #

The whole of portal configuration is beyond the scope of this article. However, you can start with the signing on as the admin and looking through the administrative tools.

Signing in with the test@liferay.com user, password test, will be signing on as the Omni Admin. After signon, navigate to the "My Community" community's private page to see some of the admin portlets that are used to configure the portal as well as administer users and permissions.

This area may be expanded to include how to set up communities, users, basic permissions, and default portal settings.

Known Issues in 5.0.1 RC #

LEP-5693 #

You will not be able to deploy your ext-impl/src/portal-ext.properties in 5.0.1 RC due to issue http://support.liferay.com/browse/LEP-5693

Must modify ext/build-parent.xml.

Change

 <target name="deploy-properties">
 	<copy todir="${app.server.classes.portal.dir}" overwrite="yes">
 		<fileset dir="ext-impl/classes">
 			<include name="*-ext.properties" />
 		</fileset>
 	</copy>
 </target>

To

 <target name="deploy-properties">
 	<copy todir="${app.server.classes.portal.dir}" overwrite="yes">
 		<fileset dir="ext-impl/src">
 			<include name="*-ext.properties" />
 		</fileset>
 	</copy>
 </target>

Conclusion #

If you have followed all of the steps in this guide, congratulations! You are all set up to be productive and start development in Liferay. Good luck!