It is expected that the user is familiar with both the Apache Maven project tool and the Apache Ant build tool.
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.
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.
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.
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.
Property | Description | Default 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 |
The following properties all specify a subfolder of the ${org.apache.jetspeed.portal.home}
location as defined above.
Property | Description | Default 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} |
Note: The maven-plugin currently only supports the Tomcat Server 5.0.x or 5.5.x
Property | Description | Default 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 |
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:
Property | Description | Default 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 |
org.apache.jetspeed.production.database.url
| The jdbc connection url | jdbc: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 name | org.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 |
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:
org.apache.jetspeed.portal.home
property is required from the set of required portal
configuration properties.
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:
${org.apache.jetspeed.services.autodeployment.user}
and
${org.apache.jetspeed.services.autodeployment.user}
as described above.
Now we're going to configure, setup and build a new custom portal application using the Jetspeed-2 maven-plugin.
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
:
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:
Once you have the maven-plugin installed and set properties as needed, generate a default portal configuration using the plugin as follows:
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.
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.
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.
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:
The Jetspeed 2 project.properties uses this property to define the required
org.apache.portal.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 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
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:
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
.
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.
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.
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:
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/jetspeedor replace "jetspeed" in the above url with the name of you own portal application (
${org.apache.jetspeed.portal.artifactId}
).
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 |