Apache Cocoon is a pipelined rendering engine for website content. It works very well with the Apache Web Server and the Tomcat servlet container.

This page describes the installation of the Cocoon engine. Rather than describing what you're doing, I'll show you exactly what to do. You'll do the work of acquiring and installing software from within the Terminal application, using a web browser only for the testing steps.

I assure you that the UNIX commands I'll direct you to invoke have been taken directly from a Terminal window - these are the commands I just used to do a clean install - rather than having been composed after the fact. This is *exactly* what worked for me. I've taken pains to choose forms of the commands which should make sense to you even if you're new to UNIX.

Get and install the Apache web server

Follow the instructions on installing the Apache Web Server and come back here. We'll be waiting.

Get and install the Tomcat servlet container

Follow the instructions on installing the Tomcat servlet container and come back here. We'll be waiting.

Create a place in which to work

We'll be downloading software from the Internet; here's how we create a workspace for ourselves.

% mkdir ~/install ; cd ~/install

Get and build Apache Cocoon

Instead of using the link I show (which points to the main apache.org site) please use one of the many Apache mirror sites. Thank you.

% cd ~/install % curl -# -O http://www.apache.org/dist/cocoon/cocoon-2.1.6-src.tar.gz ######################################################################## 100.0% % gnutar zxf cocoon-2.1.6-src.tar.gz % cd cocoon-2.1.6/ % ./build.sh % ./build.sh war

I set JAVA_HOME to /Library/Java/Home/; this location remain constant as Apple updates Java. You may wish to add this to the .login file in your home directory. Then you will have JAVA_HOME set each time you start a Terminal window. I use tcsh as my shell; if you're using default bash shell the syntax will be:

JAVA_HOME=/Library/Java/Home export JAVA_HOME

and the file to edit would be .bash_profile.

Install Apache Cocoon

Things have changed slightly since I documented the Tomcat install procedure. There's now a link which always points to the correct Tomcat install, so my environment set-up looks like this:

% setenv JAKARTA_HOME /usr/local % setenv CATALINA_HOME ${JAKARTA_HOME}/tomcat

CATALINA_HOME is what used to be called TOMCAT_HOME. Now I continue with the install. Start by shutting Tomcat down.

% sudo ${CATALINA_HOME}/bin/shutdown.sh % cp ./build/cocoon-2.1.6/cocoon.war ${CATALINA_HOME}/webapps/ % mv ${CATALINA_HOME}/common/endorsed/xercesImpl.jar ~/install/old-versions/ % cp blocks.properties local.blocks.properties

Edit the file ${CATALINA_HOME}/bin/catalina.sh and add the line

CATALINA_OPTS="-Djava.awt.headless=true"

under the first occurence of the string "CATALINA_OPTS". You may also allocate more memory; add something like -Xmx192M to the CATALINA_OPTS.

Make a copy of the file ${CATALINA_HOME}/conf/tomcat-users.xml and edit the original, giving it a full description of roles, as in:

<?xml version='1.0' encoding='utf-8'?>
<tomcat-users>
  <role rolename="tomcat"/>
  <role rolename="role1"/>
  <role rolename="manager"/>
  <role rolename="admin"/>
  <user username="tomcat" password="password" roles="tomcat,admin,manager"/>
  <user username="role1" password="tomcat" roles="role1"/>
   <user username="both" password="tomcat" roles="tomcat,role1"/>
</tomcat-users>

Some of the libraries we've just built must be put into the shared environment. I've heard several stories about what the right thing to do might be, ranging from the "do it all" school of thought

NOTE: I don't actually do this step! % sudo cp ./lib/endorsed/*.jar ${CATALINA_HOME}/common/endorsed/

to the "move only what we need" school, shown here with a safety-first backup of existing libraries:

% mkdir ./BACKUP_LIBS % sudo mv ${CATALINA_HOME}/common/endorsed/{jakarta-bcel-*.jar,jakarta-regexp-*.jar,xalan-*-dev-*.jar,xercesImpl-*.jar,xml-apis*.jar} ./BACKUP_LIBS/ % sudo cp ./lib/endorsed/{jakarta-bcel-*.jar,jakarta-regexp-*.jar,xalan-*-dev-*.jar,xercesImpl-*.jar,xml-apis*.jar} ${CATALINA_HOME}/common/endorsed/

I've also heard that one should add any avalon-*.jar files to this list. In poking around I I found some files in ${CATALINA_HOME}/webapps/cocoon/WEB-INF/lib/ but I don't know what to do about them.

% find ${CATALINA_HOME} -name *xerces* -o -name *xalan* /usr/local/jakarta-tomcat-4.1.31/common/endorsed/xercesImpl-2.6.2.jar /usr/local/jakarta-tomcat-4.1.31/webapps/cocoon/WEB-INF/lib/xalan-2.6.1-dev-20041008T0304.jar /usr/local/jakarta-tomcat-4.1.31/webapps/cocoon/WEB-INF/lib/xercesImpl-2.6.2.jar

And if we're using MySQL as our database let's add the latest connector. Unfortunately you'll have to visit

http://dev.mysql.com/downloads/connector/j/

to find a link to a mirror. You'll also have to use Stuffit Expander (when you're on the Macintosh) because gnutar reports a "lone zero block" when uncompressing this file. Once you have this difficult beast opened

% cp mysql-connector-java-3.1.6.tar ${CATALINA_HOME}/common/lib

Start and test Cocoon

We must now start Tomcat once again.

% sudo ${CATALINA_HOME}/bin/startup.sh

When you point your web browser to http://localhost:8080/ you should see the Tomcat main page (shown previously). Next try http://localhost:8080/cocoon/, and you should see the following

Clean up after yourself

When all done we may remove the install directory.

% cd ~ % rm -rf ~/install

You might want to - okay, you really ought to - jump up one level, to see how this fits into the big picture of developing and deploying web-based applications (and to see what other tools I've installed to work with this).

NOTES AND COMMENTS / NOT YET COMPLETED

- Andy said to disable in local.build.propertiesdisable blocks: JMS, hsqldb, slides, petstore. Current deployment doesn't have top-level blocks ready for uncommenting. Still need?