<?xml version="1.0"?>
<!DOCTYPE document SYSTEM "../dtd/document-v10.dtd">
<document>
<header>
<title>Installing Cocoon</title>
<authors>
<person name="Stefano Mazzocchi" email="stefano@apache.org"/>
</authors>
</header>
<body>
<s1 title="System Requirements">
<p>
Cocoon requires the following systems to be already installed in your
system:
</p>
<ul>
<li><strong>Java Virtual Machine</strong>
A Java 1.1 or greater compatible virtual machine must be present for both
command line and servlet type 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.
</li>
<li><strong>Servlet Engine</strong>
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.
</li>
</ul>
</s1>
<s1 title="Required Components">
<p>
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.
</p>
<p>
Cocoon uses an XML parser and an XSLT processor has its basic components and
uses the DOM API to access work with them. For this reason, you need both
DOM-enabled XML parser and XSLT processor. Also, for complex formatting,
Cocoon uses a formatting object renderer and a set of printing classes
to send the page to the client.
</p>
<p>
Being an Apache project, Cocoon focues on Apache technologies and comes
configured to operate with Xerces, Xalan and FOP, but other DOM-aware
components are supported as well (see the <code>cocoon.properties</code>
file for more information on other components supported).
</p>
<p>
For this reason, in order to work out of the box and have complete operation,
you need to download all three packages (Xerces-J, Xalan-J and FOP) from the
<link href="http://xml.apache.org/dist/">xml.apache.org</link> distribution
area. Once you have
all three jar packages required and all other packages that may be required
by these projects, go ahead and follow the instructions for your servlet
engine.
</p>
</s1>
<s1 title="Installing Cocoon">
<p>
Being Cocoon a 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.
</p>
<s2 title="Installing Cocoon on Apache JServ">
<p>
Apache JServ has one configuration file for the whole engine (normally called
<code>jserv.properties</code>) and one for each servlet zone. Please, refer
to the Apache JServ documentation for more information on this.
</p>
<p>
First thing to do is to make sure that the components needed by Cocoon (and
explained in the above paragraphs) are visible. This implies adding this to
the servlet engine classpath by adding a line like this in your
<code>jserv.properties</code> file for each jar package you have to install
after substituting <em>[path-to-jar]</em> with the path to the jar file and
<em>[jar-name]</em> with the package file name.
</p>
<source>wrapper.classpath=[path-to-jar]/[jar-name].jar</source>
<p>
<em>Note:</em> do not add the <code>cocoon.jar</code> package here since
this might corrupt it's normal operation. Here, you should add all the
required packages <em>but</em> Cocoon itself.
</p>
<p>
At this point, you must tell the servlet engine to locate Cocoon (since
you didn't do this in the step right above!). To do this, you should choose
the servlet zone where you want Cocoon to reside. If you don't know what
a servlet zone is, you probably want to open the <code>zone.properties</code>
file that represents the default servlet zone. Now add the
<code>cocoon.jar</code> package to your servlet zone by making sure
a line like this is present in your zone property file.
</p>
<source>repositories=...,[path-to-cocoon]/bin/cocoon.jar</source>
<p>
where ... stands for any other servlet repository the servlet zone already
contains (or might be empty if no other repository is used by this zone) and
<em>[path-to-cocoon]</em> is substitued by the actual path to the <code>
cocoon.jar</code> file.
</p>
<p>
Now the servlet engine knows where to locate the Cocoon servlet
but Cocoon must need to know its configurations to be able to start.
To configure Cocoon, you must pass the <code>cocoon.properties</code>
file location to the servlet by adding the following to the
<code>zone.properties</code> file:
</p>
<source>servlet.org.apache.cocoon.Cocoon.initArgs=properties=[path-to-cocoon]/bin/cocoon.properties</source>
<p>
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
breaf indications and comments on the different configurations, but you
don't need to care about that at this point.
</p>
<p>
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 <code>mod_jserv.conf</code> or <code>jserv.conf</code> file:
</p>
<source>ApJServAction .xml /servlet/org.apache.cocoon.Cocoon</source>
<p>
where <em>.xml</em> is the file extention you want to map to the servlet
and <em>/servlet/</em> is the mount point of your servlet zone (and the
above is the standard name for servlet mapping for Apache JServ).
</p>
<p>
Everything should be configured fine. Restart both Apache and Apache JServ
and try accessing the samples contained in the distribution to see
Cocoon in action.
</p>
</s2>
<s2 title="Installing Cocoon on Apache Tomcat">
<p>Yet to be written! <em>Volunteers welcome!</em></p>
</s2>
<s2 title="Installing Cocoon on Allaire JRun">
<p>Yet to be written! <em>Volunteers welcome!</em></p>
</s2>
<s2 title="Installing Cocoon on NewAtlanta ServletExec">
<p>Yet to be written! <em>Volunteers welcome!</em></p>
</s2>
</s1>
<s1 title="Working Systems">
<p>
Cocoon has been reported to be working on these systems:
</p>
<ul>
<li>RedHat Linux 6.0 + Apache 1.3.9 + Apache JServ 1.0 + IBM JDK 1.1.8</li>
<li>RedHat Linux 6.0 + Apache 1.3.9 + Apache JServ 1.1b3 + IBM JDK 1.1.8</li>
<li>RedHat Linux 6.0 + Apache 1.3.9 + Apache JServ 1.0 + Blackdown JDK 1.2pre2</li>
<li>RedHat Linux 6.1 + Apache 1.3.9 + JRun 2.3.3 + IBM JRE 1.1.8</li>
<li>Windows 98 + Apache 1.3.9 + Apache JServ 1.0 + IBM JDK 1.1.7</li>
<li>Windows 98 + Apache 1.3.9 + Apache JServ 1.1b3 + IBM JDK 1.1.7</li>
<li>Windows 98 + Apache 1.3.9 + Apache JServ 1.0 + Sun JDK 1.2.2</li>
<li>Windows 98 + Apache 1.3.9 + Apache JServ 1.1b3 + Sun JDK 1.2.2</li>
<li>Windows 98 + MS Personal Web Server + ServletExec 2.2 + Sun JDK 1.2.1</li>
<li>Windows NT 4.0 + IIS 4.0 + ServletExec 2.2 + Sun JDK 1.2.1</li>
<li>Windows NT 4.0 + IIS 4.0 + JRun 2.3.3 + Sun JDK 1.2.1</li>
<li>MacOS 8.6 + WebSTAR 4.0 + JRun 2.3 + MrJ 2.1.4</li>
<li>MacOS 8.6 + WebSTAR 4.0 + ServletExec 2.1 + Mrj 2.1.4</li>
<li>SunOS Netria 5.6 + Apache 1.3.9 + Apache JServ 1.1b3 + Sun JDK 1.1.7</li>
<li>SCO OpenServer 5 + WebLogic 4.5.1 + SCO JDK 1.1.7A</li>
</ul>
<p>
<em>Note:</em> due to a bug in <link href="http://www.blackdown.org">Blackdown
JDK 1.2pre2</link> for Linux, we suggest you to use green threads instead of the
native ones which are much less stable, expecially highly concurrent operations
like servlet engines and servlet execution.
</p>
<p>
Please, submit your feedback if you were able to install Cocoon on a
different combination not listed above. Thanks.
</p>
</s1>
</body></document>