Requirements

It is expected that the user is familiar with both the Apache Maven project tool and the Apache Ant build tool.

  • Ant 1.5 or higher
  • Maven 1.0 or higher
  • Java 1.4.2_02 or higher
  • Servlet 2.3:

    Tomcat 5.0.30 (or higher)

    or

    Tomcat 5.5.8 (or higher)

Naming Conventions and Basic Assumptions

Basic Assumptions

  • Unless otherwise specified, you should be running all maven build commands from within the Jetspeed directory (if you are just building Jetspeed) or from within your custom portal directory.
  • You must use "/" as a file seperator on both *nix and windows, e.g. c:/windows, and /home.

Naming Conventions

Below is a listing of common conventions used within this document.

Variables are represented as such, ${some_variable}. This may signify a setting in jetspeed or may represent a setting within your environment.

Properties files are also capable of using ${some_variable} within them. So, for example, ${org.apache.jetspeed.server.home} references either a property defined further up in the properties file, that has been defined somehwere within the build process or defined in another build file within jetspeed.

  • ${USER_HOME}: This is the user's home directory. For Windows systems, this generally c:\Documents and Settings\${userName} where ${userName} is the name you log into windows as.

    ${USER.HOME} is synonymous with ${USER_HOME} within this document.
  • ${CATALINA_HOME}: This should point to the location of your tomcat installation, e.g. c:/tomcat.

Subversion (SVN)

Subversion (SVN) is becoming the standard source and version control mechanism for Apache projects. SVN is very similar CVS. For those user's on Windows system who prefer non-command line access we suggest using TortoiseSVN which plugs into your Windows Explorer view. For those using the Eclipse IDE, there is a plugin available for SVN access.

Maven

We will not go into the specifics of Maven as that is beyond the scope of this document. However, here are a few bits of standard maven jargon we feel is important for you to know.

You will see mention of a maven repository in this document. When you install Maven the .maven/ directory is created in your ${USER_HOME) directory.

Under .maven/ you will see a repository directory. This is were Maven stores all the jars it downloads when you run your builds. This is also were Maven puts your jars.wars you build under the format of ${groupId}/${projectId}/jars/${projectId}-{$version}.jar for jar files and ${groupId}/${projectId}/wars/${projectId}.war for war files. The ${groupId}, ${projectId} and ${version} variables are discussed later on in this document. Jars/wars will also be created in your project in the /target directory.

1. Get Maven Ready

If you have not already done so, download and install Maven.

2. Jetspeed build and maven-plugin Properties

If you are going to build Jetspeed directly from the source or want to setup a custom portal you need to set a few properties.

Creating your own custom portal is very easy with the maven plugin provided by Jetspeed 2. And, it is used when you build jetspeed from source as well. In fact, the jetspeed-2 build procedure is just one example of a custom portal configuration and setup.

The Jetspeed 2 maven-plugin defines default values for most of the properties you can set, but not all. When you download or checkout the jetspeed-2 source tree, you'll see it contains a project.properties file in the root folder overriding and setting some of these properties.

As said before: not all properties are provided with a default value: you must specify a few yourself. And you'll most likely want to override some others.

Set or override the build or maven-plugin properties in your ${USER_HOME}/build.properties file.

Required Portal Configuration Properties

PropertyDescriptionDefault value
org.apache.jetspeed.portal.home The folder where the maven-plugin will (re)create or update your custom portal maven project configuration (with goal j2:portal.conf.project). This will be where you will be performing all of your future custom portal development.

Example: /home/myportal/
no default
org.apache.jetspeed.portal.groupId The (maven) short name of your portal project group.

This value is used for the maven repository folder in which the project artifacts (like the portal war file) is stored.

Example: myprojects
no default
org.apache.jetspeed.portal.artifactId The (maven) short name of your portal project.

This value is used for the portal war file and the (portal) web application context name.

Example: myportal
no default
org.apache.jetspeed.portal.name The (maven) full name of your portal project.

This value is used by maven for generating JavaDoc titles.

Example: My Test Portal
no default
org.apache.jetspeed.portal.currentVersion The current version of your portal project.

This value is used by maven as name postfix for the generated artifacts.

Example: 1.0
no default

Optional Portal Configuration Properties

The following properties all specify a subfolder of the ${org.apache.jetspeed.portal.home} location as defined above.

PropertyDescriptionDefault value
org.apache.jetspeed.portal.conf.dir The folder where the maven-plugin will generate and copy application server specific configuration files as a tomcat application context descriptor.

This folder and its contents is created or updated by plugin goal j2:portal.conf.tomcat.
target/portal-conf
org.apache.jetspeed.portal.sql.dir The folder where the maven-plugin will generate and copy portal and database server specific sql DDL and DML scripts.

This folder and its contents is always (re)created by plugin goal j2:portal.conf.sql.
target/portal-sql
org.apache.jetspeed.portal.db.dir The folder where the maven-plugin will create its build-in HSQLDB database(s).

This folder and its contents is created or updated by plugin goal j2:start.production.server or j2:start.test.server.
target/portal-db
org.apache.jetspeed.portal.webapp.dir The folder where the maven-plugin will copy the standard jetspeed web application resources.

This folder and its contents is created or updated by plugin goal j2:portal.copy.webapp.
target/${org.apache.jetspeed.portal.artifactId}
org.apache.jetspeed.portal.target.dir The folder where the maven-plugin will generate and copy runtime portal configuration files.

These configuration files contain values derived from build/plugin properties for the portal and OJB.

This folder and its contents is created or updated by plugin goal j2:portal.conf.jetspeed and goal j2:portal.conf.ojb.
target/${org.apache.jetspeed.portal.artifactId}

Required Application Server Properties

Note: The maven-plugin currently only supports the Tomcat Server 5.0.x or 5.5.x

PropertyDescriptionDefault value
org.apache.jetspeed.server.home The root folder of your Tomcat server installation.

Example: ${CATALINA_HOME}/.
no default
org.apache.jetspeed.server.shared The location of the shared jars in your Tomcat installation.

Example: ${org.apache.jetspeed.server.home}/shared/lib/
no default
org.apache.jetspeed.deploy.war.dir The location of web applications in your Tomcat installation.

Example: ${org.apache.jetspeed.server.home}/webapps/
no default
org.apache.jetspeed.services.autodeployment.user A Tomcat user with the manager role.

Used to access the Tomcat Manager application from within the portal, explained below.
no default
org.apache.jetspeed.services.autodeployment.password The password of the Tomcat user above.

Used to access the Tomcat Manager application from within the portal, explained below.
no default
org.apache.jetspeed.catalina.version.major The major version of the Tomcat server you are using: 5 or 5.5

Example: 5.5
no default

Optional Database Server Properties

Jetspeed-2 and its maven-plugin uses, as well as provides, by default a HSQLDB database.

If you want to use a different database you will need to override the following properties:

PropertyDescriptionDefault value
org.apache.jetspeed.production.database.default.name The type of database you are using. Used for sql script generation with Torque.

Currently supported databases (with corresponding Torque target database name):
  • hsql (hypersonic)
  • oracle (oracle)
  • mysql (mysql)
  • postgres (postresql)
  • mssql (mssql)
hsql
org.apache.jetspeed.production.database.url The jdbc connection urljdbc:hsqldb:hsql://127.0.0.1:9001
org.apache.jetspeed.production.database.user The database user name to connect with.sa
org.apache.jetspeed.production.database.password The database user its password to connect with. empty
org.apache.jetspeed.production.database.driver The jdbc driver class nameorg.hsqldb.jdbcDriver
org.apache.jetspeed.production.jdbc.drivers.path A Java classpath style path to the jdbc driver classes or jar(s) needed for connecting to the database.

Example: /lib/ojdbc14.jar;/lib/nls_charset12.jar
empty

Example: A minimal custom portal configuration

Make sure you have define at least the required properties as described above in your ${USER_HOME}/build.properties. A minimal custom portal configuration using the default HSQLDB database can be something like:

            
          
Note: If you're going to build the default Jetspeed 2 portal directly from the source only the org.apache.jetspeed.portal.home property is required from the set of required portal configuration properties.

3 Tomcat Configuration

Jetspeed 2 can use the Tomcat Manager application for managing portlet applications with the Portlet Application Lifecycle Manager Portlet (PALM). To be able to do so it needs a configured Tomcat user with the predefined 'manager' role in the ${org.apache.jetspeed.server.home}/conf/tomcat-users.xml.

A minimal example tomcat-users.xml can look like:

          
        
The attribute values for username and password must correspond to the specified values for ${org.apache.jetspeed.services.autodeployment.user} and ${org.apache.jetspeed.services.autodeployment.user} as described above.

Tomcat 5.5.9 on Windows

To have redeployment and undeployment working properly when using Tomcat 5.5.9 on Windows you have to set the global Context attribute "antiJARLocking" to true.

In ${org.apache.jetspeed.server.home}\conf\context.xml use:

            
          

4. Creating a new Portal Application

Now we're going to configure, setup and build a new custom portal application using the Jetspeed-2 maven-plugin.

4.1 Set the maven remote repository lookup configuration

To be able to setup a Jetspeed 2 based portal the maven remote repository lookup needs to be configured properly in your ${USER_HOME}/build.properties:

            
          
Note: the order in which these repositories must be specified is significant!

4.2 Install the Jetspeed 2 maven-plugin

The first time, and when you want to upgrade to a newer version of Jetspeed 2, you need to install the maven-plugin as follows:

            
          
Note: you can set the version flag to the specific version you want to install, 2.0-M4-SNAPSHOT is just an example here.

4.3 Generate a new portal project

Once you have the maven-plugin installed and set properties as needed, generate a default portal configuration using the plugin as follows:

            
          
This maven goal actually executes several subgoals which are further described in the maven-plugin documentation itself.

4.4 Further customization of the portal

This section doesn't specify anything to do. After the portal project is generated you can adapt and customize it to your taste by overriding and merging your own configurations and extensions.

You can regenerate or update (part of) your portal project with the j2:portal.genapp goal as described in the previous section or use its subgoals directly.

4.5 Build the portal

Once your portal configuration and setup is ready, you can build and install the portal application in your local maven repository (as needed for deployment) using the following standard maven goal from your custom portal project directory (in ${org.apache.jetspeed.portal.home}):

            
          

You are now ready to deploy the new portal application. For this, skip the following section on building the Jetspeed 2 portal from source and continue with the deployment section.

5. Build Jetspeed 2 from source

Build the Jetspeed 2 portal directly from the source is somewhat easier to do but should only be done if you don't want to create a new, customizable portal.

5.1 Setup the Jetspeed 2 source and build properties

The Jetspeed 2 source contains a project.properties file which provides all of the required portal configuration settings as described above.

You should not define any of those properties in your ${USER_HOME}/build.properties.

Instead, you must set a org.apache.jetspeed.project.home property, specifying the location where you expanded the downloaded source or checked out the source from subversion, like:

            
          
Note: you still need to specify the required application server properties as described above.

The Jetspeed 2 project.properties uses this property to define the required org.apache.portal.home:

            
          
So, they are the same when you build the Jetspeed 2 portal from the source.

When you are going to deploy the portal as described further below, you'll see references to the org.apache.jetspeed.portal.home which you can translate with the root folder of your Jetspeed 2 source.

If you want to run the testcases when building the Jetspeed 2 sources and don't want to use the default HSQLDB test database, you need to override the default test database properties, similar to the production database properties as described above:

  • org.apache.jetspeed.test.database.default.name
  • org.apache.jetspeed.test.database.url
  • org.apache.jetspeed.test.database.user
  • org.apache.jetspeed.test.database.password
  • org.apache.jetspeed.test.database.driver
  • org.apache.jetspeed.test.database.drivers.path
Note: due to outstanding issue JS2-320 you currently must use hard coded values for the test database properties.

Initialize the maven-plugin

Instead of downloading and installing the Jetspeed 2 maven-plugin, you are going to build and install it directly from the source. You will need to repeat this every time you update to a newer version of Jetspeed 2 or change its project configuration, the plugin itself or the resources used by the plugin.

Build and install the maven-plugin as follows from the root directory of the Jetspeed-2 source:

            
          

Optional: start the HSQLDB test database first

If you are going to run the testcases and are using the default HSQLDB database configuration, you will need to start the test database before building Jetspeed 2 in a separate console:

            
          

After the build is finished you can stop the database and close this console with a Ctrl-C.

Build the Jetspeed 2 portal and demo portlet applications

For a full build and installation of the portal and the demo portlet applications in your local maven repository run:

            
          

But, if you also want to run the testcases during the build run the following instead:

            
          

You are now ready to deploy the Jetspeed 2 Portal.

6. Deploy and Run

Optional: start the HSQLDB production database first

If you are using the default HSQLDB database you need to start it before deploying the portal.

To start the HSQLDB production database run the following in a separate console:

            
            

You need to have this database running during the deployment and while running the application server. Afterwards you can stop the database and close this console with a Ctrl-C.

Note: this is required when using the j2:quickStart goal as described below. The Jetspeed 2 maven-plugin provides other (sub)goals which you can use without (re)creating a production database and/or inserting default portal configuration data. See the Plugin documentation for further information about the available goals.

Deploy

We currently only cover deploying to Tomcat 5 or Tomcat 5.5.

Information about deployment to other application servers can be found at the The Jetspeed 2 Wiki.

To deploy a default Jetspeed 2 portal, including the demo portlet applications, run the following in a separate console:

            
          
Note: the maven-plugin documentation described other goals you can use to customize the deployment to your taste.

Run

The final step is starting up your Tomcat server and the portal will automatically install any deployed portlet applications.

Then you can access the portal with your browser at:

    http://localhost:8080/jetspeed
          
or replace "jetspeed" in the above url with the name of you own portal application (${org.apache.jetspeed.portal.artifactId}).

Default installed user accounts

With the default Jetspeed 2 portal deployment, several example user accounts are inserted into the portal database with which you can logon to the portal:

usernamepasswordroles
adminadminadmin, manager, user
managermanagermanager, user
jetspeedjetspeedmanager
useruseruser
tomcattomcat