Installing Cocoon 1.8.2 under FreeBSD

Cocoon should be installed from the ports system, as trying to piece it together using incompatible releases of the Apache XML Project's tools will almost certainly fail.

It is certainly preferable to be able to test the installation as it proceeds from the machine onto which you are installing. The default configuration of Apache will not allow the server information and status pages to be viewed outside the localhost. JServ's default configuration similarly disallows access to its status page outside of the localhost. (Interestingly, Cocoon does allow its status page to be world-viewable by default.) X-Windows, or even console facilities like a monitor and keyboard, however, are not required. Even lynx will be sufficient to demonstrate that installation is proceeding. The default configurations can be changed later to allow the appropriate outside access.

Installation of Apache from the ports is relatively unproblematic. The latest version of Apache will probably work, though this document was written when the current version was Apache 1.3.20. As root, execute the following:

# cd /usr/ports/www/apache13/
# make
# make install

Some customisation of the configuration file /usr/local/etc/apache/httpd.conf will be required. Getting Apache running is beyond the scope of this article, and is well covered elsewhere.

At the end of installation, and after modification of httpd.conf, start Apache as root:

# /usr/local/sbin/apachectl start

The parent Apache process will run as root, and all its children will run as the user and group specified in the User and Group directives in httpd.conf. Test Apache by pointing a broswer at the localhost:

# lynx http://localhost/

A default Apache page should be displayed at this point.

Installation of Apache JServ from the ports is relatively unproblematic. As root, execute the following:

# cd /usr/ports/www/apache-jserv/
# make
# make install

JServ's dependencies include the Java 1.1.8 JVM, so the installation may take some time if Java is not yet installed on your machine. At the end of make install, the following advice is given:

o Touch /var/log/jserv.log with write permission for owner of httpd.
o Add "Include etc/apache/jserv/jserv.conf" into httpd.conf to
activate mod_jserv.

To do this, execute the following as root:

# touch /var/log/jserv.log
# chown nobody.nobody /var/log/jserv.log

This assumes that httpd will run as user nobody, group nobody which is the default. If you have chosen to run httpd as another user or group, adjust the chown command accordingly. Restart Apache as root:

# /usr/local/sbin/apachectl restart

Test that JServ is working:

# lynx http://localhost/jserv/

There are a few additional traps in installing Cocoon, however it is predominantly a matter of making the port and following the additional instructions. As root:

# cd /usr/ports/textproc/cocoon/
# make
# make install

The instructions given by the Makefile at the end of make install should be followed (additional comments are below each of the Makefile's instructions):

(1) Add following line into jserv.conf.

"ApJServAction .xml /servlets/org.apache.cocoon.Cocoon"

This line is commented out in the default /usr/local/etc/apache/jserv/jserv.conf, and the '#' comment character simply needs to be removed from the front of the line.

(2) Add following lines into jserv.properties.

"wrapper.classpath=/usr/local/share/java/classes/cocoon.jar"
"wrapper.classpath=/usr/local/share/java/classes/xerces_1_2.jar"
"wrapper.classpath=/usr/local/share/java/classes/xalan_1_2_D02.jar"
"wrapper.classpath=/usr/local/share/java/classes/fop_0_15_0.jar"

Unfortunately, cocoon.jar is mis-spelled in the default installation of /usr/local/etc/apache/jserv/jserv.properties as Cocoon.jar, so don't simply uncomment the line—you must correct the spelling. The entries for xerces_1_2.jar, xalan_1_2_D02.jar and fop_0_15_0.jar are not in the default version of jserv.properties and should be added as instructed above, though without quotation marks. Additionally, although this does not appear to be documented anywhere, Cocoon requires the following additional .jar files in its classpath:

wrapper.classpath=/usr/local/share/java/classes/w3c.jar
wrapper.classpath=\
/usr/local/share/java/classes/turbine-pool.jar

Those lines should also be added to jserv.properties.

(3) Add following line into zone.properties.

"repositories=/usr/local/share/java/classes/cocoon.jar"
"servlet.org.apache.cocoon.Cocoon.initArgs=properties= \
/usr/local/etc/apache/cocoon/cocoon.properties"

Again, cocoon.jar is mis-spelled as Cocoon.jar in the default installation of /usr/local/etc/apache/jserv/zone.properties. The line should be uncommented, and the spelling corrected. Additionally, the full path of cocoon.properties is wrong in that file. By default, cocoon.properties is installed into /usr/local/etc/apache/cocoon/, so when uncommenting the line in zone.properties, be sure to insert the additional cocoon/ subdirectory into the path. Note that despite the instruction above, there are two lines to be added, and neither should be delimited by quotation marks.

(4) Make directory "/var/tmp/cocoon-repository".

The ownership of this directory should also reflect the user and group under which httpd will be running, which is nobody by default. As root, execute:

# mkdir /var/tmp/cocoon-repository
# chown nobody.nobody /var/tmp/cocoon-repository

Finally, restart Apache and test Cocoon:

# /usr/local/sbin/apachectl restart
# lynx http://localhost/Cocoon.xml