Introduction

This is an update to an earlier article that documented how to install uPortal 2.5.x and uPortal 2.6.x. This will be a new article with much of the same content. While the installation process is similar, there are enough differences that it is worth having two articles covering the differences.

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 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 and Maven build tools and the Java Development Kit. All of this software is available to download on the Internet.

 Please be sure to use a utility other then the built-in Microsoft Windows functionality for unarchiving .zip files.  WinZip, 7-zip or the Java Development Kit jar utility can all successfully unzip the software mentioned in this guide.  Usiing Microsoft Windows File Explorer to unarchive .zip files can result in a corrupt Tomcat or uPortal distribution. 

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 3.1) requires a Java Virtual Machine (JVM) of version 1.5 or greater. The JVM comes with the Java Platform Standard Edition software. Visit Sun's download site and download the most current JDK for your platform. This guide will use the following JDK.

jdk-6u19-windows-i586.exe 

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

C:\Program Files\Java\jdk1.6.0_19 

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.6.0_19 

Environment variables on Windows XP can be set by doing the following

1. Right-click on the My Computer icon and select Properties.
2. Select the Advanced tab.
3. Click the Environment Variables button.
4. Use the New and Edit buttons in the System Variables section.

After the JAVA_HOME environment variable is created you will need to update the Path environment variable. The following text should be ADDED to the beginning of the Path environment variable.

%JAVA_HOME%\bin;<existing_path> 

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_10.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:\portal\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 Apache. 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.1-bin.zip file unzip the into the C:\portal directory. You should now have this directory containing Ant:

C:\portal\apache-ant-1.7.1\ 

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

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

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/.

Maven

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

http://maven.apache.org/ 

Once you have the apache-maven-2.2.1-bin.zip file unzip the into the C:\portal directory. You should now have this directory containing Maven:

C:\portal\apache-maven-2.2.1 

Next, we need to create two environment variables specifying the location of the Maven installation:

MAVEN_HOME = C:\portal\apache-maven-2.2.1 M2_HOME = C:\portal\apache-maven-2.2.1 

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

PATH=<existing_path>;%MAVEN_HOME%\bin 

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

mvn -version 

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

Web Container

Before we can install uPortal 3.1, we must have a servlet 2.5 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: (note: uPortal 3.1 requires Tomcat 6.x and will not run with Tomcat 5.5.x or earlier)

http://tomcat.apache.org/ 

Once you have the apache-tomcat-6.0.26.zip file unzip the file into the C:\portal directory. You should now have this directory containing Tomcat:

C:\portal\apache-tomcat-6.0.26\ 

Now, we need to configure Tomcat to work with uPortal. Locate the following file:

C:\portal\apache-tomcat-6.0.26\conf\catalina.properties 

Find the shared.loader property and set the value as follows:

shared.loader=${catalina.base}/shared/classes,${catalina.base}/shared/lib/*.jar 

Next, locate the file:

C:\portal\apache-tomcat-6.0.26\conf\server.xml 

Find the <Connector> element for port 8080 and modify the element to include the emptySessionPath="true" attribute as follows:

    <Connector port="8080" protocol="HTTP/1.1"                 emptySessionPath="true"                connectionTimeout="20000"                 redirectPort="8443" ></Connector> 

The default uPortal installation requires Tomcat to use a little bit more PermGen memory then the default JVM configuration specifies. To change this, a new environment variable must be set to allow Tomcat to use more PermGen memory if needed. Set the JAVA_OPTS environment variable:

JAVA_OPTS="-XX:MaxPermSize=192m" 

Last, we will create desktop shortcuts to the batch files that start and stop Tomcat. These batch files are located at:

C:\portal\apache-tomcat-6.0.26\bin\startup.bat C:\portal\apache-tomcat-6.0.26\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, the Ant and Maven build tools 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-3.2.1.tar.gz file, unarchive the file into the C:\portal directory. You should now have this directory containing the uPortal source code:

C:\portal\uPortal-3.2.1\ 

Now, we need to make uPortal aware of the specific database, database driver, and servlet container that we are using. First create a new file by copying the build.properties.sample file to build.properties

copy C:\portal\uPortal-3.2.1\build.properties.sample C:\portal\uPortal-3.2.1\build.properties 

Now edit this new file and find the server.home property and set the value as follows:

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

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

C:\portal\uPortal-3.2.1\uportal-impl\src\main\resources\properties\rdbm.properties 

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

 hibernate.connection.driver_class=org.hsqldb.jdbcDriver hibernate.connection.url=jdbc:hsqldb:hsql://localhost:8887 hibernate.connection.username=sa hibernate.connection.password= hibernate.dialect=org.hibernate.dialect.HSQLDialect 

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

Before you can build uPortal you will need to specify which jdbc driver file you intend to use. To specify the jdbc driver, find the pom.xml file in the base uPortal-3.2.1 directory. Open this file up and modify the following lines to specify your driver configuration.

         <!-- The JDBC Driver used by uPortal --><!-- The JDBC Driver used by uPortal -->         &amp;amp;amp;lt;jdbc.groupId&amp;amp;amp;gt;hsqldb&amp;amp;amp;lt;/jdbc.groupId&amp;amp;amp;gt;         &amp;amp;amp;lt;jdbc.artifactId&amp;amp;amp;gt;hsqldb&amp;amp;amp;lt;/jdbc.artifactId&amp;amp;amp;gt;         &amp;amp;amp;lt;jdbc.version&amp;amp;amp;gt;${hsqldb.version}&amp;amp;amp;lt;/jdbc.version&amp;amp;amp;gt; 

The uPortal manual contains configuration instructions for PostgreSQL, MySQL, Oracle, HSQLDB and Microsoft SQL Server. Important: if you are using Oracle or Microsoft SQL Server there is an additional step required to install the JDBC driver to your local maven repository.

Now it is time build uPortal and load the database with an initial set of uPortal data (users, channels, layout fragments, etc). Make sure the database is up and running (see HSQLDB section above). 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 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.

---- Cris J H