1. Naming Conventions and Basic Assumptions (deprecated)

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.

2. Jetspeed build and maven-plugin Properties

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

This property is not needed/used for anything else.
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 Derby 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):
  • derby
  • hsql (hypersonic)
  • oracle (oracle)
  • mysql (mysql)
  • postgres (postgresql)
  • mssql (mssql)
  • sapdb (sapdb)
  • db2 (db2)
derby
org.apache.jetspeed.derbydatabase.path Path to where the embedded derby database will be created/expected/tmp
org.apache.jetspeed.production.database.url The jdbc connection urljdbc:derby:${org.apache.jetspeed.derbydatabase.path}/productiondb;create=true
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.apache.derby.jdbc.EmbeddedDriver
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 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
					
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.

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 :

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

						
maven -DartifactId=maven-jetspeed2-plugin -DgroupId=org.apache.portals.jetspeed-2 -Dversion=2.1.3 plugin:download
					
Note: you can set the version flag to the specific version you want to install, 2.1.3 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:

						
maven j2:portal.genapp
					
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}):

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

						
# required Jetspeed 2 portal configuration property for building from the source
org.apache.jetspeed.project.home = /home/apache/jetspeed-2/
					
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 :

						
org.apache.jetspeed.portal.home = ${org.apache.jetspeed.project.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 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
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:

						
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.

6. Deploy and Run

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

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
admin admin admin, manager, user
manager manager manager, user
jetspeed jetspeed manager
user user user
tomcat tomcat