Warning: many pages on this wiki imply that a servlet container must be installed before running Cocoon, this is wrong - see NoServletContainerRequired. A basic installation of Cocoon for test or development purposes can be very simple.

Update The whole procedure has been tested with Cocoon-2.1.5.1 on a Suse Linux 9.1 with j2sdk1.4.2_05 and jakarta-tomcat-5.0.27 and there are no changes so far. For using this instruction you just need to replace cocoon-2.1.4 with cocoon-2.1.5.1.

Update The following procedure I have tested on Debian SID, using Cocoon-2.1.7 with the following customizations:

1. Instead of /opt/cocoon I chose to reference under my user account as follows:

/home/myUserName/path-to-cocoon/

e.g., /home/mdriftmeyer/svnReanimality/reanimCocoon/ with ROOT being named as mentioned below in the base installation instructions.

2. Tomcat tested is Tomcat 5.5.9 [Debian SID still only has Tomcat 4.1.31-3 in the debian repository, at the moment. Work on the Java policies is ongoing and once resolved we should see Tomcat 5.5.9 or later release available in a standard debian package]. The server.xml is edited as follows with one reference change:

  <Host appBase="../cocoon" name="cocoon">
    <Logger className="org.apache.catalina.logger.FileLogger" 
            prefix="cocoon_log." suffix=".txt" timestamp="true"/>
  </Host>

modified with to satisfy /user/path-to-cocoon/ appBase:

  <Host appBase="/home/mdriftmeyer/svnReanimality/reanimCocoon" name="cocoon">
    <Logger className="org.apache.catalina.logger.FileLogger" 
            prefix="cocoon_log." suffix=".txt" timestamp="true"/>
  </Host>

3. Java JDK built and tested is JDK 1.5:

mdriftmeyer@horus:/etc$ java -version
java version "1.5.0_03"
Java(TM) 2 Runtime Environment, Standard Edition (build 1.5.0_03-b07)
Java HotSpot(TM) Client VM (build 1.5.0_03-b07, mixed mode, sharing)
mdriftmeyer@horus:/etc$

- Marc J. Driftmeyer mailto:mjd@reanimality.com


This description has been created on a SuSE Linux 9.0 system with Tomcat 5.0.19 and j2sdk1.4.2_04 installed. As a good starting point for doing virtual hosting with Cocoon, Cocoon will be the default host and will listen to http://cocoon:8080/ instead of http://localhost:8080/cocoon/. Tomcat is already installed in /opt and Cocoon, as shown below, will be installed there as well instead of being deployed to Tomcat's "webapps" directory.

otto@linux:/opt> ls -al
total 3
drwxr-xr-x   14 root     root          400 May  5 16:25 .
drwxr-xr-x   21 root     root          488 May  5 13:28 ..
drwxr-xr-x    6 root     root          352 Apr  1 10:27 OpenOffice.org1.1.1
drwxr-xr-x    3 root     root           72 May  5 16:37 cocoon
drwxr-xr-x    9 root     root          216 Jan 15 07:51 gnome
drwxr-xr-x   12 root     root          376 May  5 17:34 jakarta-tomcat-5
drwxr-xr-x    6 root     root          144 Apr 17 06:37 kde3
otto@linux:/opt>

Get Cocoon

Go to the directory you are using to accept downloads and create a subdirectory cocoon. Use your web browser to download the LatestRelease from a mirror site and save it in the cocoon directory. Step into this cocoon directory and use WGET to download the distribution MD5 hash which corresponds to your release - you must get this directly from the ultimately trusted ASF server. {{{otto@linux:~> cd /tmp/ otto@linux:/tmp> mkdir cocoon otto@linux:/tmp> cd cocoon/ otto@linux:/tmp/cocoon> otto@linux:/tmp/cocoon> wget -nd http://www.apache.org/dist/cocoon/cocoon-2.1.4-src.tar.gz.md5 --15:33:55-- http://www.apache.org/dist/cocoon/cocoon-2.1.4-src.tar.gz.md5

}}} After download is complete you should check MD5 sum of your download. Either do md5sum -c *.md5 or check it manually. Follow the instructions on the Cocoon download pages.

otto@linux:/tmp/cocoon> md5sum cocoon-2.1.4-src.tar.gz
65a099094217ef0621e832ad5aa1cfc9  cocoon-2.1.4-src.tar.gz
otto@linux:/tmp/cocoon> cat cocoon-2.1.4-src.tar.gz.md5
65A099094217EF0621E832AD5AA1CFC9  cocoon-2.1.4-src.tar.gz
otto@linux:/tmp/cocoon>

Unpacking cocoon-2.1.4-src.tar.gz will create a new directory cocoon-2.1.4.

otto@linux:/tmp/cocoon> tar xzf cocoon-2.1.4-src.tar.gz
otto@linux:/tmp/cocoon> ls -al
insgesamt 37717
drwxr-xr-x    3 otto  users         168 2004-05-05 15:48 .
drwxr-xr-x    5 otto  users         128 2004-02-22 11:03 ..
drwxr-xr-x    6 otto  users         648 2004-02-12 09:48 cocoon-2.1.4
-rw-r--r--    1 otto  users    38577140 2004-02-12 10:31 cocoon-2.1.4-src.tar.gz
-rw-r--r--    1 otto  users          59 2004-02-12 10:31 cocoon-2.1.4-src.tar.gz.md5
otto@linux:/tmp/cocoon>

Build Cocoon

Step into cocoon-2.1.4 and list its content. You might read the INSTALL.txt and README.txt files, and check what's about the blocks.properties and build.properties.

otto@linux:/tmp/cocoon> cd cocoon-2.1.4/
otto@linux:/tmp/cocoon/cocoon-2.1.4> ls -al
insgesamt 223
drwxr-xr-x    6 otto  users         648 2004-02-12 09:48 .
drwxr-xr-x    3 otto  users          80 2004-05-05 15:57 ..
-rw-r--r--    1 otto  users        5106 2004-02-12 09:48 blocks.properties
-rw-r--r--    1 otto  users        2149 2004-02-12 09:48 build.bat
-rw-r--r--    1 otto  users        4617 2004-02-12 09:48 build.properties
-rwxr-xr-x    1 otto  users         470 2004-02-12 09:48 build.sh
-rw-r--r--    1 otto  users        2970 2004-02-12 09:48 build.xml
-rw-r--r--    1 otto  users       12233 2004-02-12 09:48 cli.xconf
-rw-r--r--    1 otto  users        6193 2004-02-12 09:48 cocoon.bat
-rwxr-xr-x    1 otto  users        4597 2004-02-12 09:48 cocoon.sh
-rw-r--r--    1 otto  users        3444 2004-02-12 09:48 CREDITS.txt
-rw-r--r--    1 otto  users         277 2004-02-12 09:48 DESKTOP.INI
-rw-r--r--    1 otto  users        3524 2004-02-12 09:48 forrest.properties
-rw-r--r--    1 otto  users       34872 2004-02-12 09:48 gump.xml
-rw-r--r--    1 otto  users        4644 2004-02-12 09:48 INSTALL.txt
-rw-r--r--    1 otto  users        9329 2004-02-12 09:48 KEYS
drwxr-xr-x    2 otto  users        2080 2004-05-05 15:48 legal
drwxr-xr-x    6 otto  users         168 2004-05-05 15:48 lib
-rw-r--r--    1 otto  users        2710 2004-02-12 09:48 README.txt
drwxr-xr-x   12 otto  users         320 2004-02-12 09:48 src
-rw-r--r--    1 otto  users       93042 2004-02-12 09:48 status.xml
drwxr-xr-x   10 otto  users         248 2004-02-12 09:46 tools
otto@linux:/tmp/cocoon/cocoon-2.1.4>

Normally it shouldn't be necessary to do any changes to the above files. You can directly start the program building cocoon.

otto@linux:/tmp/cocoon/cocoon-2.1.4> ./build.sh webapp

Building Cocoon will take some time and generate some output on your screen. Finally it will end up with

BUILD SUCCESSFUL
Total time: 4 minutes 37 seconds
otto@linux:/tmp/cocoon/cocoon-2.1.4>

The building procedure should have created a new directory build within cocoon-2.1.4. You may check it.

otto@linux:/tmp/cocoon/cocoon-2.1.4> cd build/
otto@linux:/tmp/cocoon/cocoon-2.1.4/build> ls -al
insgesamt 1
drwxr-xr-x    4 otto  users         104 2004-05-05 16:10 .
drwxr-xr-x    7 otto  users         672 2004-05-05 16:02 ..
drwxr-xr-x   11 otto  users         392 2004-05-05 16:12 cocoon-2.1.4
drwxr-xr-x    8 otto  users         336 2004-05-05 16:13 webapp

What we are going to use is the subdirectory webapp.

Install Cocoon

All steps until here should have been done without root privileges. Now become root su root and create a cocoon directory within /opt.

otto@linux:/tmp/cocoon/cocoon-2.1.4/build> su root
Password: (Enter your password)
linux:/tmp/cocoon/cocoon-2.1.4/build # mkdir /opt/cocoon

Now move your /tmp/cocoon/cocoon-2.1.4/build/webapp/ directory into /opt/cocoon/.

linux:/tmp/cocoon/cocoon-2.1.4/build # mv webapp/ /opt/cocoon/
linux:/tmp/cocoon/cocoon-2.1.4/build # ls -al /opt/cocoon/
insgesamt 0
drwxr-xr-x    3 root     root           72 2004-05-05 16:35 .
drwxr-xr-x   14 root     root          400 2004-05-05 16:25 ..
drwxr-xr-x    9 otto     users         360 2004-05-05 16:27 webapp
linux:/tmp/cocoon/cocoon-2.1.4/build #

Now, we want Cocoon to act as the Default Context of its own host that we are going to configure in Tomcat. This sounds complicated? So let's do it. In Tomcat's configuration we'll make /opt/cocoon the Application Base for a new host. Any host setup in Tomcat will check its configured Application Base for a subdirectory ROOT and regard this one as its default context. So, let's simply rename our webapp to ROOT, spelt with four upper case letters.

linux:/tmp/cocoon/cocoon-2.1.4/build # cd /opt/cocoon/
linux:/opt/cocoon # ls -al
insgesamt 0
drwxr-xr-x    3 root     root           72 2004-05-05 16:35 .
drwxr-xr-x   14 root     root          400 2004-05-05 16:25 ..
drwxr-xr-x    9 otto     users         360 2004-05-05 16:27 webapp
linux:/opt/cocoon # mv webapp/ ROOT/
linux:/opt/cocoon # ls -al
cinsgesamt 0
drwxr-xr-x    3 root     root           72 2004-05-05 16:37 .
drwxr-xr-x   14 root     root          400 2004-05-05 16:25 ..
drwxr-xr-x    9 otto     users         360 2004-05-05 16:27 ROOT
linux:/opt/cocoon #

This will make ROOT to be recognized by Tomcat as the default webapp in /opt/cocoon/. Now let's make Tomcat regard /opt/cocoon/ as a webapp directory:

Edit server.xml

If you happened to have Tomcat already running, you should stop it now! Go to Tomcat's configuration directory

linux:/opt/cocoon # cd ../jakarta-tomcat-5/conf/
linux:/opt/jakarta-tomcat-5/conf # ls -al
insgesamt 101
drwxr-xr-x    3 root     root          496 2004-05-05 16:26 .
drwxr-xr-x   11 root     root          352 2004-02-25 08:57 ..
drwxr-xr-x    4 root     root           96 2004-02-25 09:09 Catalina
-rw-------    1 root     root         6804 2004-02-14 11:26 catalina.policy
-rw-------    1 root     root         2715 2004-02-14 11:26 catalina.properties
-rw-------    1 root     root          778 2004-02-14 11:26 jk2.properties
-rw-------    1 root     root         1128 2004-02-14 11:26 server-minimal.xml
-rw-r--r--    1 root     root         1756 2004-03-05 12:45 server.xml
-rw-r--r--    1 root     root          433 2004-05-05 16:26 tomcat-users.xml
-rw-------    1 root     root        37477 2004-02-14 11:26 web.xml

and with your favourite editor open the file server.xml. Don't forget to backup a copy before. Search for the starting tag of Catalina Engine

<Engine defaultHost="localhost" name="Catalina">

Below it, add the following lines that create a new host cocoon with an Application Base ../cocoon. The relative path used here starts from $Catalinahome, which in our case is /opt/jakarta-tomcat-5/.

  <Host appBase="../cocoon" name="cocoon">
    <Logger className="org.apache.catalina.logger.FileLogger" 
            prefix="cocoon_log." suffix=".txt" timestamp="true"/>
  </Host>

and change Catalina's default host to cocoon

<Engine defaultHost="cocoon" name="Catalina">

So that, excluded all the comments, the engine "Catalina" now looks like

<Engine defaultHost="cocoon" name="Catalina">

  <Host appBase="../cocoon" name="cocoon">
    <Logger className="org.apache.catalina.logger.FileLogger" 
            prefix="cocoon_log." suffix=".txt" timestamp="true"/>
  </Host>

  <Host appBase="webapps" name="localhost">
    <Logger className="org.apache.catalina.logger.FileLogger" 
            prefix="localhost_log." suffix=".txt" timestamp="true"/>
  </Host>

  <Logger className="org.apache.catalina.logger.FileLogger" 
          prefix="catalina_log." suffix=".txt" timestamp="true"/>

  <Realm className="org.apache.catalina.realm.UserDatabaseRealm"/>

</Engine>

Save your changes and close "server.xml".

Add cocoon to your /etc/hosts file

127.0.0.1 localhost cocoon anyhost otherhost onemorehost

Restart Tomcat and then become normal user

linux:/opt/jakarta-tomcat-5/conf # cd ..
linux:/opt/jakarta-tomcat-5 # bin/startup.sh
Using CATALINA_BASE:   /opt/jakarta-tomcat-5
Using CATALINA_HOME:   /opt/jakarta-tomcat-5
Using CATALINA_TMPDIR: /opt/jakarta-tomcat-5/temp
Using JAVA_HOME:       /usr/lib/java
linux:/opt/jakarta-tomcat-5 #
linux:/opt/jakarta-tomcat-5 # exit
exit
otto@linux:/opt/jakarta-tomcat-5>

Start your browser and follow the link http://cocoon:8080/. It should now take you to Cocoon's welcome page whereas http://localhost:8080/ still will go to Tomcat's welcome page with its docs and examples. And, as we changed Catalina's default host to Cocoon, now any other http://anyhost:8080/ will go to Cocoon as well. We will use this feature for doing "virtual hosting with Cocoon".

If you like to get rid of :8080 in the url, please read the very excellent ApacheModProxy guide.

mailto:volkmar@pogatzki.net

CocoonEasyInstallation (last edited 2009-09-20 23:41:08 by localhost)