1. Building a Custom Portal with the Maven-1 Plugin

Basic Assumptions

Note the Maven-1 plugin will be deprecated in Jetspeed version 2.2

  • 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.

Maven

We will not go into the specifics of Maven as that is beyond the scope of this document. If you have never used Maven, you need to read "What is Maven" just to get a sense of the role of Maven in a software development project. If your project involves more than one or two people, you may want to look into Maven in more detail since it does simplify and standardize many of the project management issues that are commonly encountered.

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 of the jars that it downloads when you run your builds. This is also were Maven puts your jars and wars that you build. Jar files will be stored in a directory structure that has the format of ${groupId}/${projectId}/jars/${projectId}-{$version}.jar. The portal war file is stored as ${groupId}/${projectId}/wars/${projectId}.war. The ${groupId}, ${projectId} and ${version} variables are discussed later on in this document. Jar and war files will also be created in your project in the /target directory.

Variables

Variables are represented as ${ some_variable }. Variable names are case sensitive. Variables are defined in several places in a Maven project and according to the Maven Setup section of the on-line Maven User's Guide, the properties files in Maven are processed in the following order:

  • ${project.home}/project.properties - Properties that are common to the entire project
  • ${project.home}/build.properties - Properties that describe the current release
  • ${user.home}/build.properties - Properties that are particular to you
The usage of these files is quite different from the way they are used in a project that develops from the sources since the project in that case is the Jetspeed project rather than your own portal. In that case, the user's build.properties is used much more intensively used to override Jetspeed's parameters.

Maven processes this sequence of properties files, overriding any previously defined properties with newer definitions. The last definition wins! In this sequence, your ${user.home}/build.properties has the final say in the list of properties files processed.

This list of properties files that Maven processes is called the "standard properties file set".

In addition, System properties are processed after the standard properties files. So, a property specified on the command line using the -Dproperty=value convention will override any previous definition of that property.

For example, ${org.apache.jetspeed.server.home} references either:

  • a property defined earlier in the standard properties file set,
  • a property specified on the command line of the Maven invokation,
  • a variable that has been defined somehwere within the build process or
  • a variable defined in another build file within Jetspeed.

Installation dependent locations

The documentation refers to some common locations by the following names:

  • ${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 use to log into windows.
    ${user.home} is synonymous with ${USER_HOME} within this document.
  • ${CATALINA_HOME} : This refers to the location of your tomcat installation, e.g. c:/tomcat .

These are not used in the Jetspeed configuration but are merely shorthand notations to make the documentation more concise and precise.

Subversion (SVN)

Subversion (SVN) is used in the Jetspeed project to manage the source files. SVN is very similar to 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, the Subclipse plugin is available for SVN access.

2. Overview of the Jetspeed build Process

Setting up a custom portal development project using the binary distribution is a fairly simple process. At the end, you will you have a directory structure and set of files that will simplify building and deploying your own custom portal.

If you want to setup a Jetspeed portal application using Eclipse as your IDE, you should continue reading this page for background material but refer to Building a Jetspeed Enterprise Portal with Eclipse for the actual instructions on using Eclipse for Jetspeed 2 portal development.

Creating your own custom portal is very easy with the maven plugin provided by Jetspeed 2. The steps are:

  • Download and install the Jetspeed plugin
  • Use the plugin to download and generate the Jetspeed binary distribution.
  • Customize the properties files to reflect your database installation and local environment.
  • Prepare the Application Server
  • Build the portal
  • Start the Database Server(if required)
  • Initialize the Database
  • Deploy the default portal using your database
  • Test the default portal
  • Customize the default portal to include your logo and Portal name
  • Generate, deploy and test your custom Portal

The Jetspeed 2 maven-plugin defines default values for most of the properties you can set, but not all. As you customize the portal, you will override others.

3. Installation Steps

3.1 Download the Jetspeed Plugin

3.1.1 Set the maven remote repository lookup configuration

Now we're going to configure your ${user.home}build.properties file to give Maven the information that it needs to download the Jetspeed-2 maven-plugin. The base directory where you are going to build your portal needs to be specified to Maven as well as the the maven remote repository need to be configured properly in your ${USER_HOME}/build.properties : 
basedir = c:/myportal
maven.repo.remote = http://www.bluesunrise.com/maven/, http://www.ibiblio.org/maven/, \
http://dist.codehaus.org/, http://cvs.apache.org/repository
Note: the order in which the repositories are specified is significant!

3.1.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: 

							
maven -DartifactId=maven-jetspeed2-plugin -DgroupId=org.apache.portals.jetspeed-2 -Dversion=2.1.3 plugin:download
Note: you must set the version to the specific version you want to install, "2.1.3" is just an example.

3.2 Download the default Jetspeed portal project

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

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

3.3 Customize the properties files

You can fill in as much of the project information in the project.xml file as you want. This will depend on how you intend to use Maven as a project management tool and is beyond the scope of this document. The information in the project.xml file distributed with Jetspeed reflects the Jetspeed development project.

You can now customize the properties files to reflect your database installation and local environment.

The ${basedir}project.properties file provided by the Jetspeed developers includes all of the variables that are common to all portals based on Jetspeed. You should not have to change these.

The project properties are described in the Maven Properties Reference documentation. We have already filled in the value for basedir and maven.repo.remote in previous steps. You can fill in as much of the project information in the ${basedir}project.xml file as you want. This will depend on how you intend to use Maven as a project management tool and is beyond the scope of this document. The Maven site has all of the information that you need to use Maven successfully.

The configuration of your specific properties needs to be done before we can build the portal. Review the definition of the configuration properties described in Basic Configuration Parameters .

In the case of a binary build, the basic configuration properties can be placed in ${basedir}build.properties . A minimal custom portal configuration using the default Derby database can be something like: 

						
# required portal configuration properties          
org.apache.jetspeed.portal.home           = /home/myportal/
org.apache.jetspeed.portal.groupId        = myprojects
org.apache.jetspeed.portal.artifactId     = myportal
org.apache.jetspeed.portal.name           = My Test Portal
org.apache.jetspeed.portal.currentVersion = 1.0

If you are not using the Derby database that comes pre-configured in the ${basedir}project.properties file, you also need to define the database parameters in the ${basedir}build.properties file. Refer to the Database Configuration section for a description of the variables required.

3.4 Prepare the Application Server

Before running the portal, we need to prepare the Application server to run a Jetspeed portal. This consists of telling Jetspeed where the application server expects files to be placed and what authentication values are required to request service from the Application Server's management tools. There may also be modifications to the server configuration so be sure to read the Application server configuration documentation .

Verify that you made the Application Server changes suggested in the overview of the Getting Started documentation.

A minimal custom portal configuration using the Tomcat 5.5 Application Server could be something like: 

						
# required portal configuration properties          
org.apache.jetspeed.portal.home           = /home/myportal/
org.apache.jetspeed.portal.groupId        = myprojects
org.apache.jetspeed.portal.artifactId     = myportal
org.apache.jetspeed.portal.name           = My Test Portal
org.apache.jetspeed.portal.currentVersion = 1.0

# required application server properties
org.apache.jetspeed.server.home                      = ${CATALINA_HOME}/
org.apache.jetspeed.server.shared                    = ${org.apache.jetspeed.server.home}/shared/lib/
org.apache.jetspeed.deploy.war.dir                   = ${org.apache.jetspeed.server.home}/webapps/
org.apache.jetspeed.services.autodeployment.user     = j2deployer
org.apache.jetspeed.services.autodeployment.password = xxxxx
org.apache.jetspeed.catalina.version.major           = 5.5

3.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}): 

						
maven war:install

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.

3.6 Start the Database Server

You need to make sure that your database server is running. If you are not using the default Derby database, you need to make sure that it is running and that the user that will own the Jetspeed tables is setup and ready for use. Refer to the Database Configuration section for more information.

You need to have this database running during the deployment and while running the application server.

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.

3.7 Initialize the Database

The database's tables and initial data needs to be loaded prior to Jetspeed being deployed. The maven-plugin includes a number of goals that can be used to manage the database. The easiest way to load the tables and deploy the application is to run the j2:quickstart goal. 

						
cd ${org.apache.jetspeed.portal.home}
maven j2:quickStart
This can only be run once without a bit of a cleanup afterwards since it defines the tables and loads the data as part of starting the application. If you have an error and you want to run it again, you must make sure that the tables and data are cleaned out either by manually dropping the tables in the database or by using the j2:db.drop.production Maven goal.

The j2:quickstart currently only covers deploying to Tomcat 5 or Tomcat 5.5 application servers.

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: 

						
cd ${org.apache.jetspeed.portal.home}
maven j2:quickStart
Note: the maven-plugin documentation described other goals you can use to initialize the database.

3.8 Deploy the default portal using your database

The j2:quickstart task does this for you. If you have used another Maven goal to initialize the database, then you can deploy the portal by using: 

					
cd ${org.apache.jetspeed.portal.home}
maven j2:fullDeploy

The j2:fullDeploy goal currently only covers deploying to Tomcat 5 or Tomcat 5.5 application servers.

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

3.9 Test the default portal

The final step in getting the default portal running is starting up your Tomcat server. 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 your own portal application ( ${org.apache.jetspeed.portal.artifactId} ).

If you see a running Jetspeed portal, we have succeeded in getting the software installed and working.

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:

username password roles
admin admin admin, manager, user
manager manager manager, user
jetspeed jetspeed manager
user user user
tomcat tomcat

3.10 Customize the default portal to include your logo and Portal name

Now that the default portal is working we can try a small customization to test out the customization process. We are going to change the logo and portal name.

3.10.1 Creating your customization area

The first step is to create a directory to hold your customized files. This will help you to preserve your changes when you install new versions of jetspeed. Create a directory in the top level of the portal home. 

						
cd ${org.apache.jetspeed.portal.home}
mkdir customized

Make a copy of the build.properties file that you have already modified.

You may also want to make a directory to hold the original files before you modify them. This is not strictly requirred since you can always reload the distribution. However it might be handy to keep a copy for reference or to quickly get back to the state before you made changes.

3.10.2 Making some simple cuistomizations

We are going to change the logo and the portal name to test customization. You can make you own logo to replace the Jetspeed logo. Take a look at the ${basedir}/src/webapp/images/logo.png to get the size and to verify the background colour. Make your own logo or copy the testlogo.png file to your ${basedir}/customized directory.

3.11 Generate, deploy and test your custom Portal

					
cd ${org.apache.jetspeed.portal.home}
maven j2:fullDeploy

You can access the revised portal with your browser at: 


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

You should see the new name and the new logo on the front page.