Installing Cocoon

System Requirements

Cocoon requires the following systems to be already installed in your system:

Required Components

Cocoon is a publishing framework and was designed to be highly modular to allow users to choose their preferred implementation for the required component and to allow better and faster parallel development.

Previous releases of Cocoon forced you to download all the basic required packages for the installation, but this generated lots of problems due to lack of synch between the projects and the complexity of the operation. For this reason, Cocoon now ships with all the required packages, (but not the optional packages), a sort of a simple distribution to make things easier for you. We apologize for the increased size of the distribution, but we think this will be worthwhile even for users with low bandwidth.

In the /bin directory you'll find the cocoon.jar jar package that contains the Cocoon binary files, while the /lib directory contains all the libraries required for Cocoon operation. While these packages may not be the most up-to-date versions, they are guaranteed and tested to work properly with Cocoon so, we suggest that you use them. Note, however, that they were all redistributed untouched from their original distributions.

If you use Java 1.2 or greater, you also have to treat the file [jdk_home]/lib/tools.jar as another Cocoon component and include this into your classpath. This package contains the java compiler that is required for Cocoon page compilation.

The Ant and Stylebook packages are only used in the build system and are not used by Cocoon at run-time. So you can safely ignore them in the installation.

Installing Cocoon

As Cocoon is a servlet (albeit a large servlet!), you should be able to install it on every compliant servlet engine by associating the "org.apache.cocoon.Cocoon" servlet with the requests you want it to handle. In order to do this, there is no standard way, so we try to provide detailed information for the most used servlet systems.

If you have any problems, please look at the FAQ before submitting a bug report or a request for help on the mailing lists. Thank you.

Installing Cocoon on Apache JServ

The first thing to do is to make sure that Cocoon and all the needed components (as explained in the previous section) are visible to the JVM. This means adding the following to the servlet engine classpath by adding a bunch of classpath lines to your jserv.properties file for each jar package.

wrapper.classpath=[path-to-jar]/[jar-name].jar

Here is an example:

wrapper.classpath=/usr/local/java/jdk/lib/tools.jar
wrapper.classpath=/usr/local/java/cocoon/bin/cocoon.jar
wrapper.classpath=/usr/local/java/cocoon/lib/xerces.jar
wrapper.classpath=/usr/local/java/cocoon/lib/xalan.jar
wrapper.classpath=/usr/local/java/cocoon/lib/fop.jar
...

The ./bin/cocoon.jar package must be added to the servlet engine classpath in order for the XSP subsystem to work correctly. We understand that this could be a flexibility limitation. On JServ it is not yet possible to run multiple instances of Cocoon in the same virtual machine - if you would like to do that, try using a different servlet engine.

JServ is a Servlet 2.0 compliant servlet engine and will not work if you place the Servlet_2.2.jar in its classpath. So ignore the servlet_2.2.jar package that is shipped with Cocoon if you use Jserv.

At this point, you must set the Cocoon configuration. To do this, you must choose the servlet zone(s) where you want Cocoon to reside. If you don't know what a servlet zone is, open the zone.properties file.

To configure Cocoon, you must pass the cocoon.properties file location to the servlet by adding the following line to the servlet zone:

servlet.org.apache.cocoon.Cocoon.initArgs=properties=[path-to-cocoon]/bin/cocoon.properties

where [path-to-cocoon] is an absolute path.

Note that you should not need to change anything from the template properties file found in the distribution (under /conf/), but you must edit it for more complex operation. Please refer directly to that file, which contains brief indications and comments on the different configurations (but you don't need to care about that at this point).

Now your cocoon servlet is properly configured, but you should tell Apache to direct any call to an XML file (or any other file you want Cocoon to process) to the Cocoon servlet. To do this, you should add the following line to your jserv.conf file:

Action cocoon /servlet/org.apache.cocoon.Cocoon
AddHandler cocoon xml

where xml is the file extention you want Cocoon to handle and /servlet/ is the mount point of your servlet zone (and the above is the standard name for servlet mapping for Apache JServ).

If you haven't already got the Actions module compiled in to Apache (note - this is compiled in by default in standard installs), you will need to have the following line uncommented in your httpd.conf or Apache will not be able to start:

LoadModule action_module /path/to/mod_actions.so

Restart both Apache and Apache JServ and try accessing the Cocoon status page:

http://localhost/Cocoon.xml

Cocoon will show you how it's configured.

If the page above is working, make the samples contained in the distribution (under ./samples) visible from your web server (by either copying the files under yout htdocs directory, or by making at alias for the sample directory) and call ./samples/index.xml to see Cocoon in action.

If you have any problems, please look at the FAQ before submitting a bug report or a request for help on the mailing lists. Thank you.

Installing Cocoon on Apache Tomcat

To make Cocoon work with Tomcat, you must add a context to Tomcat that describes to Tomcat how to load Cocoon files. Then you must tell Apache to send certain requests to Tomcat (and consequently Cocoon). Finally you must provide the .xml files to be served by Cocoon. These steps are outlined below.

A context in Tomcat describes to Tomcat how and when to load a particular servlet and Cocoon is one such servlet. First we need to make sure that Tomcat knows how to load the Cocoon .jar files. To begin with, you must copy any .jar files from $COCOON_HOME/lib to $TOMCAT_HOME/lib that are necessary for Cocoon to run. In addition, you must copy $COCOON_HOME/bin/cocoon.jar to $TOMCAT_HOME/lib.

In recent versions of Tomcat under Unix, Tomcat will automatically detect any .jar files in the $TOMCAT_HOME/lib directory. But under Windows, you must explicitly add the new .jar files in the appropriate place in the file $TOMCAT_ROOT/bin/tomcat.bat.

Next you must tell Tomcat about the new context which will run Cocoon requests. To do this edit the file $TOMCAT_HOME/conf/server.xml and add the following line:

 <Context path="/cocoon" docBase="webapps/cocoon" debug="0" reloadable="true" >
 </Context>
 

This tells Tomcat that requests that come in under that partial path "/cocoon" should be mapped to the context defined in the directory "webapps/cocoon". We will set that up shortly.

Next, if using Apache with Tomcat (which is recommended on a production server, since Tomcat standalone is not yet as efficient or robust - Apache is far more mature!) we need to tell Apache to forward the same partial pathnames to Tomcat. This is done by editing the tomcat .conf file (it's called tomcat-apache.conf if you're using Tomcat 3.1 and Apache 1.3.12) in your Apache setup. Add the following lines:

 Alias /cocoon $TOMCAT_HOME/webapps/cocoon
 <Directory "$TOMCAT_HOME/webapps/cocoon">
     Options Indexes FollowSymLinks
 </Directory>
 ApJServMount /cocoon /cocoon
 <Location /cocoon/WEB-INF/ >
     AllowOverride None
     deny from all
 </Location>
 

This tells Apache to direct requests that come in under that partial path "/cocoon" to the directory under Tomcat ($TOMCAT_HOME/webapps/cocoon).

Finally, we need to set up the actual context that we have defined and pointed requests to above. To do this, we need to create a new directory in webapps called cocoon. Then we need to make a sub-directory that describes to Tomcat how to map particular files to Cocoon, then we need to fill the sub-directory with our Cocoon source files (.xml files).

First make a directory and its subdirectory:

 mkdir $TOMCAT_HOME/webapps/cocoon
 mkdir $TOMCAT_HOME/webapps/cocoon/WEB-INF
 

Next copy the template files from the Cocoon distribution:

 cp $COCOON_HOME/src/WEB-INF/web.xml $TOMCAT_HOME/webapps/cocoon/WEB-INF
 cp $COCOON_HOME/conf/cocoon.properties $TOMCAT_HOME/webapps/cocoon/WEB-INF
 

Next you need to edit the $TOMCAT_HOME/webapps/WEB-INF/web.xml file to point to the Cocoon properties file in the same directory. Do this by changing the text conf/cocoon.properties to WEB-INF/cocoon-properties. Note that this path is a relative path must be so. Don't try to use an absolute path here. It won't work. Also note that the web.xml file describes how to map .xml requests to the Cocoon servlet.

Next you need to populate the cocoon context with source .xml files. For testing purposes you can just use the samples that come along with Cocoon.

 cp -R $COCOON_HOME/samples $TOMCAT_HOME/webapps/cocoon/servlets
  

Finally, you need to stop Tomcat, stop Apache, then restart the two in order to make all of the new settings load. You should be able to access pages like http://localhost/cocoon/Cocoon.xml and http://localhost/cocoon/servlets/index.xml

Make sure that xerces.jar is located before xml.jar otherwise XSP won't work. To do this, rename xml.jar as zxml.jar to be placed later in alphabetical order.

If you have any problems, please look at the FAQ before submitting a bug report or a request for help on the mailing lists. Thank you.

Installing Cocoon on New Atlanta's ServletExec 2.2

After you have obtained all the jar packages you need (see the above section), you should add them to your Classpath.pref file. Then, add this to the servlets.properties file:

servlet.Cocoon.code=org.apache.cocoon.Cocoon
servlet.Cocoon.initArgs=properties=/web/var/tmp/cocoon/cocoon.properties

and this to the rules.properties file:

*.xml=Cocoon

to provide the initArgs and extension association for Cocoon. Once the web server is restarted to pick up the new configuration, everything should work ok - try accessing the samples contained in the distribution to see Cocoon in action or the /Cocoon.xml page for Cocoon internal status.

You could also make these three configuration changes via the servlet/admin GUI interface if you're not into editing files.

Installing Cocoon on BEA WebLogic (version 4.5.1)

After you have obtained all the jar packages you need (see the above section), you should add all of them (included the cocoon.jar package to your weblogic.class.path variable either using the t3config utility or use the -Dweblogic.class.path argument with the java runtime that invokes the system.

Once you've done that, you should register Cocoon by adding these lines to your configuration files:

weblogic.httpd.register.*.xml=\org.apache.cocoon.Cocoon
weblogic.httpd.initArgs.*.xml=\properties=[path-to-cocoon]/bin/cocoon.properties

making sure that you replaced [path-to-cocoon] with the actual path in your system.

At this point, you should check if your system matches the global considerations about Cocoon properties. Usually, you might want to give the installation a try as it is and then read again that section if something goes wrong. Most installations don't need any changes to be operational.

Everything should be configured fine. Restart Weblogic and try accessing the samples contained in the distribution to see Cocoon in action or the /Cocoon.xml page for Cocoon internal status.

Installing Cocoon on BEA WebLogic (version 5.1)

WLS 5.1 implements Servlet 2.2. so it plugs in easily. Here's a quick recipe:

  • Add the xerces, xalan, fop, servlet, and cocoon JAR files (from the distribution) to your CLASSPATH. (See below). If you're using Java 2, you should also add the tools.jar file from the JDK distribution to your CLASSPATH.
  • Create a new subdirectory tree of your WLS run time directory "cocoonwar/WEB-INF" and copy the default web.xml file (from the src directory of the distribution) there.
  • Copy the cocoon.properties from the conf directory of the distribution to cocoonwar/WEB-INF and updated the web.xml file to refer to it.
  • Copy the samples directory from the distribution to cocoonwar
  • Map the web application into the WLS URI name space by adding the following line to your weblogic.properties file: weblogic.httpd.webApp.cocoon=cocoonwar

Start WLS, point your browser at http://localhost:7001/cocoon/samples/index.xml and away you go.

Classpaths and XSP

To support hot deployment of EJB's and Servlets, WebLogic Server uses its own class loader with its own classpath (the "WebLogic classpath"). Normally you'd put all the WebLogic Server container code, JDBC drivers, etc. in your Java CLASSPATH (so that WebLogic Server can start up) and add all your application code (stuff that needs to be able to be redeployable) to the WebLogic classpath.

Cocoon is effectively "container" code, and the XSP processor uses dynamic classloading which only understands the Java CLASSPATH, so you should put all of the Cocoon jars in CLASSPATH.

The big problem with this is that you can't use any code that loads from the WebLogic classpath within XSP's. This includes all of the WebLogic API, so is a PITA. To overcome this, either the way Cocoon loads classes needs to be modified, or the WebLogic Server class loader needs to be disabled (in which case you have to be willing to live without hot redeployment).

To disable the WebLogic class loader, put your application classes, the Cocoon jars and all of the WebLogic Server stuff into the Java CLASSPATH, and add

-Dweblogic.system.disableWeblogicClassPath=true

to the Java command at the end of you WebLogic start script.

The above will also work for installing Cocoon in the BEA WebLogic Enterprise 5.1 J-Engine.

Installing Cocoon on JRun

To configure JRun, you must set up both JRun and the web server of your choice to work with Cocoon. We assume that you already have a generic JRun installation that works with your web server.

For the JRun portion, you must add all Cocoon jars to the java.classpath in [jrun-home]/jsm-default/properties with something like:

java.classpath=[previous jrun jars]:[cocoon-home]/lib/xerces.jar:
[cocoon-home]/lib/stylebook.jar:[cocoon-home]/lib/fop.jar:
[cocoon-home]/bin/cocoon.jar:[cocoon-home]/lib/xalan.jar:
[cocoon-home]/lib/turbine-pool.jar

Note that all newlines are added for readability and should not actually be in the configuration file. All jars should be listed upon the same line.

Now, modify [jrun-home]/jsm-default/services/jse/properties/rules.properties and add the line:

*.xml=org.apache.cocoon.Cocoon

In [jrun-home]/jsm-default/services/jse/properties/servlets.properties, add the lines:

servlets.properties:servlet.org.apache.cocoon.Cocoon.code=org.apache.cocoon.Cocoon
servlets.properties:servlet.org.apache.cocoon.Cocoon.args=properties=[cocoon-home]/conf/cocoon.properties
servlets.properties:servlet.org.apache.cocoon.Cocoon.preload=false

And finally, change the defaultdocs line in [jrun-home]/jsm-default/services/jse/properties/files.properties and add "index.xml" so that the line looks something like:

defaultdocs=index.html,index.jsp,index.xml

Since JRun is web server independent, you must configure JRun and Cocoon to work with your webserver. Again, we assume that you already have JRun installed and working for your particular webserver. We give additional instructions only for making Cocoon work.

Cocoon with JRun and Apache

Add the following to [apache path]/conf/httpd.conf

Action cocoon /servlet/org.apache.cocoon.Cocoon
AddHandler cocoon xml
Alias /cocoon/ "[cocoon-home]"

The "Alias" line above is optional; but it will make testing the setup much easier. To verify that all is working, make sure to test out the XSP demos. If you get a java.lang.NoSuchMethodError: org.w3c.dom.Node error, try moving the xerces.jar to the front of JRun's java.classpath, restart JRun, and try the XSP again.

Cocoon with JRun and other web servers (iPlanet, IIS, etc)

Add your sucessful installation method here. Volunteers welcome!

Installing Cocoon on iPlanet Web Server 4.x

This has been tested on v4.1 under NT 4.

If you prefer working with your file editor

Edit your servlets.properties file in the config folder of your server (something like C:\Netscape\Server4\https-something.somewhere.com\config), add the following lines:

servlet.cocoon.code=org.apache.cocoon.Cocoon
servlet.cocoon.initArgs=properties=<yourpath to cocoon>/cocoon/conf/cocoon.properties

In the jvm12.conf, add all the needed ".jar" to the jvm.classpath line and uncomment it. This would make the following line, for example, if you installed Netscape on D: drive. (Note: This should be all on one line, but for legibility it is split accross lines.)

jvm.classpath=d:/Netscape/Server4/plugins/samples/servlets/beans.10/SDKBeans10.jar;
d:/Netscape/Server4/plugins/samples/servlets/beans/SDKBeans.jar;
d:/Netscape/Server4/bin/https/jar/Bugbase.jar;
d:/Netscape/Server4/bin/https/jar/Calljsac.jar;
D:/Netscape/Server4/docs/cocoon/bin/cocoon.jar;
D:/Netscape/Server4/docs/cocoon/lib/fop_0_12_1.jar;
D:/Netscape/Server4/docs/cocoon/lib/stylebook-1.0-b2.jar;
D:/Netscape/Server4/docs/cocoon/lib/xalan_1_0_1.jar;
D:/Netscape/Server4/docs/cocoon/lib/xerces_1_0_3.jar

In the rules.properties file, add the following line (this is made to turn around a regexp bug in iWS):

@.*[.]xml=cocoon

If you prefer the GUI interface

Everything is in the "Servlets" tab of your server setting:

  1. You need to set first "Configure Servlet Attributes". Don't try to set the classpath here. It is of no use :-(
    • Servlet Name: Cocoon
    • Servlet Code (class name): org.apache.cocoon.Cocoon
    • Servlet Args: properties=<yourpath to cocoon>/cocoon/conf/cocoon.properties (This is a disk path)
  2. Then, go to "Configure JVM Attributes" and add to the classpath the path to the cocoon jar (like the jvm.classpath value in the above section)
  3. To finish, go to "Configure Servlet Virtual Path Translation" and add the rule for "*.xml" to point to cocoon servlet:
    • Virtual Path: @.*[.]xml
    • Servlet Name: cocoon

Installing Cocoon on other platforms

Yet to be written! Volunteers welcome!

Working Systems

Cocoon 1.x has been reported to be working on these systems:

Operating System Web Server Servlet Engine JVM
Debian Potato or Woody Apache 1.3.12 JServ 1.1.2 IBM JDK 1.1.8 or 1.3
RedHat Linux 6.0 Apache 1.3.9 Apache JServ 1.0 IBM JDK 1.1.8
RedHat Linux 6.0 Apache 1.3.9 Apache JServ 1.1b3 IBM JDK 1.1.8
RedHat Linux 6.0 Apache 1.3.9 Apache JServ 1.0 Blackdown JDK 1.2pre2
RedHat Linux 6.1 Apache 1.3.9 JRun 2.3.3 IBM JRE 1.1.8
RedHat Linux 6.1 (i686) Apache 1.3.11 Apache JServ 1.1 Sun JDK 1.2.2
RedHat Linux 6.1 (i686) Apache 1.3.11 + mod_ssl 2.5.0 Apache JServ 1.1 IBM JDK 1.1.8
RedHat Linux 6.1 Apache 1.3.12-2 Jserv 1.1.2-2 JDK 1.2.2_006
RedHat Linux 6.2 (i686) Apache 1.3.12 + mod_ssl 2.6.5 JRun 2.3.3 Sun JDK 1.2.2
RedHat Linux 6.2 Apache 1.3.12-2 Tomcat 3.1 JDK 1.2.2_006
RedHat Linux 6.2 (i686) Apache 1.3.12 Resin 1.2.b1 Sun JDK 1.2.2
SuSE 6.3 Linux Apache 1.3.9 Apache JServ 1.1 Sun JDK 1.2.2
SuSE 7.0 Linux (2.2.16) Apache 1.3.12 Apache JServ 1.1.2, Tomcat 3.1 IBM JDK 1.3
Windows 98 Apache 1.3.9 Apache JServ 1.0 Sun JDK 1.2.2
Windows 98 Apache 1.3.9 Apache JServ 1.0 IBM JDK 1.1.7
Windows 98 Apache 1.3.9 Apache JServ 1.1b3 Sun JDK 1.2.2
Windows 98 Apache 1.3.9 Apache JServ 1.1b3 IBM JDK 1.1.7
Windows 98 MS Personal Web Server ServletExec 2.2 Sun JDK 1.2.1
Windows NT 4.0 IIS 4.0 ServletExec 2.2 Sun JDK 1.2.1
Windows NT 4.0 IIS 4.0 JRun 2.3.3 Sun JDK 1.2.1
Windows NT 4.0 Apache 1.3.9 JRun 2.3.3 Sun JDK 1.2.2
Windows NT 4.0 Apache Jakarta Tomcat 3.1 Milestone 1 Sun JDK 1.2.2
Windows NT 4.0 SP4 BEA WebLogic Server 5.1 SP3 Sun JDK 1.2.2
Windows NT 4.0 SP5 IIS 4.0 Websphere 3.5 Enterprise IBM JDK 1.2.2
Windows NT 4.0 SP6a Apache 1.3.11 Apache JServ 1.1 Sun JDK 1.2.2
Windows 2000 Professional Apache 1.3.12 Apache JServ 1.1 Sun JDK 1.2.2
Windows 2000 Professional Apache 1.3.12 Tomcat 3.1 Sun JDK 1.3
Windows 2000 Advanced Server Tomcat 3.1 JDK 1.3
MacOS 8.5+ Resin 1.1b MRJ 2.2
MacOS 8.6 Tomcat 3.1 MRJ 2.2.2
MacOS 8.6 WebSTAR 4.0 JRun 2.3 MrJ 2.1.4
MacOS 8.6 WebSTAR 4.0 ServletExec 2.1 Mrj 2.1.4
MacOS 8.6 Quid Pro Quo 2.1.3 ServletExec 2.2 Mrj 2.1.4
Solaris 2.5.1 Netscape-Enterprise/3.6 SP3 ServletExec 2.2 Sun JDK 1.2.1
SunOS Netria 5.6 Apache 1.3.9 Apache JServ 1.1b3 Sun JDK 1.1.7
Solaris 8 (SPARC) Apache 1.3.12 Tomcat 3.1 Sun JDK 1.3 Beta Refresh
Solaris 8 (x86) Resin 1.2.b1 JDK 1.3 beta
FreeBSD 3.4 Apache 1.3.9 Apache JServ 1.0 Blackdown JDK 1.1.8
FreeBSD 3.4-STABLE with linux_base-6.1 for linux-emulation Jetty Java HTTP Server v2.3.3 Blackdown jdk-1.2.2-RC4-linux-i386-glibc
FreeBSD 4.1 (RELEASE) Apache 1.3.12 Jserv 1.1.2 Linux JDK 1.2.2
SCO OpenServer 5 WebLogic 4.5.1 SCO JDK 1.1.7A
OS/2 Warp 4 FP 12 Gefion Software LiteWebServer IBM JDK 1.1.8
SGI IRIX 6.5.7 Apache 1.3.12 Apache JServ 1.1 Sun JDK 1.2.1 (SGI)

Please, submit your feedback on the cocoon users mailing list (nowhere else!) if you were able to install Cocoon on a different combination not listed above. Thanks!