Click for other Manual Versions

uPortal 4.0 Manual

Skip to end of metadata
Go to start of metadata

Quickstart

Just want to try out uPortal? uPortal can be downloaded pre-packaged with Apache Tomcat, Apache Ant, and Maven. This installation option is best suited for evaluation purposes only.  Skip this section and see the Quickstart section in Downloading uPortal.

Installing Apache Tomcat

Icon

Apache Tomcat is the recommended servlet container to use with uPortal 4. While uPortal 4 requires a Servlet 2.5-compatible servlet container and another servlet container may be used, most uPortal implementers deploy to Apache Tomcat. Choosing Tomcat 6.x or 7.x will likely allow uPortal adopters to get the best advice from the community.

Tomcat 7.0.47 incompatibility

Icon

There's an issue with uPortal logout / session invalidation in Tomcat 7.0.47, which is the very latest Tomcat 7 as of this writing. If you want to be running recent Tomcat 7, try Tomcat 7.0.42 instead.

Linux/Unix Installation

1. Download Apache Tomcat 6.x or Apache Tomcat 7.x

2. Untar the package as follows:

tar -zxvf apache-tomcat-6.0.26.tar.gz

3.Optionally rename your install to something more meaningful:

mv apache-tomcat-6.0.26 uportal-tomcat

4.Set your environment variables:

export JAVA_HOME=/path/to/your/java
export TOMCAT_HOME=/path/to/your/tomcat

5.Test your Tomcat installation

a. First, start Tomcat

$TOMCAT_HOME/bin/startup.sh

b. Go to http://localhost:8080/

You should see the Apache Tomcat Welcome screen

c. Shutdown Tomcat

TOMCAT_HOME/bin/shutdown.sh
Windows Installation

1. Download Apache Tomcat 6.x or Apache Tomcat 7.x for Windows

2. Unzip the download into a suitable directory. For example, you may unzip the file into the C:\ directory. This will create a directory like C:\apache-tomcat-6.x containing your Tomcat files.

3. You will need to create two environment variables CATALINA_HOME and JAVA_HOME

 CATALINA_HOME : C:\apache-tomcat-6.x
 JAVA_HOME : C:\Program Files\Java\jdk1.x

For Windows (different versions may vary) you can create these environment variables by doing the following: right-click 'My Computer' select properties and then the Advanced tab. Then click Environment Variables and under System variables click New. From here, you can enter the name and value for CATALINA_HOME and again for JAVA_HOME if it's not already created.

4. Start Tomcat. Try starting up Tomcat by running the C:\apache-tomcat-6.x\bin\startup.bat batch file. Point your browser to http://localhost:8080 and you should see the default Tomcat home page (see above image). To shutdown the server run C:\apache-tomcat-6.x\bin\shutdown.bat batch file.

Configuring Tomcat for uPortal 

Shared Libraries

uPortal places libraries in CATALINA_BASE/shared/lib The default Tomcat 6 and Tomcat 7 download does not enable libraries to be loaded from this directory.

  1. To resolve this you must edit CATALINA_BASE/conf/catalina.properties and change the line that begins "shared.loader=" to the following:
Enabling shared libraries in CATALINA_BASE/conf/catalina.properties
shared.loader=${catalina.base}/shared/lib/*.jar

Warning!

Icon

Be absolutely certain the shared.loader property is configured exactly as shown. An extra space character at the end of the line can prevent it from working as intended, which is very difficult to troubleshoot.

Shared Sessions

Jasig portlets, as well as many other popular JSR-168 and JSR-286 portlets, rely on the ability to share user session data between the portal web application and portlet applications. To enable this feature:

  1. Tomcat 6.0: add the emptySessionPath="true" parameter to the in-use connector (configured in Tomcat in CATALINA_BASE/conf/server.xml).
  2. Tomcat 7.0 (for uPortal 4.0.10+ or 4.1+):  add the sessionCookiePath="/" to CATALINA_BASE/conf/context.xml.
Example Tomcat 6.0 Connector Configuration
Example Tomcat 7.0 Connector Configuration

JVM Heap Configuration

uPortal requires a larger than standard PermGen space and more heap than may be allocated by default. A good conservative set of heap settings are -XX:MaxPermSize=384m -Xmx1024m. To add these, create a file called either setenv.sh (Linux/Mac) or setenv.bat (Windows) in your CATALINA_HOME/bin directory and add the configuration as follows:

setenv.sh or setenv.bat

 

Tomcat 7 parallel startup (optional)

 

Tomcat 7.0.23+ can be configured to have multiple webapps start up in parallel, reducing server startup time.  Set the startStopThreads attribute of a Host to a value greater than one.  See http://wiki.apache.org/tomcat/HowTo/FasterStartUp for more details and other suggestions.

GZipping HTML (optional)

Browser-side performance may be improved somewhat by GZip-ping downloaded content where appropriate. uPortal 4 already GZips CSS and JavaScript. uPortal does not, however, GZip the uPortal page itself.

GZipping of HTML content can be performed via Tomcat. To enable this functionality, set compression="on" in the in-use Tomcat connector, and set the list of compressable mime types. More information about this feature can be found in the Tomcat configuration page.

Example GZip Configuration

Further Tomcat Configurations

JVM settings

Example Installations

Having problems with these instructions?

Please send us feedback at uportal-user@lists.jasig.org