Cocoon Documentation

# Installing Cocoon

# Notes for Upgraders

If you are upgrading Cocoon from a previous version, please note four important points:

- It is likely to cause errors if you use your old cocoon.properties file. Instead, copy the new one from the Cocoon distribution and make changes to it if necessary.
- Again, it may cause errors if you use old samples with a new Cocoon.
- If you use the ESQL taglib, the syntax has changed between Cocoon 1.8 and Cocoon 1.8.1
- The most common upgrading and installation mistakes can be rectified by carefully reading the instructions below.

# System Requirements

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

- Java Virtual Machine A Java 1.1 or greater compatible virtual machine must be present for both command-line and servlet usage of Cocoon. Note that all servlet engines require a JVM to run so if you are already using servlets you already have one installed.
- Servlet Engine A Servlet 2.x compliant servlet engine must be present in order to support servlet operation and dynamic request handling. Note that this requirement is optional for command-line operation.

# 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:

Jar filename | Package name | Obtained from | Purpose | Needed at run-time? | Needed at build-time? | Notes
--- | --- | --- | --- | --- | --- | ---
ant_1_1.jar | Ant 1.1 | jakarta.apache.org | Cocoon build system (a bit like Make) | No | Yes | Other versions of Ant may not work.
bsfengines.jar | Bean Scripting Framework | IBM | Xalan extension functions | Optional | No |
bsf.jar | Bean Scripting Framework | IBM | Xalan extension functions | Optional | No |
fop_0_15_0.jar | FOP | xml.apache.org | Converts xsl:fo into PDF output | Yes (unless disabled) | Yes |
sax-bugfix.jar | - | Robin Green | Fixes error reporting bug | Optional | No | See below
servlet_2_2.jar | Servlet 2.2 API | jakarta.apache.org | Compiling | No | Yes, always |
stylebook-1.0-b2.jar | Stylebook | xml.apache.org CVS | Generating docs | No | Yes for docs and dist | Requires Java 2; will be obsoleted by C2
turbine-pool.jar | Turbine | java.apache.org | JDBC connection pooling | Yes, always | Yes |
w3c.jar | ? | xml.apache.org | Required by FOP | Yes | ? |
xalan_1_2_D02.jar | Xalan 1.2D02 | xml.apache.org | Processing XSLT stylesheets and logicsheets | Yes | Yes |
xerces_1_2.jar | Xerces 1.2 | xml.apache.org | Parsing XML and outputting XML/HTML/text. | Yes | Yes | Position in CLASSPATH is very important (see below)

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.

It is very important to ensure that the xerces jar is in front of other XML parsers in the CLASSPATH (if any). This is the most frequent source of errors in installing Cocoon!

The Ant, Stylebook and Servlet 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 (unless otherwise specified).

The `sax-bugfix.jar` is an optional, unofficial bugfix - which must be ahead of xerces in the CLASSPATH to work - to allow you to see line numbers and column numbers in XML parsing error messages, and is only needed on some virtual machines. If you get "sealing violations", try removing it from your CLASSPATH.

# 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, and adding the required jar files to the CLASSPATH. Unfortunately, there is as yet no standard way to do this, so we try to provide detailed information for a variety of servlet engines:

- Apache JServ
- Apache Tomcat - Tomcat homepage
- BEA WebLogic
- Dynamo
- IBM WebSphere
- Inprise Application Server
- iPlanet Web Server
- Orion
- ServletExec
- Other

Note that you should not need to change anything from the template `cocoon.properties` configuration 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 comments and hints on the different configurations.

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: This is an EXAMPLE only and may not be up to date. If you get errors, first check that all the required jar files (see top of page) from cocoon/lib are on your CLASSPATH, and spelled correctly.

    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
    [... and all the other required jar files in cocoon/lib as discussed above]

??To run multiple instances of Cocoon in the same virtual machine (in ??different zones), the `./bin/cocoon.jar` file needs to be ??included in the zone's classpath (together with other zone specific ??classpath components).??so, you need to properly set the ??processor.xsp.localclasspath property. This property tells the XSP ??ngine wich classpath to use when calling the compiler, as there's ??currently no way for Cocoon to ask the classpath to the zone's ??classloader. The value of this property should be the classpath ??used in the "repositories" parameter (which includes ??`cocoon.jar`). Please note that the??port ??for doing this is still experimental.

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.

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

We highly recommend using Tomcat 3.2.1 or higher, since it is more secure and supports virtual hosting with or without using separate JVMs.

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 (see top of page). In addition, you must copy `$COCOON_HOME/bin/cocoon.jar` to `$TOMCAT_HOME/lib`.

In recent versions of Tomcat under Unix and Windows, Tomcat will automatically detect any `.jar` files in the `$TOMCAT_HOME/lib` directory. But with Tomcat 3.1 under Windows only, 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 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, but with Tomcat 3.2 you have a choice between tomcat-apache and the more advanced `mod_jk.conf-auto`) and associating it with your Apache setup, as described below.

Very Important Note! Both of these files are now regenerated and overwritten whenever you run Tomcat, so don't edit them directly, but instead save them as something else!

If you're using mod_jserv, add the following lines to your copy of `tomcat-apache.conf`:

     Alias /cocoon $TOMCAT_HOME/webapps/cocoon
     <Directory "$TOMCAT_HOME/webapps/cocoon">
         Options Indexes FollowSymLinks
     </Directory>
     ApJServMount /cocoon /cocoon
     AddType text/xml .xml
     AddHandler jserv-servlet .xml
     <Location /cocoon/WEB-INF/ >
         AllowOverride None
         deny from all
     </Location>

This tells Apache to direct .xml requests that come in under that partial path "/cocoon" to the directory under Tomcat (`$TOMCAT_HOME/webapps/cocoon`). The equivalent setup for mod_jk with a worker called "ajp13" is simpler (see also the mod_jk HOWTO for more details):

     Alias /cocoon $TOMCAT_HOME/webapps/cocoon
     <Directory "$TOMCAT_HOME/webapps/cocoon">
         Options Indexes FollowSymLinks
     </Directory>
     JkMount /cocoon/*.xml ajp13
     AddType text/xml .xml
     <Location /cocoon/WEB-INF/ >
         AllowOverride None
         deny from all
     </Location>

Don't mix mod_jserv directives with mod_jk directives. It won't work.

These files don't actually do anything by themselves. To be activated, they need to be included into the main Apache configuration file. To do this, add this to `httpd.conf`.

           include /your-dir/your-filename-here

(of course, substituting `/your-dir/your-filename-here` for the location of your configuration file)

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/cocoon/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, and 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. Note that some of these are insecure and SHOULD NOT be available on a production server, because they allow access to arbitrary .xml source code

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

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/samples/index.xml

IMPORTANT: If you get a NoSuchMethodError when starting up, make sure that `xerces.jar` is located before other XML jars in the CLASSPATH, otherwise XSP won't work. Tomcat 3.1 on UNIX - and Tomcat 3.2 on both UNIX and Windows - construct their own CLASSPATH automatically and then add the environment CLASSPATH, so manually setting the CLASSPATH before running Tomcat won't work. Instead, a hack which some people have found to work is (in the case of Tomcat 3.2) renaming `xml.jar` as `zxml.jar` and `parser.jar` as `zparser.jar`. For other versions try renaming `crimson.jar`. (Alert readers may have noticed that xerces is lexicographically prior to xml anyway - so why does this work? Well, to be quite frank - who cares? It works, okay! ;-)

If you have any other problems, please, please look at the FAQ and the Tomcat documentation before submitting a bug report or a request for help on the mailing lists. Please also consider that Tomcat has its own mailing lists for more Tomcat-related problems. Thank you.

## Installing Cocoon on BEA WebLogic

Please follow the instructions for the version that you are using.

Afterwards, 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.

### BEA WebLogic version 4.5.1

Add all of the required jar files (see top of page) 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.

### BEA WebLogic version 5.1 / Enterprise 5.1 J-Engine

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

To avoid problems, apply the latest WebLogic Service Pack before installing Cocoon.

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

1. Add all the required jar files (see top of page) to your CLASSPATH (but see the CLASSPATH section below!). You can do this through `wlconfig` in the `weblogic\bin` directory, or on Windows through `regedit32` (Software -> BEA Systems -> Weblogic -> 5.10 -> classpath), or the `startweblogic.cmd` file.
2. Create a new subdirectory tree of your WLS run time directory "cocoonwar/WEB-INF" and copy the default web.xml file (from the src/WEB-INF directory of the distribution) there.
3. Copy the cocoon.properties from the conf directory of the distribution to cocoonwar/WEB-INF and update the web.xml file to refer to it. You should use a relative path: `/WEB-INF/cocoon.properties`
4. Copy the samples directory from the distribution to `cocoonwar`
5. 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`
6. Restart the Weblogic server

#### 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 your WebLogic start script.

### BEA Weblogic Server version 6.0

1. Create a "cocoon" directory in WEBLOGIC_HOME/config/mydomain/applications
2. Copy the "conf" and "samples" directories from the Cocoon distribution to `WEBLOGIC_HOME/config/mydomain/applications/cocoon`
3. Create WEBLOGIC_HOME/config/mydomain/applications/cocoon/WEB-INF and copy src/web.xml from the distro to this directory. Note that all caps are important for the WEB-INF directory regardless of OS (since Java is case sensitive).
4. Edit the web.xml file to point to the cocoon.properties file. If you followed the instructions above, the <param-value> tag should contain /conf/cocoon.properties
5. Make sure ALL the required jars in the Cocoon distribution are in your Java CLASSPATH. If you get errors initializing Cocoon or accessing XSP pages, check this first.
6. Start WLS. Cocoon should automagically deploy. Start the console, click on the "deployments" -> "Applications". You should see "cocoon" in the application list. Click on it and see if the "Deployed" box is checked in the configuration tab. If it isn't, check it and click "apply".

## Installing Cocoon on Dynamo

This has been tested on Windows 2000.

1. Remove lotusxsl.jar and xml4j.jar - these are replaced by the newer xalan and xerces, respectively, supplied with Cocoon.
2. Update your system CLASSPATH with the required Cocoon jars (see top of page)
3. Start the Dynamo server and the Developer Workbench.
4. In the Developer Workbench create a component in the Nucleus tree named `/Cocoon`
5. Edit the properties file $DYNAMO_HOME/localconfig/Cocoon.properties and add the line `properties=C:/Programs/cocoon-1.8/conf/cocoon.properties` (use the correct path for your installation, and use forward slashes instead of backslashes).
6. Look for the component "/atg/dynamo/servlet/pipeline/MimeTyperServlet" and check the property "mimeTyper" is "/atg/dynamo/servlet/pipeline/MimeTyper".
7. Look for the component "/atg/dynamo/servlet/pipeline/MimeTyper" and check properties 160 and 161 are "xml" and "application/xml". If not, you have to add them.
8. Look for the component "/atg/dynamo/servlet/pipeline/MimeTypeDispatcher" and edit the proprerty "dispatcherServiceMap", adding "key" = "application/xml" and "value" = "/Cocoon".
9. Re-start Dynamo.
10. Go to http://localhost/Cocoon.xml and you should see the Cocoon status page.

## Installing Cocoon on IBM WebSphere 3.5

The following rough-and-ready script installs Cocoon and maps the content directory to the cocoon examples directory using /cocoon as a URI. This script assumes you've unpacked the cocoon 1.8 distribution into d:/cocoon-1.8, you may need to adjust the paths to make this work for your config.

WARNING! This script will wipe out any user set command line arguments to the default Application server.

WARNING! Do NOT add servlet_2_2.jar (from the Cocoon distribution) to the CLASSPATH. This is only provided for the purposes of rebuilding Cocoon, and because WebSphere uses non-standard Servlet API calls, this jar may cause WebSphere to fail.

This is an EXAMPLE only and may not be up to date. If you get errors, first check that all the required jar files (see top of page) from cocoon/lib are on your CLASSPATH.

    # usage: wscp -f ws.tcl

    set node [Node list]
    set appserv "[set node]ApplicationServer:Default Server"
    set webapp "$appserv/ServletEngine:Default Servlet Engine/WebApplication:cocoon"
    set cocoon "$webapp/Servlet:cocoon"

    # add the cocoon classes to the classpath
    # *** NOTE! - the following should be all on one line!! ***
    ApplicationServer modify $appserv/ -attribute
    {{CommandLineArgs {-classpath D:/cocoon-1.8/lib/bsf.jar;D:/cocoon-1.8/lib/bsfengines.jar;
    D:/cocoon-1.8/lib/turbine-pool.jar;D:/cocoon-1.8/lib/xerces_1_2.jar;
    D:/cocoon-1.8/lib/xalan_1_2_D02.jar;D:/cocoon-1.8/lib/fop_0_15_0.jar;
    D:/WebSphere/AppServer/jdk/lib/tools.jar;D:\cocoon-1.8\bin\cocoon.jar}}}

    # create the cocoon web application
    set attributes {}
    lappend attributes {Name cocoon}
    lappend attributes {Description {Cocoon web application}}
    lappend attributes {DocRoot {d:/cocoon-1.8/samples}}
    lappend attributes {URIPath default_host/cocoon}
    lappend attributes {Classpath d:/cocoon-1.8/samples}
    WebApplication create $webapp/ -attribute ${attributes}

    # create the servlet
    set attributes {}
    lappend attributes {Code org.apache.cocoon.Cocoon}
    lappend attributes {Name cocoon}
    lappend attributes {LoadAtStartup true}
    lappend attributes {Description {Cocoon servlet}}
    lappend attributes {URIPaths {default_host/cocoon/}}
    lappend attributes {InitParams {{properties D:\cocoon-1.8\conf\cocoon.properties}}}
    Servlet create $cocoon/ -attribute ${attributes}

    # stop & start the app server to make cocoon runnable.
    ApplicationServer stop $appserv/
    ApplicationServer start $appserv/

## Installing Cocoon on Inprise Application Server 4.1.1

This has been tested on RedHat, Debian and Windows 2000 with JWS 2.0.

1. Copy all the required jars (see top of page) to the IAS `[path_to_ias]/ias/lib` directory.
2. Start IAS.
3. Open the web server administration interface (not the IAS console) at http://your_host:9090 and login as admin.
4. Select "HTTP Web Engine", the first on the services list.
5. In the "Setup menu" select "Servlet Aliases", press the "add" button and type "`*.xml`" on the left and "`cocoon`" on the right. Remember to press the "Save" button!
6. Press the "Servlet" button (with the gears icon) on the top on the left, then the "add" button. Type as "Servlet Name" "`cocoon`" and "Servlet Class" "`org.apache.cocoon.Cocoon.class`". Press "add". Write whatever description you like and go to press the "Properties" button (on the top). Press "add" and set the init parameter: the name is "properties" and the value is the full path to your `cocoon.properties` file. Press "Save".
7. Choose between "Load at Startup" or "Loaded Now" and press "Save" again.
8. Go to http://localhost:8080/Cocoon.xml and you should see the Cocoon status page.

## 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" files 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.)

This is an EXAMPLE only and may not be up to date. If you get errors, first check that all the required jar files (see top of page) from cocoon/lib are on your CLASSPATH.

    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_15.jar;
    D:/Netscape/Server4/docs/cocoon/lib/turbine-pool.jar;
    D:/Netscape/Server4/docs/cocoon/lib/xalan_1_2_D02.jar;
    D:/Netscape/Server4/docs/cocoon/lib/xerces_1_2.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 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.

Please follow the instructions that apply to your version of JRun, and then the additional general instructions for having the webserver pass requests to Cocoon.

### JRun version 2.3

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

Here is an example: This is an EXAMPLE only and may not be up to date. If you get errors, first check that all the required jar files (see top of page) from cocoon/lib are on your CLASSPATH.

    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

### JRun version 3.0

In addition to the instructions given at the JRun website and below, you also need to do the following to configure XSP and avoid conflicts with JRun 3.0's own XML classes.

1. Make sure you first stop the admin server and the default server.
2. In JRUN_HOME/lib/global.properties add the line (without any spaces or newlines): `java.classpath={jrun.classpath};{user.classpath};{servlet.classpath}; {jrun.rootdir}/servers/default/cocoon-web-pub/WEB-INF/lib`
3. Delete jaxp.jar and parser.jar - but not xt.jar - from the JRun\lib\ext directory.
4. Copy the xerces.jar which is in the Cocoon package, and also the tools.jar of the JDK 1.2.2 to the JRun\lib\ext directory.
5. Restart the admin server.

Next, 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 NoSuchMethodError, 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 ServletExec 2.2

Add all the required .jar files (see top of page) 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 other platforms

Yet to be written! Volunteers welcome!

Additionally, there are some servlet engines on the Working Systems table below which are not listed above, but have been gotten to work with Cocoon.

# 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
Debian Potato | Apache 1.3.14 | Tomcat 3.2.1 | Sun JDK 1.3
Debian Woody | JWS 2.0 | IAS 4.1.1 | IBM JDK 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.1 | Apache 1.3.14 | Tomcat 3.2.1 | JDK 1.1.6
RedHat Linux 6.2 | Apache 1.3.12 | JRun 3.0 | Sun JDK 1.2.2
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 | JWS 2.0 | IAS 4.1.1 | IBM JDK 1.3
RedHat Linux 6.2 (i686) | Apache 1.3.12 | Resin 1.2.b1 | Sun JDK 1.2.2
RedHat Linux 7.0 | Apache 1.3.12 | JServ 1.1.2 | Sun JDK 1.3
Linux Mandrake 7.0 | Orion/1.0.3 | Sun JDK 1.3.0rc1
SuSE 6.2 Linux | Apache 1.3.14 mod_ssl | JServ 1.1.2 | Sun JDK 1.1.7 / IBM JDK 1.3
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 98 SE | Apache 1.3.12 | Tomcat 3.1 | JDK 1.2
Windows 98 SE | Tomcat 3.2.1 | JDK 1.3
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 | Tomcat 3.1 Milestone 1 | Sun JDK 1.2.2
Windows NT 4.0 SP3 | Apache 1.3.12 | JServ 1.1.2 | Sun JRE 1.2.2
Windows NT 4.0 SP4 | Apache 1.3.12 | Tomcat 3.1 | Sun JDK 1.3
Windows NT 4.0 SP4 | BEA WebLogic Server 5.1 SP3 | Sun JDK 1.2.2
Windows NT 4.0 SP5 | WLS 6.0 Beta | JDK 1.3
Windows NT 4.0 SP5 | IIS 4.0 | JRun 3.0 | 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 SP5 | Apache 1.3.14 | Tomcat 3.2b8 | Sun JDK 1.2.2
Windows NT 4.0 SP6 | Apache 1.3.6 | JDK 1.1.8 | Resin 1.1
Windows NT 4.0 SP6a | Apache 1.3.11 | Apache JServ 1.1 | Sun JDK 1.2.2
Windows NT 4.0 SP6a | Apache 1.3.12 | Tomcat 3.1 | Sun JDK 1.2.2
Windows NT 4.0 SP6a | IIS 4.0 | Tomcat 3.2.1 | Sun JDK 1.3.0
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 Professional | Resin 1.1 | Sun JRE 1.2.2
Windows 2000 Professional | JWS 2.0 | IAS 4.1.1 | Sun JDK 1.3
Windows 2000 Professional | Dynamo 4.5.1 | Sun JDK 1.2.2
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 | Apache 1.3.12 | Tomcat 3.1 | Sun JDK 1.2.2
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 2.6 SPARC | Apache 1.3.14 | JServ 1.1.2 | Sun JDK 1.3
Solaris 7 | Apache 1.3.14 | Locomotive 4.2.0 | JDK 1.3
Solaris 7 | Netscape Enterprise Server 3.2 | JRun 2.3 | Sun JDK 1.2
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 | JDK 1.1.8
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!

Copyright © 1999-2001 The Apache Software Foundation.
All rights reserved.