Setting up and running Jetspeed 2 on JBoss

This page details installation and setup instructions for the Jetspeed 2 Enterprise Portal in JBoss. It also contains information on how Jetspeed 2 runs and behaves in JBoss and how the deployment of portlets works in this environment - all from the point of view of someone completely new to Jetspeed 2 (and also somewhat new to JBoss). Please feel free to clarify any misunderstandings on the author's part.

Jetspeed 2 contains official installation instructions and instructions on deploying it in Tomcat at http://portals.apache.org/jetspeed-2/getting-started.html and the page here is intended as a supplement to http://wiki.apache.org/portals/Jetspeed2/JbossHowTo.

The information on this page is applicable to at least Jetspeed 2 M1 and JBoss 3.2.3, 3.2.5, 3.2.6, 4.0.1 with additional notes denoted M2: for Jetspeed 2 M2 and JBoss 4.0.1.

Installing Jetspeed 2

Building Jetspeed 2

The build instructions given at http://portals.apache.org/jetspeed-2/getting-started.html can be followed in the same way for points 1 to 4, considering the following additional notes:

Ensure your system meets all the prerequisites listed, including Tomcat. While it is probably possible to build Jetspeed 2 without Tomcat, its presence simplifies the procedure by being able to follow the listed steps.

M2: is available as a binary distribution as well, in which case no Maven and no build is required.

Maven Installation

To err on the safe side, you should have the following environment variables set up (Windows examples):

  • HOME C:\Documents and Settings\someuser JAVA_HOME C:\j2sdk1.4.2_06 MAVEN_HOME C:\maven MAVEN_REPO C:\Documents and Settings\someuser\.maven\repository Path add C:\maven\bin USER_HOME C:\Documents and Settings\someuser

If you experience problems during the Jetspeed 2 build, add the following lines to the build.properties:

  • maven.repo.remote=http:'//www.bluesunrise.com/maven,http:'//www.ibiblio.org/maven,http:'//dist.codehaus.org,http:'//cvs.apache.org/repository maven.tomcat.home=C:/tomcat ... or different, depending on where you put Tomcat maven.tomcat.version.major=5

Build properties, configuration, and building Jetspeed 2

Make sure you set the build property org.apache.jetspeed.catalina.version.major = 5 since JBoss 3.2.5 and up use Tomcat 5.0.26 (and up). Set the value to 4 for JBoss 3.2.3.

Follow steps 3 and 4 as per the instructions, building Jetspeed 2 using your installation of Tomcat. Before running the command maven allClean allBuild, set your command window's buffer to at least 5000 lines, so you can check for errors afterwards should it be necessary (or redirect it to a file).

Deploying Jetspeed 2

After following steps 1 to 4 of the "Getting Started with Jetspeed 2" instructions, Jetspeed 2 is completely ready and deployed in Tomcat. You can use this point as a checkpoint and see whether you can see the default Jetspeed home page at http://localhost:8080/jetspeed with all portlets displaying correctly (start your Tomcat first).

At this stage, Jetspeed 2 is not yet deployed in JBoss, but it is built, essentially resulting in the files (inside the Tomcat directory):

  • \shared\lib\pluto-1.0.1-rc1.jar (M2: pluto-1.0.1-RC2-PATCHED.jar has to be gotten from binary M2 distribution) \shared\lib\portals-bridges-common-0.1.jar (M2: portals-bridges-common-0.2.jar) \shared\lib\jetspeed-commons-2.0-M1.jar (M2: jetspeed-commons-2.0-M2.jar) \shared\lib\jetspeed-api-2.0-M1.jar (M2: jetspeed-api-2.0-M2.jar) \shared\lib\portlet-api-1.0.jar \webapps\jetspeed.war \webapps\jetspeed\WEB-INF\deploy\jetspeed-layouts.war \webapps\jetspeed\WEB-INF\deploy\struts-demo.war \webapps\jetspeed\WEB-INF\deploy\php.war \webapps\jetspeed\WEB-INF\deploy\perl.war \webapps\jetspeed\WEB-INF\deploy\security.war \webapps\jetspeed\WEB-INF\deploy\demo.war \webapps\jetspeed\WEB-INF\deploy\pam.war \webapps\jetspeed\WEB-INF\deploy\jsf-demo.war \webapps\jetspeed\WEB-INF\deploy\rss.war

M2: Additional portlet war files: palm.war, jpetstore.jar, jsf-demo-myfaces.war

These files can also be found in the respective target directories inside the Jetspeed 2 source.

If these files are available from a previous Jetspeed 2 build (or a binary distribution), then no rebuilding (maven allClean allBuild) is necessary.

Setting up Jetspeed 2 in JBoss

Database

If you have not done so already (see 2.1.2), start the production server with the command maven start.production.server (M2: or the start-database script of a binary distribution) in a command window and leave it running. It never needs to be shut down again (e.g. when redeploying or even changing JBoss versions).

If you have not done so already (see 2.1.2), run the command maven quickStart. This initialises the database. This command never needs to be rerun.

Initial Setup of JBoss/Jetspeed 2

First, make sure JBoss is not running.

The procedure at http://wiki.apache.org/portals/Jetspeed2/JBossHowTo can be largely followed with a few notes and adjustments (the instructions on that web page were for an alpha release as opposed to Milestone 1):

  1. Unzip the jetspeed.war (can be found in Tomcat's webapps dir or in the portal/target dir of the Jetspeed 2 source (after a build of course) into a directory called jboss/server/default/deploy/jetspeed.war - inside this directory you will then find a directory WEB-INF/deploy.
  2. Copy the following 5 jars (can be found in Tomcat's shared\lib dir) into your JBoss' server/default/lib directory

pluto-1.0.1-rc1.jar (M2: pluto-1.0.1-RC2-PATCHED.jar)

portals-bridges-common-0.1.jar (M2: portals-bridges-common-0.2.jar)

jetspeed-commons-2.0-M1.jar (M2: jetspeed-commons-2.0-M2.jar)

jetspeed-api-2.0-M1.jar (M2: jetspeed-api-2.0-M2.jar)

portlet-api-1.0.jar

  1. Copy the JBoss datasource definition jetspeed-ds.xml from the Jetspeed 2 source's /portal/src/resources directory to your JBoss' server/default/deploy directory.
  2. Delete JBoss' server/default/lib/hsqldb.jar file and instead copy Jetspeed's hsqldb-1.7.1.jar file into the server/default/lib directory.
  3. Move the following jars out of jetspeed.war/WEB-INF/lib into your JBoss' server/default/lib directory:

commons-logging-1.0.3.jar

log4j-1.2.8.jar

xerces-2.3.0.jar

xml-apis-2.0.2.jar

  1. In jetspeed-spring.xml, locate the bean with the id="org.apache.jetspeed.tools.pamanager.servletcontainer.ApplicationServerManager". Comment out the current bean definition, which is targeted at Tomcat 4/5, and uncomment the bean definition below that one, which is targeted at JBoss.

*M2:*The jetspeed-spring.xml may not contain the JBoss ApplicationServerManager definition, so here it is (copy/paste into the jetspeed-spring.xml):

<bean id="org.apache.jetspeed.tools.pamanager.servletcontainer.ApplicationServerManager"
      class="org.apache.jetspeed.tools.pamanager.servletcontainer.JBossManager"
      init-method="start" />
  1. You can now start JBoss - if you previously deployed portlets (e.g. in Tomcat), they may still be registered and have to be un-deployed first and then re-deployed (see 4.1).
  2. For the demo portlets to show up you will need to copy the following 9 wars into your JBoss' server/default/deploy/jetspeed.war/WEB-INF/deploy directory (created when you unzipped the jetspeed.war file in the previous step):

jetspeed-layouts.war

struts-demo.war

php.war

perl.war

security.war

demo.war

pam.war

jsf-demo.war

rss.war

M2: Additional portlet war files: palm.war, jpetstore.jar, jsf-demo-myfaces.war

These files can be found in Tomcat's webapps/jetspeed/WEB-INF/deploy directory or in their respective target directories in the Jetspeed 2 source (after a build of course). For M1, keep copies of these files handy!

Note: To get the locale selector and login portlet to display, you have to change the web.xml inside /WEB-INF in the demo.war to change the role name in the auth-contraint from tomcat to *

  <security-constraint>
    <web-resource-collection>
      <web-resource-name>HTTPBasicDemo</web-resource-name>
      <url-pattern>/sso-basic/*</url-pattern>
    </web-resource-collection>
    <auth-constraint>
      <role-name>*</role-name>
    </auth-constraint>
  </security-constraint>

Put the modified demo.war (with the changed web.xml) into your handy copy of the 9 portlet war files and also replace the demo.war file in your JBoss' server/default/deploy/jetspeed.war/WEB-INF/deploy directory with the just modified one.

Login Portlet

JBoss does not have a tomcat-users.xml file. Instead, look inside the server/default/conf/login-config.xml file. In there, you will find an application policy "other", which is used if the realm (= security domain) "jetspeed" is not found. This application policy uses the org.jboss.security.auth.spi.UsersRolesLoginModule as a default, which is driven by the two files "users.properties", and "roles.properties" in the directory server/default/deploy/http-invoker.sar/invoker.war/WEB-INF/classes.

To be able to login, you have to add the users and roles that exist in the HSQL database (populated by the init db script) to these two files.

Running Jetspeed 2 in JBoss & Deployment

Important Note for M1: If you started Tomcat at the end of deploying Jetspeed 2 into it, the portlets have already been registered in the database, in which case they have to be un-deployed, and re-deployed while running JBoss. See the following section for how this works.

Auto Deployment

Jetspeed 2 has an auto-deployer, which picks up additions, deletions or changes to files in its deploy directory (jetspeed.war/WEB-INF/deploy directory inside the web servers' deploy directory, e.g. server/default/deploy/jetspeed.war/WEB-INF/deploy). The directory contains the portlet's war files. If you copy a file into the directory (while JBoss and Jetspeed 2 are running), the portlet gets deployed. If you delete a file from the directory, the portlet gets un-deployed.

As a rule, only add/change/delete portlet war files in Jetspeed 2's deploy directory while JBoss / Jetspeed 2 are running!

The auto-deployer writes to the log file jetspeed.war/logs/deployment.log - watch this file to see what the auto-deployer is doing and always wait for it to finish.

M2: The auto-deployer now copies the .war files from Jetspeed 2's deploy directory to JBoss' deploy directory and afterwards deletes them from Jetspeed 2's deploy directory (which can be thought of aas a staging directory). Also, it is completely stable as far as shutting down/starting up JBoss is concerned, solving the deployment/un-deployment issues described in the sections below!

Deploying

The deployment process extracts the war files from Jetspeed 2's deploy directory into JBoss' deploy directory. For example, the file server/default/deploy/jetspeed.war/WEB-INF/deploy/demo.war gets deployed by extracting its contents into a (automatically created) directory server/default/deploy/demo.war. In this example, a directory server/default/deploy/demo (without the .war extension) is also created, but remains empty.

If a portlet is still registered (e.g. from previously running a different server and not un-deploying before shutting down the server), copying a file into Jetspeed 2's deploy directory may not cause deployment (you can see this by a message in the deployment.log saying that a portlet application has already been registered and that it is skipping initial deployment.

Un-deploying

Deleting a war file from Jetspeed 2's deploy directory undeploys and unregisters the portlet. It does not delete the corresponding, automatically created directories in JBoss' deploy directory - this must be done manually.

Always un-deploy every portlet (and wait for the auto-deployer to finish un-deploying) before shutting down JBoss! Otherwise Jetspeed 2 seems to get confused as to what is deployed/registered.

Re-deploying

Overwriting a war file in Jetspeed 2's deploy directory re-deploys it, but only while JBoss / Jetspeed 2 is running (see 4.2).

Deployment of portlets inside .ear files

Deployment of portlets inside .ear files does not seem to be directly supported, at least at the moment. Looking at the source code, it expects extensions .war, .jar, or .zip, and more importantly, looks for files such as portlet.xml in /WEB-INF. In an .ear file, this would be in the war file inside the ear file and therefore not be found.

JBoss / Jetspeet 2 Shutdown and Startup

The following procedure is the only procedure found to keep using the same JBoss installation in a repeatable way for M1:

Precondition: A working JBoss / Jetspeed 2 is running (if no JBoss is running, check whether you need to do step 3 and then continue with step 4 to 6).

Shutdown

  1. Un-deploy all portlets by deleting all war files from Jetspeed 2's deploy directory. If this is not done, you will either get exceptions then next time JBoss is started (if 2. is not done either), or you will get empty portlets (if this step was not done, but step 2 was done).
  2. Shutdown JBoss.
  3. Delete all automatically created .war-directories in JBoss' deploy directory (e.g. for the portlet in demo.war, the directory server/default/deploy/demo.war) and all their contents. If this is not done, you will get exceptions the next time JBoss is started.

You now have a clean, shut down state with no portlets deployed or registered.

M2: Simply shut down JBoss - when you start it up again, all portlets will still be registered and deployed.

Startup

  1. Start JBoss and wait for it to finish (for M1, the last message stating that JBoss has started can be found in the file server/default/deploy/jetspeed.war/logs/jetspeed.log).
  2. Go to or refresh http://localhost:8080/jetspeed - this will show an error 500. If this is not done, you will get a blank Jetspeed home page after deployment of the portlets. M2: This step is not necessary anymore.
  3. Deploy the portlets by copying the (e.g. 9 example) portlet war files into the Jetspeed 2 deploy directory and wait until the auto-deployer has finished deploying them (see jetspeed.war/logs/deployment.log).

You now have a working, running JBoss / Jetspeed 2.

Troubleshooting

Empty Jetspeed 2 home page

If you have a blank page, follow steps 1 to 6 in the section 4.2.

Empty portlets

If you have empty portlets showing on the Jetspeed 2 home page, the reason is that it cannot find the corresponding .war-directories in the JBoss deploy directory.

In this case, un-deploy the portlets (while the server is running), go to the Jetspeed home page (-> error 500) and re-deploy the portlets.

Many exceptions in the command prompt window during JBoss startup

This is typically caused because there are still previously automatically created .war-directories for portlets in the JBoss deploy directory.

In this case, shut down JBoss, delete the .war-directories and try again.

ZipExceptions in jetspeed.log

If you get

WARN org.jboss.deployment.JARDeployer - Failed to add deployable jar: file:_'_'/java.util.zip.ZipException: error in opening zip file

in the jetspeed.log, then set JBoss' JVM heap size to 1024m (the max.). However, even then they can occur, but do not seem to cause any harm.

Cannot login in login portlet

Make sure you have added the users from the table SECURITY_PRINCIPAL (e.g. FULL_PATH "/user/admin") and the corresponding password from the table SECURITY_CREDENTIAL (e.g. VALUE "password") as a name/value pair line (e.g. "admin=password") to the "users.properties" file, and a corresponding line of name/comma-separated value pair (e.g. "admin=admin,manager,user") to the "roles.properties" file (see 3.2.1).

There are some issues with authentication with JBoss 3.2.3, since it uses Tomcat version 5.0.26, which is lower than 5.0.28 - see http://wiki.apache.org/portals/Jetspeed2/Tomcat5JassIssues.

Miscellaneous

To get rid of the following warning in the jetspeed.log:

org.apache.catalina.startup.ContextConfig - Missing application web.xml, using defaults only [StandardEngine][jboss.web].StandardHost[localhost].StandardContext[/demo]

put the demo portlet's web.xml into the empty demo-directory in the JBoss deploy directory (not the demo.war-directory, and not into any sub-directory inside the demo directory).

  • No labels