Introduction

The purpose of this document is to provide step-by-step setup instructions for a uPortal development environment for use in developing Portlets. The instructions will be geared towards users of the Microsoft Windows XP platform, but the concepts should be applicable for other operating systems including UNIX.

The development environment makes use of uPortal sources, the Tomcat servlet container, the HSQLDB database, the Ant build tool, and the Java Development Kit. All of this software is open source and available for download on the Internet.

Installation Directory

To get started, create a directory that will be used to install java software that needs to be unzipped somewhere on your computer. The choice of directory name is arbitrary, but it is advisable to choose a name without spaces as spaces sometimes cause poorly written programs to break. This document will use the following directory name:

C:\portal

Java Development Kit

uPortal (release 2.6), being a java web application, requires a Java Virtual Machine (JVM) of version 1.5 or greater. The JVM comes with the Java 2 Platform Standard Edition software. Visit Sun's download site http://java.sun.com/javase/downloads/index.jsp.

And download the most current JDK 5.0 update for your platform.

Software/JDK/jdk-1_5_0_12-windows-i586-p.exe

Double-click this file to begin the installation process. Accept the default choices for each prompt. When finished, you should have the J2SE installed on your machine in the following directory:

C:\Program Files\Java\jdk1.5.0_12

Some java applications require an environment variable named JAVA_HOME to be set with the value equal to the location of the java installation directory. To finish the installation, please create the following environment variable:

JAVA_HOME = C:\Program Files\Java\jdk1.5.0_12

To make sure the installation was successful, open a command prompt and type:

java -version

The system should respond with information about the J2SE installation. For more information about J2SE, please visit http://java.sun.com/javase/.

Relational Database

The default implementation of uPortal requires a relational database and corresponding JDBC driver to read and write portal data. For production, most people use proven database products such as PostgreSQL, Oracle, Sybase, Microsoft SQL Server, and DB2. In class, we will be using a free, open-source, java-based relational database called Hypersonic SQL (HSQLDB). To install HSQLDB, please download the HSQLDB distribution from the HSQLDB web site at:

http://www.hsqldb.org/

Once you have the hsqldb_1_8_0_7.zip file unzip the file into the C:\portal directory:

You should now have this directory containing HSQLDB:

C:\portal\hsqldb

Next, create a desktop shortcut to the batch file that starts HSQL, supplying the command line with arguments that define the name of the database and the port on which the database should listen. The batch file is located at

C:\portal\hsqldb\demo\runServer.bat

Create a shortcut to this file and place it on the Windows desktop. Rename the shortcut Start HSQLDB. We will now edit the properties of the shortcut by right-clicking on the shortcut and selecting Properties. Add command line options for the port and database name to the Target as follows:

C:\portal\hsqldb\demo\runServer.bat -port 8887 -database uPortal

Also, make sure the Start in field contains:

C:\Training\hsqldb\demo

The port can actually be any unused port and the database name can be anything you want. Now you can start the database by double-clicking the Start HSQLDB shortcut. The following window should open indicating that the database is running:

You can safely minimize this window. Closing this window will shut down HSQLDB. The recommended way to shut down HSQLDB is to press Ctrl+C while this window is active.

For more information about HSQLDB, visit http://www.hsqldb.org/.

Ant

The next piece to install is the Ant build tool from the Apache Jakarta project. To install Ant, please download the Ant distribution from the Ant web site at:

http://ant.apache.org/

Once you have the apache-ant-1.7.0-bin.zip file unzip the into the C:\portal directory:

You should now have this directory containing Ant:

C:\portal\apache-ant-1.7.0

Next, we need to create an environment variable specifying the location of the Ant installation:

ANT_HOME = C:\portal\apache-ant-1.7.0

We would like to be able to invoke Ant on the command line from any directory. To make this possible, modify the PATH environment variable, appending the location of the Ant batch file:

PATH=<existing_path>;%ANT_HOME%\bin

To make sure Ant is properly installed, open a new command prompt and type:

ant -version

The system should respond with information about the ant installation. For more information about J2SE, please visit http://ant.apache.org/.

Web Container

Before we can install uPortal, we must have a servlet 2.3 or greater compliant web container available. A web container is a JEE server component that enables access to servlets and JSP pages. There are many to choose from including WebLogic (BEA), WebSphere (IBM), JRun (Macromedia), Resin (Caucho), Jetty (Mortbay), and Tomcat (Apache). Tomcat is the easiest implementation to use with uPortal.

To install Tomcat, please download the Tomcat distribution from the Tomcat web site at:

http://tomcat.apache.org/

Once you have the apache-tomcat-5.5.23.zip file unzip the file into the C:\portal directory:

You should now have this directory containing Tomcat:

C:\portal\apache-tomcat-5.5.23

Next, we will create desktop shortcuts to the batch files that start and stop Tomcat. The batch files are located at

C:\portal\apache-tomcat-5.5.23\bin\startup.bat
C:\portal\apache-tomcat-5.5.23\bin\shutdown.bat

Create shortcuts to these files and place them on the Windows desktop. Rename the shortcuts Start Tomcat and Stop Tomcat. To make sure Tomcat has been installed correctly and the shortcuts are functioning, double-click the Start Tomcat shortcut. A console window should open with a few startup messages from Tomcat. In a web browser, enter the URL

http://localhost:8080/

This should bring up the Tomcat home page indicating that Tomcat is running successfully on your machine:
To shutdown Tomcat, simply double-click the Stop Tomcat shortcut on your desktop.

uPortal

Now that we have a Java Virtual Machine, a relational database and driver, a servlet container, and the Ant build tool installed on our machine, we can install uPortal. To install uPortal, please download the uPortal distribution from the uPortal web site at:

http://www.uportal.org/

Once you have the uPortal_rel-2-6-0-RC1.zip file unzip the file into the C:\portal directory:

You should now have this directory containing uPortal:

C:\portal\uPortal_rel-2-6-0-RC1

Now, we need to make uPortal aware of the specific database, database driver, and servlet container that we are using. First open the following file for edit:

C:\portal\uPortal_rel-2-6-0-RC1\build.properties

Find the server.home property and set the value as follows:

server.home=C:/portal/apache-tomcat-5.5.23

Note: If you want to deploy uPortal into a servlet context other than uPortal, then find and modify the deploy.home property as well. It is not necessary to modify deploy.home.

To use a database besides HSQLDB you must edit the following file::

C:\portal\uPortal_rel-2-6-0-RC1\properties\rdbm.properties

For example to use HSQLDB you would set the JDBC information as follows:

Make sure all other database configurations besides the one you are using are commented out.

Before you run the ant command you will need to copy the jdbc driver file to the uPortal container-common library directory. This ensures that it is deployed to the correct location in tomcat. If you are using the HSQLDB documented in this guide, type the following at a command prompt:

copy C:\portal\hsqldb\lib\hsqldb.jar C:\portal\uPortal_rel-2-6-0-RC1\lib\container-common

Also make sure that any other version of the your database jdbc driver file is deleted from the C:\portal\uPortal_rel-2-6-0-RC1\lib\container-common directory to avoid any conflicts. For example, uPortal 2.6.0-RC1 contained an old version of the HSQLDB driver that must be deleted with the following command:

del c:\portal\uPortal_rel-2-6-0-RC1\lib\container-common\hsqldb-1.7.2.4.jar

Now it is time to load the database with an initial set of uPortal data (users, channels, layout fragments, etc). Make sure the database is up and running (see section 4). Open a command prompt and change directories to the uPortal installation directory. From this directory, enter the Ant command to load the database and deploy the portal:

ant initportal

The output should show information about the database and messages indicating that the database tables have been dropped, created, and populated. There should also be information about the publishing of channels and layout fragments.

You should now be able to access the portal by starting Tomcat (restart Tomcat if it was not already running) and entering the following URL into a browser:

http://localhost:8080/uPortal/

If you see the default uPortal home page in your browser window, you have successfully set up uPortal.

You can log into the portal with the following username/password combinations: demo/demo, student/student, staff/staff, faculty/faculty, and admin/admin.