This wiki does not contain official documentation and is currently deprecated and read only. Please try reading the documentation on the Liferay Developer Network, the new site dedicated to Liferay documentation. DISCOVER Build your web site, collaborate with your colleagues, manage your content, and more. DEVELOP Build applications that run inside Liferay, extend the features provided out of the box with Liferay's APIs. DISTRIBUTE Let the world know about your app by publishing it in Liferay's marketplace. PARTICIPATE Become a part of Liferay's community, meet other Liferay users, and get involved in the open source project. Development Environment (Windows)
Table of Contents [-]
The intent of this article is to explain what Liferay Portal is and get Java developers set up, running, and off to productivity as soon as possible on the Windows operating system. It is high level and it not intended to answer in-depth questions. However, there will be details provided on how to install certain files and complete installation tasks that are required.
Liferay in a Nutshell #
Liferay Portal is a web application. In a nutshell, you can think of as the portal as one big servlet. It is a servlet that happens to be a portlet container. The portal source builds this portlet container using the Ant build tool and the JDK.
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. You can use IntelliJ instead of Eclipse, for example, but for the sake of simplicity of this article, we will stick with the below:
JDK 5 #
Download the JDK here: http://java.sun.com/javase/downloads/index jdk5.jsp
What you want is (as of Oct 2007) "JDK 5.0 Update 13". Click on the "Download" button. After accepting the agreement. Choose "Windows Offline Installation, Multi-language".
Ant 1.7 #
Download Ant 1.7 here: http://apache.eu.lucid.dk/ant/binaries/apache-ant-1.7.0-bin.zip
Jikes 1.22 #
Download Jikes 1.22 here: http://downloads.sourceforge.net/jikes/jikes-1.22-1.windows.zip?modtime=1096862035&big mirror=0
Liferay Portal Source #
Download Liferay Portal Source 4.4.2 here: http://downloads.sourceforge.net/lportal/liferay-portal-src-4.4.2.zip
Liferay-Tomcat5.5 Bundle for JDK 5 #
Download the bundle here: http://downloads.sourceforge.net/lportal/liferay-portal-tomcat-5.5-jdk5-4.4.2.zip
The bundle is and 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 #
Download Eclipse 3.3 here: http://www.eclipse.org/downloads/
What you want is Eclipse Classic.
Installation and Setup #
Let's install the files that have been downloaded.
JDK 5 #
When you get to setting the location of the install, switch from the default location to C:\Java\jdk1.5.0_13\
Same goes for the JRE. Change the destination to: C:\Java\jre1.5.0_13\
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 anew System variable. Set JAVA_HOME to "C:\Java\jdk1.5.0_13\"
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 #
Unzip the ant archive to C:\Java\apache-ant-1.7.0 . It should look something like this:
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 anew System variable. Set ANT_HOME to "C:\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 #
Unzip the jikes archive to C:\Java\jikes-1.22 . 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 anew System variable. Set JIKES_HOME to "C:\Java\jikes-1.22"
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:
Liferay-Tomcat5.5 Bundle for JDK 5 #
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.
Explode the archive into an directory of your choice. For this article, we will create a directory: C:\projects\liferay\tomcat
Go to the bin directory and double click startup.bat to start up the bundle. Id 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.
Liferay Portal Source 4.3.3 #
Let's setup the source code so we can set up the EXT environment later, and also as a reference in our development.
Explode the archive into C:\projects\liferay\portal
EXT environment #
The EXT environment is how developers can separate their custom code from the Liferay source code. Liferay recommends developing in the EXT environment because it makes applying patches to bugs and upgrades easier. Essentially, the EXT environment is a layer on top of the source. In the EXT, the source is put into JAR files. When you do a build from EXT, you are creating more JAR files, that are loaded by the class loader after the ones from source.
Let's create an EXT environment from the source we unpacked above.
Create a release.{username}.properties file. Find your username by opening a command prompt and typing "env" and you will see your "username" there.
In this case, I would need to create a file called "release.james.properties". Create one based on your username. Place it in C:\projects\liferay\portal .
In this file add these lines:
## ## Extension Environment ## lp.ext.dir=C:/projects/liferay/ext
Save.
Go to the command prompt and go to C:/projects/liferay/portal . Issue this command
ant clean start build-ext
This will build your ext environment:
Check C:\projects\liferay\ext to see that the directory has been built:
You have created the EXT environment, and this is the place where you will do all development, and from where you will do future deployments.
Deploy EXT #
Now that you have created an EXT directory, let's set it up for deployment.
The first thing you need to do is create a file called app.server.{username}.properties . Similar as with the release.properties above, find your username:
NOTE:
If you´re using Tomcat 6.x it´s necessary to uncomment the following entries in the app.server.properties config file:
app.server.tomcat.version=6.0
app.server.tomcat.dir=${app.server.parent.dir}/tomcat-6.0.16
app.server.tomcat.classes.global.dir=${app.server.tomcat.dir}/lib
app.server.tomcat.lib.endorsed.dir=${app.server.tomcat.dir}/lib/ext
app.server.tomcat.lib.global.dir=${app.server.tomcat.dir}/lib/ext
app.server.tomcat.lib.support.dir=${app.server.tomcat.dir}/lib/ext
app.server.tomcat.support.dir=${app.server.tomcat.dir}/lib/ext
app.server.tomcat.zip.name=liferay-portal-tomcat-6.0-${downloads.version}.zipIn this case the file will be called app.server.james.properties. Create one for yourself based on your username:
In this file, add these lines:
app.server.type=tomcat app.server.tomcat.dir=C:/projects/liferay/tomcat
This tells the Ant build tool what type of app server to deploy to, and where it is located.
Save the file.
After making sure Tomcat is not running, open a command prompt and issue this command:
ant clean deploy
This will clean the files currently on Tomcat, and then do a deployment from the code that is in your EXT.
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. However, it is good idea to keep it around as a reference in case you need to develop code based off of the source.
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!
Eclipse 3.3 #
Most people prefer to use some sort of IDE to do development. For simplicity we will demonstrate how to set up the EXT as a project in Eclipse and also how to set up the debugger.
Set up the Java Projects #
Unzip the eclipse archive into: C:\Java\eclipse
Startup eclipse by double clicking on eclipse.exe . Choose C:\projects\liferay as your workspace
Go to the Workbench:
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: C:\projects\liferay\ext
Click "Finish"
Do a similar procedure for the portal source. Call the project "portal" and point to: C:\projects\liferay\portal
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 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=C:/projects/liferay/tomcat/conf/jaas.config -Djava.endorsed.dirs=C:/projects/liferay/tomcat/common/endorsed -Dcatalina.base=C:/projects/liferay/tomcat -Dcatalina.home=C:/projects/liferay/tomcat -Djava.io.tmpdir=C:/projects/liferay/tomcat/temp
Working Directory: C:/projects/liferay/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 C:\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.
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.
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!
