HOWTO: Set up Cocoon in RedHat 8.0

Introduction

This is a summary of the steps I've taken to set up Cocoon on a vanilla RedHat 8.0 box, more for my own future reference than as a compreehensive setup guide. Most of this is easily applicable to RedHat 9.0 or Fedora, but I haven't gotten around to fully test it yet.

Before going through the rest of this HOWTO, bear in mind that there are alternatives such as Az which will get you a generic install of Apache, Tomcat and Cocoon. The proper Geek way, using wget and vi will give you full control over your install, of course.

Files Needed:

j2sdk-1_4_1_01-linux-i586-rpm.bin (The Java 2 SDK, downloaded from Sun's Java Site)
tomcat-4.1.18-LE-jdk14.tar.gz (The Tomcat servlet engine)
cocoon-2.0.4-vm14-bin.tar.gz (Cocoon for Java 1.4)

Setting up the JDK and environment variables

Easy. just sh j2sdk-1_4_1_01-linux-i586-rpm.bin, accept the agreement, and rpm -ivh the resulting file.

To make sure the rest of the packages can find the Java install, we need to set the JAVA_HOME environment variable. Under RedHat, this is best done by adding it to the global profile like this:

cd /usr/java/
ln -s j2sdk1.4.1_01/ jdk1.4
cd jdk1.4
echo "export JAVA_HOME=`pwd`" >> /etc/profile.d/java.sh

Setting up Tomcat

Pretty much the same, really, since the only thing you need to do is unpack the distribution where you think best and set the CATALINA_HOME environment variable:

cd /usr/java
tar -zxvf /tmp/downloads/tomcat-4.1.18-LE-jdk14.tar.gz
ln -s jakarta-tomcat-4.1.18-LE-jdk14/ jakarta-tomcat
cd jakarta-tomcat
echo "export CATALINA_HOME=`pwd`" >> /etc/profile.d/java.sh

Testing is just as simple:

bash - read in the new .profile
$CATALINA_HOME/bin/startup.sh
Wait. Trust me, it takes it own damn time to get started...
Go to http://localhost:8080

Setting up Cocoon

This is pretty much limited to moving the cocoon.war file into the tomcat/webapps directory, but here are the steps by the book:

$CATALINA_HOME/bin/shutdown.sh - you don't really have to restart Tomcat, but this is simpler.
cd /usr/java
tar -zxvf /tmp/downloads/cocoon-2.0.4-vm14-bin.tar.gz
cp cocoon-2.0.4/cocoon.war jakarta-tomcat/webapps/
$CATALINA_HOME/bin/startup.sh
Wait again. Marvel at the added startup time while Cocoon does its thing.
Go to http://localhost:8080/cocoon/

Setting up Apache (optional)

You can also proxy the requests through Apache+mod_proxy, integrating Cocoon within your URL namespace. By doing this you don't have to open an extra port (8080) on your firewall, and you can later benefit from Apache's added control over authentication, URL rewriting (mod_rewrite) and whatnot:

vi /etc/httpd/conf/httpd.conf

<IfModule mod_proxy.c>
  ProxyPass         /cocoon  http://localhost:8080/cocoon # Ver [mod_proxy+mod_rewrite]
  ProxyPassReverse  /cocoon  http://localhost:8080/cocoon
  ProxyRequests Off # make sure no one else uses us as "normal" proxy
  <Directory proxy:*>
    order deny,allow
    AuthType Basic
    AuthName Cocoon Access
    AuthUserFile /etc/httpd/passwd
    require valid-user
#   You can use this for IP based authentication
#   order allow,deny
#   allow from 192.168.0.0/16
  </Directory>
</IfModule>

htpasswd -c /etc/httpd/passwd cocoon
enter password for user cocoon
/etc/rc.d/init.d/apache restart
You have hide everything but the /cocoon on your Tomcat webserver
Go to http://localhost/cocoon/
Now you have access control to your Tomcat/Cocoon applications

You're done.

Note: The default install as outlined here is insecure, i.e., it can both be accessed from outside your box on port 8080, and uses all the default settings. If you deploy one of these, learn how to bolt it down properly.

These instructions worked for me. There is no guarantee (express or implied) that they'll work for you, nor will I necessarily be able to help you if anything goes wrong. There are also no instructions for Mac OS X yet. I was supposed to worry about that as soon as Apple had a stable Java 1.4 release, but I stopped fiddling with Cocoon in the meantime.

Tao of Mac