






































|
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.
 |
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.
|
|
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 |  |  |  |  |
 |  |  |  | Installing Cocoon on BEA WebLogic (version 4.5.1) |  |  |  |  |
 |  |  |  | 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.
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 |  |  |  |  |
 |  |  |  | Installing Cocoon on iPlanet Web Server 4.x |  |  |  |  |
|
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!
|
|
|