Getting a Hippo Portal up and running

This week I started on a project where we'll be using Hippo Portal and repository for an online webshop application. I've never before worked with Hippo so it's a chance to get to know something new. The Hippo products in itself are open source and backed by a commercial company by the same name Hippo BV. Technically there are three products: a CMS, a repository and the portal. The Hippo Portal is based on Apache's JetSpeed.
So yesterday I started by trying to install Hippo Portal and encountered a few issues along the way... the Hippo portal homepage contains a setup document detailing how to install hippo repository, hippo portal as well as maven 1.0.2. All fine. Next we try to deploy a Hello World portal as detailed here. The first action (maven hp:create-portal-project) fails for two reasons:

1. maven cannot find an XSLT transformer, solved by copying xalan-2.4.1.jar into /lib/endorsed
2. on my Windows machine I had to tweak the default project.properties by replacing backslashes in the file project.properties by forward slashes like so:
   nl.hippo.portal.server.home=c:/dev/apache-tomcat-5.5.23
   and
   nl.hippo.portal.jdbc.drivers.path=c:/dev/apache-tomcat-5.5.23/common/endorsed/mysql-connector-java-3.1.12.jar
   (and also had to copy the mysql driver into the said directory)

Now I could execute the create-portal-target and proceed by creating a HelloWorld portlet and deploying the portal + HelloWorld portlet + a jetspeed demo portlet into a tomcat 5.5.23 instance. Tomcat starts up fine but when I navigate to the url http://preview.localhost:8080/gettingstarted as described in the doc, an error message appears. In the Hippo forum I found the hint to add an entry to the C:\WINDOWS\SYSTEM32\DRIVERS\ETC\HOSTS file like so:

127.0.0.1 preview.localhost

Still an error message. Luckily after some browsing through the remainder of the documentation I found out that I needed a sitemap.xml document to be present in the hippo repository, specifying the basic structure of my portal. So I created a sitemap.xml identical to the one specified here and uploaded it to the hippo repository. This sitemap.xml contains a reference to the document /content/documents/home.xml which does not exist in the repository. I did find a document called /content/documents/test.xml so I changed the reference in sitemap.xml from home.xml to test.xml and uploaded sitemap.xml it for the second time to the repository.
This all seemed fine and logical but the portal still failed to display anything interesting. So I changed the debug level in /gettingstarted/WEB-INF/conf/Log4j.properties from ERROR to DEBUG and discovered in /gettingstarted/logs/jetspeed.log that something was wrong with a layout. The origin of the problem was that the /gettingstarted-portal/src/webapp/WEB-INF/pages/__site1/home.psml contains a reference to a layoutType called default. Based on this 'default' value Jetspeeds looks in the directory /gettingstarted-portal/src/webapp/decorations/layout/default for a file called default-layout.vm and this file was empty. I added the following to default-layout.vm:

<table border="0" cellspacing="10" width="100%">
<tbody><tr>
<td valign="top">#includeFragment($myPage "home-HelloWorld")</td>
<td valign="top">#includeFragment($myPage "home-PickANumberPortlet")</td>
</tr>
</tbody></table>

Wow. So after all of this the portal did work and now I can proceed trying to understand what happened and how the various config files are related to each other and the repository. One final note: along the way I also changed one other config file although I'm not sure if this change was required to get the portal working. At the end of the project.properties file in /gettingstarted-portal I uncommented the last two lines:

nl.hippo.portal.jetspeed.psml.basedir=${nl.hippo.portal.home}/src/webapp/WEB-INF/pages
nl.hippo.portal.jetspeed.psml.context=site1

to make sure JetSpeed would look in the ../pages/__site1/ directory to find the psml files.