First thing to do is to make sure that Cocoon and all the needed components (as explained in the previous section) are visible. This implies adding this 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 perfectly understand this as a limitation to Cocoon flexibility, and we are working hard to make it possible for multiple cocoon instances to reside in the same JVM, unfortunately some limitations in Java 1.1 make this impossible at this time.

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

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 the file that contains breaf 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).

You need to make sure that you 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.

For any problem, please go to the FAQ list before submitting a bug report or a request for help on the mail lists. Thank you.

Tomcat has two basic methods of locating Java classes for the runtime environment. The first is the overall classpath that Tomcat uses to run, and this is the classpath provided to Java classes that use constructs such as Class.forName().newInstance(). The second classpath is associated with a specific context, and is somewhat analagous to the servlet zones used in Apache JServ (see section above).

Because the Cocoon framework utilizes Class.forName() and other dynamic instance handling techniques, the Cocoon classes need to have its classpath aware of the component classes used within the framework. To do this, take all the required components (see above) and put them in your <Tomcat-Root>/lib directory. This is the standard location for Tomcat core libraries. To ensure that Tomcat will use these, you need to edit the Tomcat startup file.

On Windows, this is <Tomcat-Root>/tomcat.bat and on Unix, this is <Tomcat-Root>/tomcat.sh. In this file you must add all the component jar files to Tomcat's classpath.

the cocoon.jar package should be added to the servlet engine classpath as any other required package (as shown above).

Next you need to tell your context where Cocoon can find it's properties file, as well as to map Cocoon to XML document requests. Make sure you have a web.xml file in your context's WEB-INF directory (look in src/WEB-INF/ to find a template web.xml). This file specifies servlet mappings and initial arguments to servlets and looks like this:

	<servlet> <servlet-name>org.apache.cocoon.Cocoon</servlet-name> <servlet-class>org.apache.cocoon.Cocoon</servlet-class> <init-param> <param-name>properties</param-name> <param-value> [path-to-cocoon.properties]/cocoon.properties </param-value> </init-param> </servlet> <servlet-mapping> <servlet-name>org.apache.cocoon.Cocoon</servlet-name> <url-pattern>*.xml</url-pattern> </servlet-mapping>

Make sure you replaced the path to the Cocoon.properties file with the location of that file on your system, relative to the context root. Even if you start the filename with a / it will still be relative to the context root.

Because Cocoon now (since version 1.7.3) uses getResource() in the Servlet API to read cocoon.properties, and has different instances for each servlet context, you need to put a copy of cocoon.properties in all of your servlet contexts that use Cocoon. (It is recommended to put it in the context's WEB-INF directory, or a password-protected directory, to prevent anyone from being able to read it over the web.) However, you cannot use symbolic links on Unix to point to a file outside of the current context, because Tomcat does not allow it for security reasons.

the cocoon.properties file must be referenced with relative paths in WEB-INF/web.xml, otherwise, Cocoon won't be able to locate it's properties and won't be able to start.

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

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.

If you have upgraded Cocoon from an older version and Cocoon won't initialize, either ensure that you are using the latest cocoon.properties - or, if you are have some non-standard properties in cocoon.properties which you need to keep, refer to the latest cocoon.properties to find out what changes need to be made, if any.

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

Tomcat 3.0 has a bug that prevents Cocoon operation, please download a later version.

Due to DOM level1 and DOM level2 incompatibilities, make sure that xerces.jar is located before xml.jar since Xerces contains DOM2 (which is needed by Cocoon) while ProjectX contains DOM1 (which will generate runtime exceptions with Cocoon).

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.

Yet to be written! Volunteers welcome!