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

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

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
					

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.

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

					

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.

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.

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.

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
					

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:

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 .

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

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:

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.

You can access the revised portal with your browser at:

						
							http://localhost:8080/jetspeed
						
					

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