General Idea
Liferay is a web portal system. Liferay is JSR 168 compliant. Liferay is implemented as a java compliant web application. Liferay is typically installed as a root context in Tomcat. More popular installation packages of Liferay come with a bundled tomcat. Although that is technically true, the download instead contains a tomcat with a preinstalled Liferay as its root context.
Installing Liferay involves unzipping this tomcat and starting the tomcat from the tomcat bin directory. The only real prerequisite is that there is a jdk installed and java_home set. Subsequently you can see Liferay in action by going to
http://localhost:8080
The default view of this site is for users or guests that haven't logged in yet. This is the public face of the portal web site. Liferay comes with a built in test user for testing the sign in process. One can also sign up for an account. Once installed the portal can be configured using its internal portlets and themes.
The out-of-the box Liferay comes with hypersonic sql. Nevertheless it is highly advisable to use mysql as soon as possible. The main issue you will run into otherwise is that you may not find good tools to manipulate the database.
This document will cover the basic mysql installation as well and also running command line prompt for mysql and using the mysql tools for such things as creating the database etc.
Prerequisites
jdk 1.5
jikes 1.2
Ant 1.6.5
mysql (latest)
mysql tools (latest)
eclipse 3.2
jdk is self explanatory. I haven't tested with previous versions of jdk to see if that would work as well. But considering you are going to be using tomcat 5.x and eclipse 3.2, you may want to use jdk 1.5.
Liferay uses ibm's jikes compiler for faster performance. Everything should work with out jikes as well, although I haven't tested.
Ant build files are extensively used through out Liferay. You may not need Ant for your initial installation but you will need it sooner or later. The first use of Ant is to build something called an "extension" environment. It is too involved to explain in the installation document, but there is enough need to go ahead and install ant.
I strongly recommend installing mysql and mysql tools right away. If you have mysql installed already then you are gold. I will explain how to tell Liferay to make use of your already installed mysql.
Eclipse is used for a number of things. For starters you can use it just to examine the tomcat/Liferay installation directory and make any changes that are needed. You will use eclipse for developing themes, editing jsp files, writing portlets, editing html files, and debugging Liferay if need be. It is always good to get the latest eclipse that you can grab. If you already have a copy of eclipse I am sure you could use that eclipse.
home and path settings
To successfully start the tomcat/Liferay you need to set the following environment variables
java_home
jikes_home
ant_home
You also need to add the following paths to your path variables
java_home\bin
jikes_home\bin
ant_home\bin
You can have these settings as system level settings or as settings for a given command line prompt. Because all build and startup scripts need these variables defined.
Some times adding these as system level variables can cause conflicts. I usually prefer just command line option. But while using eclipse to run some of these build or start scripts the system variables may be the only option.
Changing command line settings
As you will have to watch console messages from Liferay as it starts, it is better to change the console window properties as follows
Screen buffer size width: 100, height: 9999 Window size width: 100
Install tools and set home and path variables
Using the download pointers section download and unzip jdk, jikes, and ant. Setup the home and path variables for each.
Install or unzip Liferay
While working with Liferay it may be useful to have a directory structure as below.
Liferay-portal \tomcat \ext \portal
Liferay-portal will represent a root directory to contain all life related sub directories. The "tomcat" sub directory will contain the Liferay portal run time. The "ext" sub directory will contain the development environment for extending Liferay with your own portlets, themes etc. The "portal" sub directory will contain the source code of Liferay Portal. All three can be opened up into eclipse as projects. Make sure to open the "tomcat" directory as a "plain" project that way eclipse will not attempt any compiles etc.
To install Liferay, download the tomcat/Liferay distribution and unzip into the "tomcat" sub directory. Make sure to adjust the unpacking depending on whether the package already contains the "tomcat" sub directory. For instance in my case the zip file does not have the "tomcat" as the base. So I have created a sub directory called "tomcat" before unpacking. At this point you will not have the "ext" or the "portal" sub directories as part of the installation. I will cover them in a separate document.
Starting up Liferay
Once the home and enviornment variables are in place and Liferay unzipped as above you can start Liferay tomcat by running
tomcat\bin\startup
It is worthwhile studying tomcat/bin/startup.bat and tomcat/bin/catalina.bat to tune them to your specific needs. For example you can these batch files to set the home and path variables instead of setting them at the global level. You can also use these to have tomcat run in the same window so that you can look at the console even after tomcat exits either due to exception or user explicitly stopping it.
It is worthwhile to see the starting pattern of Liferay on the console.
Download pointers
The following lists the download pointers for each technology
Installing mysql and mysql tools
Go to mysql.com and download the following two files
mysql-essential-5.0.27-win32.msi
mysql-gui-tools-5.0-r5-win32.msi
The first is the mysql server and the second is a set of gui tools to work with mysql. While installing the sql server you will need to give a root userid and password. In addition if you have ip firewalls mysql installation will pause to allow you to fix the permissions for the ip ports. So be prepared to know how your particular firewall like Norton needs to be configured for this sort of thing.
Basic things you will need to know for Liferay in mysql
Create a database (training)
Import a script that populates the database
See or list your databases
See or list your tables
run a query against a table
Running a mysql command line application
Open a command line and run
mysql -?
This will list the help options that mysql has.
mysql -uroot -proot -hlocalhost --port=3306 training
The above statement is using a userid of "root" and a password of "root" and a host of "localhost" and a port of 3306. Notice the two dashes for the port.
You can learn more about the command line options here.. You can learn more about the mysql command line utility here.
Simply put though the following will do
mysql -uroot -proot
Once looged in you will have to change to the database you want
use training;
Pleasel note that the following combinations will not work
mysql
mysql -uroot
Butthe following will work
mysql -uroot -p
But this will prompt for the password.
Using mysql tools
You can also use the gui tool that comes with mysql. Using this tool you can see the databases, tables, and be able to run scripts.
Setting up Liferay to use mysql
Two things need to happen for Liferay to use mysql: .list Locate and obtain the scripts for mysql Load mysql database with Liferay script Change configuration so that Liferay will use mysql database instance
Download Liferay scripts file. This is about 15mb. In the download look for a file called portal/portal-mysql.sql. The script does not define a database. This allows the script to create multiple schemas if needed. If we assume this database to be "Liferay-portal:, then the following will do the job:
mysql -uroot -proot
create database lportal;
use lportal;
source portal/portal-mysql.sql;
commit;
This would have imported the necessary ingredients for Liferay.
Resources and virtual hosts in tomcat
The goal here is to define the following resource or a tomcat host where Liferay is installed. The entry will look like
<Resource
name="jdbc/LiferayPool"
auth="Container"
type="javax.sql.DataSource"
driverClassName="org.gjt.mm.mysql.Driver"
url="jdbc:mysql://localhost:3306/lportal?useUnicode=true&characterEncoding=UTF-8"
username="root"
password="root"
maxActive="100"
maxIdle="30"
maxWait="10000"
/>
This section will go in to the file
tomcat/conf/catalina/localhost/ROOT.xml
Liferay References
1. Installing 3.x with tomcat 5/5.x
2. Liferay Portal-Installation and Configuration (updated)
3. Liferay Portal 4.0 - Quick Start Guide
4. Liferay users guide PDF. For this document. The PDF version is much more readable. This document is a good read for understanding liferay data models.
5. Liferay installation category on their wiki
Other References
2. My notes on JSR 168 portlets
5. Tomcat catalina startup file