Home | about | articles | build-install-run-uportal-400

Build, Install, & Run uPortal 4.0.0

Share it now!


This is a a reboot of Cris Holdorph's excellent series of articles on installing earlier versions of uPortal. It includes step-by-step instructions for deploying uPortal and all its dependencies. As you might imagine, several things have changed since the last release of uPortal 3 (version 3.2.4).

Update 2012/11/28

This article was updated for uPortal 4.0.8.


This article is geared toward installation of a local portal, such as you might use to develop portlets that adhere to the 1.0 (JSR-168) -- or new in uPortal 4, 2.0 (JSR-286) -- Java Portlet Specification. This excercise is also a great way to learn the platform in greater depth. Examples and screenshots are given for a Windows platform, but the concepts are applicable to other operating systems, including MacOS and *nix platforms.

The steps covered in this article are also documented online in the uPortal 4.0 Manual. Be sure to check out that fabulous resource! There you will find coverage of more comprehensive installation options, as well as information on more advanced topics like integrating with LDAP, CAS, Shibboleth, and/or Grouper.

Getting started

To get started, create a directory in which we will put all our work.  To prevent possible issues down the road, we will choose a directory (1) with a short, space-free name and (2) at the root of the file system.  File paths with spaces in them (e.g. 'My Documents') can cause poorly-written programs to break.  Also, Windows systems support a limited number of characters (255) in file paths;  since some of the technologies we will be working with contain many nested subfolders, it's best not to tempt fate by adding too many characters at the beginning.

The final name choice is arbitrary, but 'portal' seems sensible.


Java Development Kit (JDK)

uPortal 4 requires Java Development Kit (JDK) version 1.6 Update 21 or later.  (There was a nasty JAXP bug is earier versions of Java that prevents uPortal 4 from building.)  NOTE:  A Java Virtual Machine (JVM) is not sufficient for building and running uPortal;  you need the full JDK, which includes important platform tools like the compiler!

For this tutorial, we will be using the following JDK download (v. 1.6 Update 27):  jdk-6u27-windows-x64.exe

Double-click this file to begin the installation process.  Change the 'Install to:' directory to simply 'C:\jdk1.6.0_27\' (again, it's best to avoid paths with spaces).

Some java applications -- including several we're about to install -- require an environment variable named JAVA_HOME to be set with the value equal to the location of the JDK directory. To finish the installation, please create the following environment variable:

JAVA_HOME = C:\jdk1.6.0_27 

Environment variables on Windows 7 can be set with the following procedure

  1. Right-click on the Computer icon and select Properties
  2. Select the Advanced system settings option (left-hand side)
  3. Click the Environment Variables... button
  4. Use the New... and Edit... buttons in the System variables section

After the JAVA_HOME environment variable is created you will need to update the Path environment variable. The following text should be ADDED to the beginning of the Path environment variable.

%JAVA_HOME%\bin;{existing path}

NOTE: Command windows that were open on your desktop previously will not be affected by these changes; they will need to be closed and re-opened. To make sure the installation was successful, open a command prompt and type:

java -version 

The system should respond with information about the J2SE installation. For more information about J2SE, please visit http://java.sun.com/javase/.

Relational Database (RDBMS)

uPortal requires a relational database and corresponding JDBC driver  to read and write portal data.  In production deployments, most adopters use proven RDBMS platforms such as Oracle, MS SQL Server, PostgreSQL, or MySQL.  For this example, we will be using  a free, open-source, java-based RDBMS called Hypersonic SQL (HSQLDB).  uPortal 4.0.8 (most recent when this article was last updated) comes pre-configured for HSQLDB version 2.2.9, so that's the version we'll use in this example.  You can download version 2.2.9 from the Hypersonic website:


Once you have the hsqldb-2.2.4.zipfile, unzip it into the C:\portaldirectory. You should now have this directory containing HSQLDB:


Next, create a desktop shortcut to the batch file that starts HSQL. The batch file is located at:


Create a shortcut to this file and place it on the Windows desktop. Rename the shortcut Start HSQLDB. Next, right-click on the shortcut and select Properties. Make sure the Start in:field contains:

Now we will tell HSQLDB about the database we intend to use with uPortal. Navigate to the C:\portal\hsqldb-2.2.4\hsqldb\datadirectory and create a new file called server.properties within it. Put the following text in that file and save it:

Now you can start the database by double-clicking the Start HSQLDB shortcut on your desktop. The following window should open indicating that the database is running:

You can safely minimize this window. Closing this window will shut down HSQLDB. The recommended way to shut down HSQLDB is to press Ctrl+C while this window is active.

For more information about HSQLDB, visit http://www.hsqldb.org/.


The next prerequisite we will install is Apache Ant, a popular and mature Java build tool. uPortal 4 .0.0 requires Ant version 1.8.2, which can be obtained from the Ant downloads page. Once you have the apache-ant-1.8.2-bin.zipfile, unzip it into your C:\portaldirectory. You should now have the following directory, which contains Ant:


Next, we need to create an environment variable specifying the location of the Ant installation (refer to instructions for JAVA_HOMEabove):

ANT_HOME = C:\portal\apache-ant-1.8.2 

We need to be able to invoke Ant on the command line from anywhere in the file system. To make this possible, modify the Pathenvironment variable once more, appending the location of the ant.bat file:

PATH = {existing path};%ANT_HOME%\bin 

Test your Ant installation by invoking the following command (REMINDER: always open a new command prompt after changing environment variables):

ant -version 

The system should respond with information about your ant installation.


The next prerequisite is Apache Maven, another build tool from Apache.  "But wait," you astutely observe, "isn't that what we have Ant for?"  Well, yes & no.  As you will see in the section on uPortal itself, the portal provides several setup and administrative functions through Ant.  Building  the uPortal software, on the other hand, has been largely migrated to Maven.  For the present, these 2 tools work together to handle build, deployment, and some management features of the portal.

uPortal 4.0.8 requires Maven version 3.0.3 or later, which can be obtained from the Maven downloads page.  Once you have the apache-maven-3.0.3-bin.zipfile, unzip it into your C:\portaldirectory. You should now have the following directory, which contains Maven:


Maven setup is very similar to Ant. Create a M2_HOMEenvironment variable and update your Pathvariable.

M2_HOME = C:\portal\apache-maven-3.0.3 Path = {existing path};%M2_HOME%\bin 

Finally, test your Maven setup by running the following command (REMINDER:  open a new command window):

mvn -version

Web Container

Before we can install uPortal, we must have a servlet 2.5 or greater compliant web container available. A web container is a JEE server component that enables access to servlets and JSP pages. There are many to choose from including WebLogic (BEA), WebSphere (IBM), JRun (Macromedia), Resin (Caucho), Jetty (Mortbay), and Apache Tomcat. Tomcat is the easiest implementation to use with uPortal and is recommended for use with uPortal.

Download the Tomcat distribution from the Tomcat downloads page (note: uPortal 4 requires Tomcat 6.x and will not run with Tomcat 5.5.x or earlier)

Once you have the apache-tomcat-6.0.33.zipfile unzip the file into the C:\portaldirectory. You should now have this directory containing Tomcat:


Now, we need to configure Tomcat to work with uPortal. Locate the following file:


Find the shared.loaderproperty and set the value as follows:


WARNING! Make certain the shared.loadersetting contains no typos and no extra characters of any sort. An extra space at the end of this line can break the whole portal!

Next, locate the file:


Find the <Connector>element for port 8080 and modify the element to include the emptySessionPath="true" attribute as follows:

<Connector port="8080"
    redirectPort="8443" >

The default uPortal installation requires Tomcat to use a bit more memory -- both PermGen memory and "regular" heap space -- then the default JVM configuration includes. To change these values, a new environment variable must be set to allow Tomcat to use more memory when needed. Set the JAVA_OPTS environment variable:

JAVA_OPTS=-XX:MaxPermSize=384m -Xms1024m -Xmx1024m

Last, we will create desktop shortcuts to the batch files that start and stop Tomcat. These batch files are located at:


Create shortcuts to these files and place them on the Windows desktop. Rename the shortcuts Start Tomcat and Stop Tomcat. To make sure Tomcat has been installed correctly and the shortcuts are functioning, double-click the Start Tomcat shortcut. A console window should open with a few startup messages from Tomcat. In a web browser, enter the URL http://localhost:8080/

This should bring up the Tomcat home page indicating that Tomcat is running successfully on your machine:

To shutdown Tomcat, simply double-click the Stop Tomcat shortcut on your desktop.


At this point we have all the prerequisites installed and ready: the JDK, a relational database, Ant and Maven. We are ready now to install uPortal.  You can download the uPortal 4.0.8 release from the Jasig website. For this exercise, we want the Source distribution (not the Quick Start).

The distribution file is named uPortal-4.0.8.tar.gz, which has been compressed with the gzip file format. On Windows, use a tool like 7 Zip to decompress and unarchive the file into the C:\portaldirectory. You should now have this directory containing the uPortal source code:


Obtaining uPortal Source from GitHub

Update 2012/11/28 -- Jasig uPortal has moved to GitHub.  Obtaining uPortal sources directly from GitHub -- using a >git clone command -- offers several important advantages over the method described here.

See the uPortal Git Workplow page on the Jasig wiki for detailed instructions.  The GitHub approach is highly recommended.


Next, we need to tell uPortal about the servlet container we are using. We need to create a new build file by copying the build.properties.samplefile to build.properties. Run the following command inside C:\portal:

>copy build.properties.sample build.properties

Now open the new file in an editor and find the server.homeproperty. Set the value as follows:


Database Configuration

For uPortal to deploy and run properly, it has to know about your RDBMS platform, database driver, and connection information. For this example, we've cheated somewhat, because in each case we have downloaded and installed exactly what uPortal 4.0.8 already expects. Nevertheless, it's probably advisable to verify the database configuration settings. It's a good idea for learning and for peace of mind.

Open the pom.xmlfile and verify the following lines appear exactly as shown:

    <!-- The JDBC Driver used by uPortal -->



Next open the filters/local.propertiesfile and verify the following as well:

## HSQL Configuration

## Database Connection Settings (Uncomment the Maven Filters section in rdbm.properties) 

The uPortal manual contains configuration instructions for Oracle, PostgreSQL, MySQL, MS SQL Server, DB2, as well as HSQLDB. Important: if you are using Oracle or Microsoft SQL Server you must first install the JDBC driver to your local maven repository.

Now it is time build uPortal and load the database with an initial set of uPortal data (users, channels, layout fragments, etc.). Make sure the database is up and running (see HSQLDB section above). Open a command prompt and change directories to the uPortal installation directory. From this directory, enter the Ant command that builds uPortal source, loads the database, and deploys the portal to Tomcat:

ant initportal 

The output should show information about the database and messages indicating that the database tables have been dropped, created, and populated. There should also be information about the publishing of channels and layout fragments.

At this point you should now be able to access the portal by starting Tomcat (restart Tomcat if it was already running) and visiting http://localhost:8080/uPortalin http://localhost:8080/uPortalin your browser.

That's it!  Now you can log into the portal as the demo, student, staff, faculty, or admin user (HINT:  the password is the same as the username).


Return to the article listing page