Luminas Technology: Cocoon: quick-start guide

This documentation assumes you already have a working installation of Apache (e.g. from http://www.apache.org/httpd.html) and a working installation of Java (e.g. from http://java.sun.com/). It is also heavily linux biased - I make no apology for that!

Firstly, you will need a servlet engine for Apache. This allows the webserver to run server-side java code ("servlets"). There are a number of free and commercial servlet engines out there, but these instructions will deal with Tomcat specifically. Tomcat is the reference implementation of the Servlet 2.2 technology.

Grab a copy of the latest release build from http://jakarta.apache.org/. At time of writing, this is Tomcat 3.2.3, and is available at: http://jakarta.apache.org/builds/jakarta-tomcat/release/v3.2.3/bin/.

Unarchive it in an appropriate place:

		cd /usr/local
		tar xzvf jakarta-tomcat-3.2.3.tar.gz

The current version of the Tomcat distribution may not have the right permissions set on some files. Fix this by typing:

		chmod +x /usr/local/jakarta-tomcat-3.2.3/bin/tomcat.sh

For detailed instructions on installing and configuring Tomcat, see the documentation in the distribution, but essentially, just do:

		cd /usr/local/jakarta-tomcat-3.2.3/bin
		./tomcat.sh start

You should then be able to see Tomcat running at http://127.0.0.1:8080/.

Next, you need to grab the cocoon distribution. The best way to obtain Cocoon 2 is to check it out of CVS. See http://xml.apache.org/cvs.html for information on grabbing Apache CVS repositories.

One way to do this is to set up an alias in your .bash_profile. This means that whenever you want to use Apache CVS, you can simply use "cvs-apache" without having to set your CVS shell or root directory. Do this as follows:

		alias cvs-apache="CVS_RSH=ssh cvs -d :pserver:anoncvs@xml.apache.org:/home/cvspublic"
		source ~/.bash_profile

The second line makes the alias take effect for the current shell. Next, take a copy of the CVS repository by doing:

		cvs-apache login
		cvs-apache checkout -r cocoon_20_branch xml-cocoon2

(The password for cvs login is 'anoncvs'.)

You should then get a directory called "xml-cocoon2" full of the relevant code.

Follow the guidelines in xml-cocoon/INSTALL, sort of:

		cd xml-cocoon
		./build.sh -Dinclude.webapp.libs=yes -Dinstall.war=/usr/local/jakarta-tomcat-3.2.3/webapps install
		cp lib/* /usr/local/jakarta-tomcat-3.2.3/lib/
		cd /usr/local/jakarta-tomcat-3.2.3/lib/
		rm jaxp.jar parser.jar
		mv xerces_1_4_1.jar parser.jar

Restart Tomcat:

		cd /usr/local/jakarta-tomcat-3.2.3/bin
		./tomcat.sh stop
		./tomcat.sh start

... and hopefully you should be ready to run cocoon!

Visit: http://127.0.0.1:8080/cocoon/ ... and with a bit of luck, you will see the Cocoon documentation. It can take a while to fire up, so be patient!