uPortal 2.x Installation

This document provides installation and configuration information necessary for getting started using uPortal. It will describe the "quick start" and "uPortal only" distributions.

Quick Start or uPortal Only?

UPortal is available either as a "Quick Start" release or as a "uPortal-only" distribution. Both releases are available from the JA-SIG uPortal website in the download section.

Why choose the Quick Start distribution?

The quick-start release distribution is provided for those who want to get familiar with uPortal quickly and easily, without having to compile and deploy code, and without having to set up a database or servlet engine.

For those that only require an installation of uPortal for demonstration or evaluation purposes, or if one wants to do some simple channel developement, the quick-start distribution is the best choice. The quick-start distribution contains a copy of the uPortal only distribution which has been configured to run in the quick-start environment.

Why choose the uPortal-only distribution?

This distribution is targeted towards people who would like to install uPortal in a development or production environment. It contains uPortal source code and properties files, but not a servlet container, directory, or relational database, which are required.

For those that want to create a production version of uPortal, develop uPortal channels, or have other web applications which will run on the same server the uPortal only distribution may be the best choice.

Quick Start Distribution

What is included?

The quick start distribution is downloaded as a zip file which extracts to directory called uPortal_2_1_3-quick-start . The directory contains the following...

uPortal 2.1.3 - directory ( uPortal_rel-2.1.3 ) containing the uPortal source code, stylesheets, and other required files (essentially, the uPortal-only distibution).
Tomcat 4.1.24 - a directory ( Tomcat_4-1-24 ) containing the Tomcat servlet container with the uPortal context preloaded.
Ant 1-5-3 - a directory ( Ant_1-5-3- ) containing a distribution of the Ant build tool.
HypersonicSQL 1.6.1 - a directory (HSQL_1-6-1) containing a distribution of the HypersonicSQL database engine. The database is preloaded with the data and tables required by uPortal.

...and the following files

build.xml - build file for use by Ant.
fix-unix-modes.sh - a unix script for setting file permissions.
ant.sh, ant.bat, ant - scripts and windows batch file for invoking the Ant built tool.

What do you need to know?

Installation of the quick-start release requires basic knowledge of the operation system upon which it will be installed. If any customization or configuration is desired, knowledge of the Jakarta-Ant build tool, Tomcat servlet container environment, and basic SQL database skills are useful.

Requirements

The Java Development Kit (JDK) version 1.3 or higher must be installed.
JAVA_HOME environment variable must be set.
Nothing else should be running on port 8080 and 8887.

Starting uPortal

The quick-start release is started using the Ant build tool and a filed called build.xml which contains a set of “targets” to start the SQL database and Tomcat servlet container. The release contains a script and batch file for running Ant in either a Windows (ant.bat) or Unix (ant.sh) environment.

Windows:
```
./ant target
```
Unix:
```
./ant.sh target
```

Starting the Database

The HypersonicSQL database is preloaded with the tables required for uPortal and must be started using Ant . The hsql target starts the database server which loads the files located in the HSQL_1-6-1/demo directory. To start up the database use one of the following:

Windows:
```
 ant hsql 
```
Unix:
```
./ant.sh hsql
```

Starting Tomcat

The quick-start release includes the Tomcat servlet container with uPortal context preloaded. Tomcat must be started using Ant . The tomcatstart target starts Tomcat using one of the following:

Windows:
```
ant tomcatstart
```
Note:

Starting Tomcat in windows opens up a separate window to display the output of the Tomcat application.
Unix:
```
./ant.sh tomcatstart
```

Running uPortal

Once the HypersonicSQL database and Tomcat are started you can access uPortal with your browser by entering the following URL: http://localhost:8080/uPortal2

You can login to uPortal using one of the following username/password combinations:

   demo/demo
   student/student
   staff/staff
   faculty/faculty
   developer/developer

Stopping Tomcat

The Tomcat servlet engine can be shutdown using Ant. The tomcatstop target stops Tomcat using one of the following:

Windows:
```
ant tomcatstop
```
Unix:
```
./ant.sh tomcatstop
```

Customization

Customization of uPortal is described in the uPortal-only section below.

uPortal Only Distribution

What is included?

The uPortal-only distribution is downloaded as a zip file which extracts to directory called uPortal_rel-2-1-3.zip . The directory contains the following...

docs - directory containing documentation about uPortal.
src - directory hierarchy containing the source code for uPortal.
lib - directory containing necessary jar files for the Java API's used by uPortal.
webpages - hierarchy which contains stylesheets, image files, java servlet pages, and other necessary files for uPortal.
properties - directory which contains properties and configuration files used by uPortal.

...and the following files

build.xml - build file for use by Ant.
build.properies - properties file for use by Ant.

What do you need to know?

Use of this distribution requires knowledge of J2EE environments and the Ant tool from the Apache Jakarta project.

Requirements

The Java Development Kit (JDK) version 1.3 or higher must be installed.
JAVA_HOME environment variable must be set.
The Jakarta-Ant build tool (version 1.5.3 or later).
A web application environment such as Tomcat or IBM Websphere
An SQL database such as HypersonicSQL, Oracle, or PostgreSQL

Setting up a Web Application Environment

The uPortal web application requires a web application enviroment such as Tomcat or IBM Webshere . If you already have a web application environment installed on a server, the uPortal context can just be deployed to that environment, otherwise you will have to install one. The build files for uPortal have been set up such that it can be easily deployed into Tomcat. The Jakarta-Tomcat servlet container can be downloaded from: http://jakarta.apache.org/tomcat/index.html . Version 4.1.24 is recommended.

Compiling and Deploying uPortal

Compiling and deploying uPortal is managed using the Jakarta Ant build environment. It is highly recommended that anyone implementing uPortal or developing channels become familiar with the Ant build tool. Documentation for Ant is available at Jakarta-Ant web site

For detailed instructions on how to compile and deploy uPortal go to the documentation page at:

Building uPortal.

Setting up A Database

The uPortal system can be deployed such that a database from several different vendors may be used. Installation and configuration information about databases can be found in the:

Database Installation and Configuration Document

Issues and known problems

JDK version issues

Some people have encountered problems starting up uPortal on systems with newer versions of the JDK. Typically it resultes in a NoClassDefFoundError exception. The solution is to recompile uPortal with the JDK which resides on the system. Go to the build directory (uPortal_rel-2-1-3) and type "ant deploy" to recompile uPortal.

Proxy/Firewall issues

If uPortal is installed on a system which requires a proxy server for access to remote web sites, the web application server will have to be configured to use the proxy server. Information on how to set up uPortal with a proxy server can be found in the following document:

Configuring uPortal to use a Proxy Server

JA-SIG Home