Source 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 ${ some_variable }. This may signify a setting in Jetspeed or may represent a setting within your environment. Properties files are also capable of specifying variables within them.

For example, ${org.apache.jetspeed.server.home} references either a property defined further up in the properties file, a variable 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 use to log into windows.
  
  ${USER.HOME} is synonymous with ${USER_HOME} within this document.
• ${CATALINA_HOME} : This is the location of your tomcat installation, e.g. c:/tomcat .

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

Maven Setup

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 that it downloads when you run your builds. This is also were Maven puts your jars and wars that you build. They will be stored in a directory structure that has 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. Jar and war files will also be created in your project in the /target directory.

Required Portal Configuration Properties

Optional Portal Configuration Properties

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

Required Application Server Properties

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

Optional Database Server Properties

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

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

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

# 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
					

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 :

						
maven.repo.remote = http://www.bluesunrise.com/maven/, http://www.ibiblio.org/maven/, \
                    http://dist.codehaus.org/, http://cvs.apache.org/repository
					

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:

						
maven -DartifactId=maven-jetspeed2-plugin -DgroupId=org.apache.portals.jetspeed-2 -Dversion=2.1.3 plugin:download
					

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:

						
maven j2:portal.genapp
					

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

						
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.

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:

						
# required Jetspeed 2 portal configuration property for building from the source
org.apache.jetspeed.project.home = /home/apache/jetspeed-2/
					

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

						
org.apache.jetspeed.portal.home = ${org.apache.jetspeed.project.home}
					

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

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:

						
cd ${org.apache.jetspeed.project.home}
maven initMavenPlugin
					

Optional: start the HSQLDB test database first

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

						
cd ${org.apache.jetspeed.project.home}
maven j2:start.test.server
					

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:

						
cd ${org.apache.jetspeed.project.home}
maven allClean allBuild
					

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

						
cd ${org.apache.jetspeed.project.home}
maven -Dmaven.test.skip=false allClean allBuild
					

You are now ready to deploy the Jetspeed 2 Portal.

Optional: start the HSQLDB production database first

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

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

						
cd ${org.apache.jetspeed.portal.home}
maven j2:start.production.server
					

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:

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

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

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: