JA-SIG Home

About uPortal

Documentation

Getting Started

Developers

Implementors

Users

Background

Release

Meeting Minutes

Building and Deploying uPortal

Overview

Compiling and deploying uPortal is managed using the Ant build tool. Ant uses a file called build.xml for managing what is compiled and copies all necessary files into the uPortal context. The uPortal context can then be deployed as a complete web application running in a servlet container such as Tomcat or IBM Websphere. The build.xml file uses several properties defined in a file called build.properties. Both of these files can be found in the uPortal_rel-2-1-3 directory.

Obtaining the Ant build tool

If using the uPortal-only release you will need to download the Ant build tool. It is available from http://jakarta.apache.org/ant. Once the archive is downloaded, uncompress it and update the operating system environment such that it is available form the standard search path. It is recommended that an ANT_HOME environment be set, and ANT_HOME/bin added to the PATH environment variable.

Obtaining external dependency libraries

If using the quick-start release, all of the external dependency libraries (jar files) are included, and can be found in uPortal_2-1-3-quick-start/uPortal_rel-2-1-3/lib directory.

If using the uPortal-only release you will have to obtain all of the necessary external dependency libraries before attempting to compile uPortal.

1. First create a directory for downloading the necessary packages, for example /usr/local/java (unix) or C:\usr\local\java (Windows).
2. Refer to the build.xml for a complete list of all packages you will need to obtain. Look for the comment section labeled "External Dependencies".
3. Download each of the packages from the location specifed. For example, the xalan jar files are available from http://xml.apache.org/xalan-j. It is recommended that the required version specified in the build.xml file be downloaded.
4. Each package typically contains jar files, documentation, and other related files in an compressed archive (zip, gzipped tar file). Uncompress each of the packages into the download directory. Most of the packages will created a subdirectory for the package with lib, doc, and other directories within that directory.
5. Edit the build.properties file and change the property values to point to the location of all the required jar files.

   For example, change:

   xalan.jar=./lib/xalan.jar
   to
   xalan.jar=/usr/local/java/xalan-j_2_4_0/bin/xalan.jar

6. Note that there are some additional properties in build.properties which may be modified. Leave them alone for now. Typically you should not need to modify the build.xml file at all.

Compiling uPortal

Now your ready to compile uPortal. Go to the uPortal_rel-2-1-3 directory and just type ant. Ant will first create a build directory, then invoke the java compiler and store all of the compiled class files into build/WEB-INF/classes. It will also copy many other files into the build directory including stylesheet files, images, and property files. If everything worked you should see a message which reads:

BUILD SUCCESSFUL

If something went wrong, it is most likely due to Ant being unable to find one or more of the external dependencies. Check the build.properties file and try again.

Deploying uPortal

The Ant build tool also manages the deployment of the uPortal application into a servlet container. It will copy everything that it compiled and stored in the build directory into a directory specified in the build.properties files as deploy.home.

If using the uPortal-only release you will first need to obtain a servlet container. The Tomcat servlet container is recommended. Tomcat can be downloaded from http://jakarta.apache.org/tomcat. Uncompress the archive file to a location where the web application server will run. For example, on Unix, extracting the Tomcat version 4.1.24 zip file into the /usr/local directory will create a directory called /usr/local/jakarta-tomcat-4.1.24 which is usually refered to with an environment variable called TOMCAT_HOME.

Before deploying uPortal you may need to modify the build.properties. Edit the file and find the deploy.home property. Change the value such that it points to the location where uPortal will be deployed. For a Tomcat servlet container that would typically be $TOMCAT_HOME/webapps/{app.name}, for example:

deploy.home=/usr/local/jakarta-tomcat-4.0.4/webapps/uPortal

Note: if you are working with the quick-start release, the deployment directory is relative to the uPortal_rel-2-1-3 directory (../tomcat-4.1.24/webapps/uPortal) and should not be changed.

Now you're ready to deploy uPortal to the servlet container. Simply type "ant deploy" to invoke the "deploy" target. If everything worked correctly you will see a BUILD SUCCESSFULL message.

Known Issues