This documentation relates to uPortal 3.2
If you are using a different version, please click on "Click for all versions" on the left side of the page and select the relevant version.

Building & Deploying uPortal

Skip to end of metadata
Go to start of metadata
All Versions
Table of Contents

Building and Deploying Instructions for:

uPortal Full-Source Version
uPortal Quick-Start

uPortal Full-Source Version Instructions

After you have downloaded uPortal let's start building your uPortal instance by going to your uPortal source directory.

Step 1: Configure the file

The uPortal build requires a file describing the deployment environment to be available in the root of the uPortal project.

     1. Create the file by copying the file to


     2. Open the for editing and configure the "server.home" property to point to the root directory of your Tomcat installation.

##### Replace server.home with the location of Tomcat 6 on your machine #####
# path to tomcat binaries

The build file contains several other optional properties which may be configured to change the default server base and webapps directory or to re-configure Maven's home directory. Deployers may also use this file to modify defaults such as deletion of existing deployed resources.

Step 2: Configure your database.

Before deploying your uPortal instance to Tomcat we need to setup and configure the JDBC properties in the file.

For database-specific instructions find your selected database and follow the steps:

Step 3: Tomcat Reminder

Just in case you missed it, don't forget to do the following configuration in your Tomcat installation

  • Shared Libraries
    • uPortal places libraries in CATALINA_BASE/shared/lib The default Tomcat 6.0 download does not enable libraries to be loaded from this directory. To resolve this you must edit CATALINA_BASE/conf/ and change the line that begins "shared.loader=" to the following:
Enabling shared libraries in CATALINA_BASE/conf/
  • Shared Sessions
    • Jasig portlets, as well as many other popular JSR-168 portlets, rely on the ability to share user session data between the portal web application and portlet applications. To enable this feature in Tomcat, you must add the emptySessionPath="true" parameter to the in-use connector.
Example Tomcat Connector Configuration
<Connector port="8080" protocol="HTTP/1.1"
    connectionTimeout="20000" redirectPort="8443" emptySessionPath="true"/>
Step 4: Deploy uPortal

WARNING: Running the following command will reinitialize your database by dropping all tables first. Your content will be lost if you run against an existing database.

  • Run the following command to deploy uPortal and load your database
ant initportal
Step 5: Restart Tomcat
Step 6: Access uPortal
  • Replace localhost:8080 with your configured server path

If everything has been installed correctly you should see the out-of-the-box uPortal screen below

uPortal Quick-Start Instructions

Step 1: Untar the package

After downloading the uPortal quickstart version untar the package as follows

tar -xvf uPortal-3.2.1-quick-start.tar.gz
Step 2: Set up JAVA_HOME

Make sure the JAVA_HOME environment variable is set

 export JAVA_HOME=/path/to/java
Step 3: Startup uPortal

Start uPortal by running the ant command from inside the uPortal-3.2.1-quick-start directory

ant start
Step 4: Access uPortal

If everything has been installed correctly you should see the out-of-the-box uPortal screen below

Step 5: Stop uPortal
ant stop

For detailed instructions, read the README.txt file located in the uPortal-3.2.1-quick-start directory.

Ant build and deployment tasks

Ant Command



This target will test your database configuration from the command-line


The target that will deploy uPortal and load your database, but you must first set up the JDBC properties in and set up the path to your servlet container in

The "initportal" target runs all the targets necessary to deploy the portal and prepare the portal database: bootstrap, deploy-ear, db, pubchan, i18n-db.

*IMPORTANT* Do not run this task against a database the contents of which you care about, as it initializes the database by first dropping all tables.


The "deploy-war" target first makes sure everything is compiled and up-to-date and then copies the extracted uPortal Web Application Archive (WAR) to the location required by your servlet container as specified in


The "deploy-ear" target first makes sure everything is compiled and up-to-date and builds an Enterprise Application Archive (EAR) composed of the uPortal WAR and the WARs of all the portlets being deployed. The EAR is then extracted to the location required by your servlet container as specified in


The "deployPortletApp" target runs the portlet Deployer tool. This tool takes a portlet WAR file, rewrites the web.xml file and deploys the results to the servlet container.

Example: "ant deployPortletApp -DportletApp=C:/TEMP/myPortlet.war"


The "hsql" target starts an HSQLDB server instance consistent with the default data access configuration of uPortal. Note that this Ant target does not return in a normal execution – the Ant "build" kicks off the database server but then just keeps on running. You'll need to kill it manually, e.g. via control-C or via a stop build control in your IDE.

Having problems with these instructions?

Please send us feedback at

  • No labels