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.

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.

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.

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.

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.

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]/conf/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.

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.

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.

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.

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

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.

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".

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.

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_3.jar; D:/cocoon-1.8/lib/xalan_1_2_2.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/

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

1. Start IAS with the command line options -cploc:front -classpath $CLASSPATH, substituting a classpath with all the required Cocoon jars (see top of page) where you see $CLASSPATH.
2. Open the web server administration interface (not the IAS console) at http://your_host:9090 and login as admin.
3. Select "HTTP Web Engine", the first on the services list.
4. 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!
5. 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".
6. Choose between "Load at Startup" or "Loaded Now" and press "Save" again.
7. Go to http://localhost:8080/Cocoon.xml and you should see the Cocoon status page.

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

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_2.jar; D:/Netscape/Server4/docs/cocoon/lib/xerces_1_2_3.jar

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

	@.*[.]xml=cocoon

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

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.

For the JRun portion, you must add all Cocoon jars to the java.classpath in [jrun-home]/jsm-default/properties/jsm.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, and ensure that xerces.jar comes first.

	java.classpath=[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:[previous-jrun-jars]

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:

	servlet.org.apache.cocoon.Cocoon.code=org.apache.cocoon.Cocoon servlet.org.apache.cocoon.Cocoon.args=properties=[cocoon-home]/conf/cocoon.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

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.

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.

Add your sucessful installation method here. Volunteers welcome!

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.

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.

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

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!