building uportal from source

Sat, Mar 25, 2006

This document describes how to build and install uPortal 2.5.1 from source and link it to PostgresSQL 8.1.3 and deploy it on Tomcat 5.5.16 with JDK 1.5.0.

The first thing you need to do is download the uPortal source code. Download the uPortal-only package : get it here

Once you’ve got it, unpack it. I’ll assume you’ve unpacked it to /usr/local/src to get:

/usr/local/src/uPortal_rel-2-5-1

We’ll call this UP_HOME from now on.

Next you have to configure uPortal to work with postgres. For this, you’ll need the 8.1.3 JDBC driver : get it here

Download the 8.1 Build 405 driver and put the jar file, postgresql-8.1-405.jdbc3.jar in UP_HOME/lib

Now, edit UP_HOME/build.properties. My tomcat is in /usr/local/apache-tomcat-5.5.16 so I set this:

server.home=/usr/local/apache-tomcat-5.5.16

Locate the section that starts:

#==================== External Dependencies ===========================

comment out the current database driver:

#jdbcDriver.jar=${lib.path}/hsqldb.jar

and add the line:

jdbcDriver.jar=${lib.path}/postgresql-8.1-405.jdbc3.jar

Now open the file UP_HOME/properties/rdbm.properties and edit the postgres JDBC section:

PostgreSQL - example

jdbcDriver=org.postgresql.Driver jdbcUrl=jdbc:postgresql://localhost:5432/uportal jdbcUser=postgres jdbcPassword=x

make sure you use your own database!

Now, before you can build from source, you have to add type mappings for postgres 8.1.3. Open the file UP_HOME/properties/db/dbloader.xml and add a type mapping for postgres 8.1.3:

<db-type-mapping> <db-name>PostgreSQL</db-name> <db-version>8.1.3</db-version> <driver-name>PostgreSQL Native Driver</driver-name> <driver-version>PostgreSQL 8.1 JDBC3 with SSL (build 405)</driver-version> <type><generic>LONGVARCHAR</generic><local>TEXT</local></type> <type><generic>VARCHAR</generic><local>VARCHAR</local></type> <type><generic>LONGVARBINARY</generic><local>BYTEA</local></type> <type><generic>VARBINARY</generic><local>BYTEA</local></type> <type><generic>INTEGER</generic>< <local>integer</local></type> </db-type-mapping>

If you don’t add the type mapping exactly as above, for the driver you just downloaded, you’ll get the database error:

Your database driver, ‘PostgreSQL Native Driver’, version ‘PostgreSQL 8.1 JDBC3 with SSL (build 405)’, was unable to find a local type name that matches the generic type name, ‘LONGVARCHAR’. Please add a mapped type for database ‘PostgreSQL’, version ‘8.1.3’ inside ‘file:/usr/local/src/uPortal_rel-2-5-1/build/WEB-INF/classes/properties/db/dbloader.xml’ and run this program again.

If you’re using a different version of postgres, make sure you match the driver version string from any error you get with the type mappings you add. Also, don’t pay any attention to the file location - update the one in properties/db/dbloader.xml. Now, create the uPortal database you’ll use:

su postgres createdb uportal

Now, you’re ready to build. I built using JDK 1.5 as then you don’t have to bother with the endorsed libraries. I also have JDK 1.4 installed so I have to specify which one to use at build time:

export JAVA_HOME=/System/Library/Frameworks/JavaVM.framework/Versions/1.5.0/Home ant initportal

My Tomcat directory is writeable to my user but if your’s isn’t, you’ll have to prefix the ant command with sudo.

This will build, initialise the database, install uPortal and deploy the portlets to /usr/local/apache-tomcat-5.5.16/webapps/uPortal. It also copies the configuration fragment:

/usr/local/apache-tomcat-5.5.16/conf/Catalina/localhost/uPortal.xml

However, before you can start it up, you have to fix a bug. uPortal doesn’t work with Tomcat 5.5 due to JNDI Datasource configuration changes. In Tomcat 4.x/5.0.x this is used by uPortal in uPortal.xml:

<Resource name=“jdbc/PortalDb” auth=“Container” type=“javax.sql.DataSource” /> <ResourceParams name=“jdbc/PortalDb”>

i.e. the Resource is named and then configured separately via a ResourceParams element. In Tomcat 5.5.x, this has changed and ResourceParams is no longer used. Instead, the configuration is specified in the Resource element. So you should replace the two Resource elements in uPortal.xml with the new format:

<Resource name=“jdbc/PortalDb” auth=“Container” type=“javax.sql.DataSource” driverClassName=“org.postgresql.Driver” url=“jdbc:postgresql://localhost:5432/uportal” username=“postgres” password=“x” maxActive=“20” maxIdle=“10” maxWait="-1" />

<Resource name=“jdbc/PersonDb” auth=“Container” type=“javax.sql.DataSource” driverClassName=“org.postgresql.Driver” url=“jdbc:postgresql://localhost:5432/uportal” username=“postgres” password=“x” maxActive=“20” maxIdle=“10” maxWait="-1" />

If you don’t do this, you’ll see this error in the logs:

Cannot create JDBC driver of class '' for connect URL ‘null’

It took me ages to figure that one out.

You can forget about webapps/uPortal/META-INF/context.xml. Tomcat 5.5.x uses conf/Catalina/localhost/uPortal.xml to configure the datasources.

You can now start tomcat and access uPortal from:

http://localhost:8080/uPortal

References:

Tomcat 5.5.x JNDI Datasource HOW-TO

comments powered by Disqus