Jetspeed Build Guide - Building Jetspeed 2.2 from Source with Maven-2

Building and Deploying Jetspeed 2.2 from Source with Maven-2

Prerequisites

Building and deploying Jetspeed-2 from source has the following prerequisites:

Java Development Kit 1.5
Apache Maven 2.2.1+
Apache Tomcat 6.0.33+
Configuration of the org.apache.portals.jetspeed-2 Maven Settings pluginGroup, see: PREREQUISITE: configuration of the Maven Settings pluginGroups on the Overview page.
Either a downloaded release source distribution archive or directly checked out from the ASF Subversion source respository using a SVN client tool.
You can checkout the sources from http://svn.apache.org/repos/asf/portals/jetspeed-2/portal/trunk/

Configuring the build environment

All the settings needed during the build and for a jetspeed demo Portal deployment need to be defined in a single file in the root folder of the project: jetspeed-mvn-setttings.xml.
Note: this file is not provided but needs to be created manually first.

For convience however a sample file, jetspeed-mvn-setttings-sample.xml is provided which can simply be copied to jetspeed-mvn-setttings.xml.

The jetspeed-mvn-setttings-sample.xml provides a default configuration using an Embbedded Derby database, and if that suites you, probably the only changes needed are the location of the Derby database(s) and the deployment target directory (org.apache.jetspeed.server.home):

<properties>
    ...
    <!-- Your Tomcat Installation Path -->
    <org.apache.jetspeed.server.home>/home/demo/tomcat-6</org.apache.jetspeed.server.home>
    <org.apache.jetspeed.catalina.version.major>6</org.apache.jetspeed.catalina.version.major>
                        
    <!-- Production jdbc driver artifact properties -->
    <org.apache.jetspeed.production.jdbc.driver.groupId>org.apache.derby</org.apache.jetspeed.production.jdbc.driver.groupId>
    <org.apache.jetspeed.production.jdbc.driver.artifactId>derby</org.apache.jetspeed.production.jdbc.driver.artifactId>
    <org.apache.jetspeed.production.jdbc.driver.version>10.3.2.1</org.apache.jetspeed.production.jdbc.driver.version>
    
    <!-- Production database name, JDBC url, JDBC driver name and connection information -->
    <org.apache.jetspeed.production.database.default.name>derby</org.apache.jetspeed.production.database.default.name>
    <org.apache.jetspeed.production.database.url>jdbc:derby:/tmp/derby/productiondb;create=true</org.apache.jetspeed.production.database.url>
    <org.apache.jetspeed.production.database.driver>org.apache.derby.jdbc.EmbeddedDriver</org.apache.jetspeed.production.database.driver>
    <org.apache.jetspeed.production.database.user></org.apache.jetspeed.production.database.user>
    <org.apache.jetspeed.production.database.password></org.apache.jetspeed.production.database.password>
    
    ...
    
    <!-- You can also configure test database properties below if you want to run unit tests. -->
    
    <!-- Test jdbc driver artifact properties -->
    <org.apache.jetspeed.test.jdbc.driver.groupId>org.apache.derby</org.apache.jetspeed.test.jdbc.driver.groupId>
    <org.apache.jetspeed.test.jdbc.driver.artifactId>derby</org.apache.jetspeed.test.jdbc.driver.artifactId>
    <org.apache.jetspeed.test.jdbc.driver.version>10.3.2.1</org.apache.jetspeed.test.jdbc.driver.version>
    
    <!-- Test database name, JDBC url, JDBC driver name and connection information -->
    <org.apache.jetspeed.test.database.default.name>derby</org.apache.jetspeed.test.database.default.name>
    <org.apache.jetspeed.test.database.url>jdbc:derby:/tmp/derby/testdb;create=true</org.apache.jetspeed.test.database.url>
    <org.apache.jetspeed.test.database.driver>org.apache.derby.jdbc.EmbeddedDriver</org.apache.jetspeed.test.database.driver>
    <org.apache.jetspeed.test.database.user></org.apache.jetspeed.test.database.user>
    <org.apache.jetspeed.test.database.password></org.apache.jetspeed.test.database.password>
    ...
</properties>

Note: depending on your database platform, the value of the org.apache.jetspeed.production.database.default.name property can be one of the followings depending on your database platform:

db2
db2v8
derby
mssql
mysql
mysql5
oracle9
oracle10
postgresql
sapdb

For details about supported databases, refer to the Apache DB Project - DdlUtils Homepage.

The following jetspeed-mvn-settings.xml provides a sample configuration using a PostgreSQL database:

<properties>
    ...
    <!-- Your Tomcat Installation Path -->
    <org.apache.jetspeed.server.home>/home/demo/tomcat-6</org.apache.jetspeed.server.home>
    <org.apache.jetspeed.catalina.version.major>6</org.apache.jetspeed.catalina.version.major>

    <!-- Production jdbc driver artifact properties -->
    <org.apache.jetspeed.production.jdbc.driver.groupId>postgresql</org.apache.jetspeed.production.jdbc.driver.groupId>
    <org.apache.jetspeed.production.jdbc.driver.artifactId>postgresql</org.apache.jetspeed.production.jdbc.driver.artifactId>
    <org.apache.jetspeed.production.jdbc.driver.version>8.3-603.jdbc3</org.apache.jetspeed.production.jdbc.driver.version>
    
    <!-- Production database name, JDBC url, JDBC driver name and connection information -->
    <org.apache.jetspeed.production.database.default.name>postgresql</org.apache.jetspeed.production.database.default.name>
    <org.apache.jetspeed.production.database.url>jdbc:postgresql://localhost/j2</org.apache.jetspeed.production.database.url>
    <org.apache.jetspeed.production.database.driver>org.postgresql.Driver</org.apache.jetspeed.production.database.driver>
    <org.apache.jetspeed.production.database.user>j2</org.apache.jetspeed.production.database.user>
    <org.apache.jetspeed.production.database.password>j2</org.apache.jetspeed.production.database.password>
    
    ...
    
    <!-- You can also configure test database properties below if you want to run unit tests. -->
    
    <!-- Test jdbc driver artifact properties -->
    <org.apache.jetspeed.test.jdbc.driver.groupId>postgresql</org.apache.jetspeed.test.jdbc.driver.groupId>
    <org.apache.jetspeed.test.jdbc.driver.artifactId>postgresql</org.apache.jetspeed.test.jdbc.driver.artifactId>
    <org.apache.jetspeed.test.jdbc.driver.version>8.3-603.jdbc3</org.apache.jetspeed.test.jdbc.driver.version>
    
    <!-- Test database name, JDBC url, JDBC driver name and connection information -->
    <org.apache.jetspeed.test.database.default.name>postgresql</org.apache.jetspeed.test.database.default.name>
    <org.apache.jetspeed.test.database.url>jdbc:postgresql://localhost/j2test</org.apache.jetspeed.test.database.url>
    <org.apache.jetspeed.test.database.driver>org.postgresql.Driver</org.apache.jetspeed.test.database.driver>
    <org.apache.jetspeed.test.database.user>j2test</org.apache.jetspeed.test.database.user>
    <org.apache.jetspeed.test.database.password>j2test</org.apache.jetspeed.test.database.password>
    ...
</properties>

Alos, the following provides a sample configuration using a MySQL database:

<properties>
    ...
    <!-- Your Tomcat Installation Path -->
    <org.apache.jetspeed.server.home>/home/demo/tomcat-6</org.apache.jetspeed.server.home>
    <org.apache.jetspeed.catalina.version.major>6</org.apache.jetspeed.catalina.version.major>
    
    <!-- Production jdbc driver artifact properties -->
    <org.apache.jetspeed.production.jdbc.driver.groupId>mysql</org.apache.jetspeed.production.jdbc.driver.groupId>
    <org.apache.jetspeed.production.jdbc.driver.artifactId>mysql-connector-java</org.apache.jetspeed.production.jdbc.driver.artifactId>
    <org.apache.jetspeed.production.jdbc.driver.version>5.1.6</org.apache.jetspeed.production.jdbc.driver.version>
    
    <!-- Production database name, JDBC url, JDBC driver name and connection information -->
    <org.apache.jetspeed.production.database.default.name>mysql5</org.apache.jetspeed.production.database.default.name>
    <org.apache.jetspeed.production.database.url>jdbc:mysql://localhost:3306/j2</org.apache.jetspeed.production.database.url>
    <org.apache.jetspeed.production.database.driver>com.mysql.jdbc.Driver</org.apache.jetspeed.production.database.driver>
    <org.apache.jetspeed.production.database.user>j2</org.apache.jetspeed.production.database.user>
    <org.apache.jetspeed.production.database.password>j2</org.apache.jetspeed.production.database.password>
    
    ...
    
    <!-- You can also configure test database properties below if you want to run unit tests. -->
    
    <!-- Test jdbc driver artifact properties -->
    <org.apache.jetspeed.test.jdbc.driver.groupId>mysql</org.apache.jetspeed.test.jdbc.driver.groupId>
    <org.apache.jetspeed.test.jdbc.driver.artifactId>mysql-connector-java</org.apache.jetspeed.test.jdbc.driver.artifactId>
    <org.apache.jetspeed.test.jdbc.driver.version>5.1.6</org.apache.jetspeed.test.jdbc.driver.version>
    
    <!-- Test database name, JDBC url, JDBC driver name and connection information -->
    <org.apache.jetspeed.test.database.default.name>mysql5</org.apache.jetspeed.test.database.default.name>
    <org.apache.jetspeed.test.database.url>jdbc:mysql://localhost:3306/j2test</org.apache.jetspeed.test.database.url>
    <org.apache.jetspeed.test.database.driver>com.mysql.jdbc.Driver</org.apache.jetspeed.test.database.driver>
    <org.apache.jetspeed.test.database.user>j2test</org.apache.jetspeed.test.database.user>
    <org.apache.jetspeed.test.database.password>j2test</org.apache.jetspeed.test.database.password>
    ...
</properties>

Note: To run unit tests properly with MySQL database, you should enable InnoDB storage engine and use InnoDB tables. InnoDB is a transactional-safe (ACID compliant) storage engine for MySQL database. See the documentation of MySQL for details.

Configuring Tomcat

A few changes and additions are needed to the default provided configuration of Tomcat to support proper Portlet API session management requirements and Jetspeed portlet application management integration:

In <TOMCAT_HOME>/conf/server.xml:
Modify the Connector element (default on port 8080) by adding the following attribute and value:
```
emptySessionPath="true"
```
In <TOMCAT_HOME>/conf/context.xml:
Uncomment the following to disable session persistence across Tomcat restarts:
```
<Manager pathname=""/>
```
Optional: in <TOMCAT_HOME>/conf/tomcat-users.xml:
Select or add a specific Tomcat user with at least role manager-script to be used by Jetspeed to communicate with the Tomcat Manager application:
```
<user username="j2deployer" password="&lt;<em>strong</em> password&lt;" roles="manager-script"/>
```
Then, define this username and its password in the jetspeed.properties file read by the portal at runtime, but overriding and more secret values can be specified in override.properties.
See for further information the Tomcat Manager and Jetspeed section in the Deployers Guide.

Building and installing Jetspeed Portal

Optional: Bootstrap build the Jetspeed Maven Plugins first

When building Jetspeed 2.2 from a released source distribution archive or a SVN checkout of a corresponding release tag the following step can be skipped.

However, when building a specific Jetspeed 2.2.x SNAPSHOT or branch SVN checkout which has not (yet) been released, you will have to run the following command first, but only the first time (for the checkout version):

$mvn install -P init

The above command will ensure the custom Jetspeed Maven Plugins as well as the portal resources for this build version are prebuild and installed in your local Maven repository as they might not be available from a remote Maven repository.

Without the above bootstrap build an initial/first $mvn clean execution might lead to a BUILD FAILURE: "A required plugin was not found" error.

Standard Maven build & install

A full build and installation of all the Jetspeed-2 components into your local Maven repository is done using the standard Maven install goal:

$mvn install

Deploying the jetspeed Demo Portal

First make sure to setup Tomcat 6 (6.0.33+) locally and apply the above described Tomcat configuration changes first.
Also make sure to configure the appropriate Tomcat major version (org.apache.jetspeed.catalina.version.major) and installation path (org.apache.jetspeed.server.home) in your local jetspeed-mvn-settings.xml file in the root of the Jetspeed project.

After first building and installing the Jetspeed project using $mvn install as described above, deploy the Jetspeed Demo Portal to Tomcat using the following command:

$mvn jetspeed:mvn -Dtarget=demo

Thereafter start Tomcat (in a separate console):
Note that the setting of CATALINA_OPTS is optional in the following examples. (See Note on Permanent Generation Size of Your JVM for detail.)

$ cd $TOMCAT_HOME/bin
$ export CATALINA_OPTS="-Xmx256m -XX:MaxPermSize=128m"
$ ./catalina.sh run

And after waiting a few seconds until Tomcat server completed starting up, the Jetspeed Demo Portal can be accessed through:

http://localhost:8080/jetspeed

For login, use one of the following username/password combinations: admin/admin, user/user, jetspeed/jetspeed

Note on Permanent Generation Size of Your JVM

Note: You may need to increase the permanent generation size of your JVM when there are a lot of Servlets, JSP's or when script portlets are used, in order to avoid OutOfMemoryError errors. By default, it is 64MB. Increasing it to be -XX:MaxPermSize=128m might be a good start. Please see http://wiki.apache.org/tomcat/FAQ/Memory for detail.

Deploying a minimal Jetspeed Portal

If you don't need the demo portlet applications, you can also deploy Jetspeed with only the j2-admin portlet application using the following command instead:

$mvn jetspeed:mvn -Dtarget=min

Build and installation options

Overview

Using the jetspeed:mvn plugin, several defined custom build and installation tasks (targets) are provided for the Jetspeed Portal project itself.

The complete list of available targets can be queried using the special -Dlist command line parameter:

$mvn -o jetspeed:mvn -Dlist

The primary jetspeed:mvn targets are described in detail below. Please see the Mvn Plugin configuration documentation and the root project pom.xml build file for further reference.

Primary jetspeed:mvn Targets

There are four major modes the portal can be built and deployed under:

ui: full ui pipeline demo build
min-ui: minimal ui pipeline demo build
demo: full portal pipeline demo build
min: minimal portal pipeline demo build

Additionally, there are two Page Manager variants for each mode:

XML file system based PSML
Database PSML

The primary build targets that can be used to build and deploy all or parts of the portal are outlined here:

`test`	Executing the `test` target will simply execute the standard Maven test goal within the current (sub module) project folder, and enables the `test` profile. Of course the same effect can be achieved by just executing `$mvn test -P test` but the primary reason for this target definition is to be used as dependent target for other targets (see below).
`testdb, proddb`	Executing one of these targets will (re)create either a test or production database (schema), using the database configuration properties from the `jetspeed-mvn-settings.xml` file. Note: this target can be executed from within any (sub) module folder within the project.
`ui-seed, min-ui-seed, demo-seed, min-seed and ui-db, min-ui-db, demo-db, min-db`	Besides (re)creation a (production) database using the `proddb` target, the Jetspeed database also needs some initial data to be seeded first to be able to run the Jetspeed Portal. The `ui-seed, min-ui-seed, demo-seed, min-seed` targets will take care of that using specific `j2-seed.xml` files. These seed files are dynamically retrieved from a previously build and installed or downloaded `jetspeed-portal-resouces:jar` artifact where the configured seed files are references relative to a specific folder within this resources artifact. As the `proddb` target and the *`-seed` targets usually are executed together, the `ui-db, min-ui-db, demo-db, min-db`** targets are also defined to allow execution those as a single target.
`demo-install`	This target will simply invoke the default Maven goal, (which is install), against the `applications/jetspeed-demo` module pom.xml.
`ui, min-ui, demo, min`	These targets will perform the actual deployment of the Jetspeed Portal to the Tomcat installation along with all database configuration and seeding. The XML file system based PSML implementation is used and its pages (re)deployed by default. Note: executing these targets directly assumes all the required Jetspeed artifacts already are build and installed.
`ui-nodb, min-ui-nodb, demo-nodb, min-nodb`	These targets only perform the deployment of the Jetspeed Portal. The database is left untouched, (the XML file system based PSML pages are redeployed).
`ui-dbpsml, min-ui-dbpsml, demo-dbpsml, min-dbpsml`	These targets are variants of the `ui, min-ui, demo, min` targets for the Database PSML configuration, (its pages are seeded into the database);
`ui-dbpsml-nodb, min-ui-dbpsml-nodb, demo-dbpsml-nodb, min-dbpsml-nodb`	These targets are variants of the `ui-nodb, min-ui-nodb, demo-nodb, min-nodb` targets for the Database PSML configuration, (its pages are not seeded into the database);

Test building Jetspeed Portal

Running the test-cases during a build

By default, running test-cases is disabled for Jetspeed-2 because it is very time-consuming and also requires the setup and initialization of a dedicated test database every time!

But if you are a Jetspeed committer or otherwise would like to run the test-cases anyway, the testdb jetspeed:mvn target can be used to setup and initialize the test database:

$mvn jetspeed:mvn -Dtarget=testdb

Or you can run the following command to automatically execute the testdb target first before running a test build:

$mvn jetspeed:mvn -Dtarget=test-install

Note: Running the test-cases requires (and only for this) the proper configuration of the org.apache.jetspeed.test.database.* properties in jetspeed-mvn-settings.xml

Additional note: Probably you need to configure some memory settings for maven to run all the tests properly because some test cases require more memory than the default memory size. You can configure memory settings for maven by setting the environment variable 'MAVEN_OPTS'. For example:

$export MAVEN_OPTS="-Xmx128m -XX:MaxPermSize=128m"

Maven Profiles

The following profiles can be supplied when building.

`mvn -P all`	specified that all modules (the API, plugins, portal resources, commons, components and applications) be built.
`mvn -P init`	specified some modules to be initialized first (the API, plugins and portal resources)
`mvn -P test`	specified that all modules (the API, plugins, portal resources, commons, components and applications) be built, with the property setting, -DskipTests=false

Additional Notes

mvn -P test and mvn -DskipTests=false are equivalent.
mvn -P test -Dtest=MyTest will execute a single test or matching tests if Ant wildcards are used.
Due to forking bugs in the Surefire Maven2 test runner plugin, test output, (e.g. System.out.println()), is not echoed to the build shell. If you wish to see console output for component tests, temporarily comment out the <forkMode> elements in the components/pom.xml and the components pom.xml and run single tests. Note: the forking is required to run multiple tests.
The -o offline option can be specified with the commands documented here to force Maven2 to use only the local repository. This can be invaluable in the event the main Maven2 repositories are down and the build insists upon validating a missing or troublesome POM.