Using the uPortal-only Distribution

Owned by John Fereira
Last updated: May 30, 2007 by Andrew PetroVersion comment

Using the uPortal Only Distribution

The version numbers indicated below are from the version of the quickstart distribution as of the last time this page was edited. The version numbers will most likely be diffrent depending on which version you have downloaded

 

 

What is included?

The uPortal-only distribution is downloaded as a zip file which extracts to directory called uPortal_rel-2-5-1.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.4 or higher must be installed. For version 2.5.1 and later JDK 1.5 is preferred. JDK version 1.4 is preferred for earlier versions of uPortal.
  • JAVA_HOME environment variable must be set.
  • The Jakarta-Ant build tool (version 1.6.2 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 5.5.9 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

Do not blindly run the ant build against a production database.  There are Ant targets in this build
which will initialize the database for uPortal.  Before running the ant build, take care that the
/properties/rdbm.properties actually describes the database against which you intend to be working.

Do not blindly run the ant build on a production system.  There are Ant targets in this build which
clean build directories and publish the uPortal build into a configured Tomcat instance.  Take care not to
accidentally run the build such that it overwrites a uPortal instance you care about.  Locations affected by
the build are declared in build.properties.

Backup your work before running builds.

 

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

Compiling uPortal.

Initial Deployment

You must run the initportal target before uPortal is started the first time.
This target will take care of compiling, deploying, database population and
other initial tasks. Running initportal again is similiar to hitting a reset
button on the portal. Any saved configuration in the portal is lost and a clean
version of the portal is configured.

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 on the:

05 Database page.

Complete the Installation

Once you have compiled and deployed uPortal and setup a database for it to utilize, you still need to publish the channel fragments and internationalize the database. This can be done in one step by issuing the `ant initportal` command. Once this command completes without errors, your uPortal instance should be fully functional.

Logging

The ant build copies /properties/Logger.properties to the root of the classes directory so that the resulting log4j.properties file will be available on the classpath for Commons Logging / log4j to find. You'll need to either change that configuration in Logger.properties before the build or to change it in /WEB-INF/classes/ afterwards. You can configure the logging level, where the file should be, or even choose a different logging approach (log via XML to a ChainSaw instance, say).

The Logger.properties file comes configured such that the portal.log file is written in a directory relative to where to web application server was started. You may wish to modify the following line such that it references an absolute file page:

log4j.appender.R.File=portal.log

 

Issues and known problems

Library Dependencies

IMPORTANT Instructions for JDK1.4
uPortal uses the JAXP 1.3 compatability libraries for its XML APIs. The JAXP
libraries need to be copied into the endorsed library locations for the JRE
and Tomcat. Instructions can be found at JAXP 1.3 compatibilty.

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