Page Comparison

h3. Building and Deploying uPortal

{note}
References to release numbers on this page may be different depending on the version of uPortal you are working with{note{}

h5. 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-5-1}} directory.

h5. 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://ant.apache.org]. Once the archive is downloaded, uncompress it and update the operating system environment such that it is available fromm the standard search path. It is recommended that an {{ANT_HOME}} environment be set, and {{ANT_HOME/bin}} added to the {{PATH}} environment variable.

h5. 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-5-1-quick-start/uPortal_rel-2-5-1/lib}} directory.

{note}
As of the 2.4.\* release all of the necessary external jar files are included in the lib directory as well
{note}
{note}
If using the _uPortal-only_ release you will have to obtain all of the necessary external dependency libraries before attempting to compile _uPortal_.

# First create a directory for downloading the necessary packages, for example {{/usr/local/java}} (unix) or {{C:\usr\local\java}} (Windows).
# 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".
# 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.
# 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.
# 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}}
# 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.

h5. Compiling uPortal

Now your ready to compile _uPortal_. Go to the {{uPortal_rel-2-5-1}} 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.

h5. 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 5.5.9 zip file into the {{/usr/local}} directory will create a directory called {{/usr/local/jakarta-tomcat-5-5-9}} 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 {{server.home}} and {{deploy.home}} properties. Change the value of {{deploy.home}} 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}}}
. Change the value of {{server.home}} such that it points to your Tomcat, i.e. $TOMCAT_HOME. For example:{{deploy.home=/usr/local/jakarta-tomcat-5-5-9/webapps/uPortal}}
{{server.home=/usr/local/jakarta-tomcat-5-5-9/}}
*Note*: if you are working with the quick-start release, the deployment directory is relative to the {{uPortal_rel-5-5-9}} directory ({{../Tomcat-5-5-9/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.