Installing cocoon (cookbook approach)

- TARGET-AUDIENCE: *beginner* advanced expert
- COCOON-RELEASES: 2.0.3, 2.0.4
- DOCUMENT-STATUS: *draft* reviewed released

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.

What you will get from this page

You will learn how to retrieve and deploy Cocoon into a running servlet container. This approach has been tested with tomcat 4.1.16 and newer releases. It should also work for other servlet containers. This only applies to binary releases (ended as of 2.0.4), so you'll need to find a tutorial on installing 2.1 somewhere else.

Skills Requirements

I assume you :

Technical Prerequisites

In order to install Cocoon, you need:

If you don't have a servlet container running on your computer, or you don't know what a servlet container is, you may look at the related documents covering basic installation issues:

CocoonDistSetupWin2000 (covers java and tomcat installation)

Other information sources

Step I: Get the release

Retrieve the distribution from any of the following locations:

Below you find the direct links to some of the packages in the distribution area of Apache cocoon-2.0.4:

||cocoon-2.0.4-bin.tar.gz||17M||Latest binary distribution for JDK 1.2/1.3 ||||19M||Latest binary distribution for JDK 1.2/1.3 ||cocoon-2.0.4-vm14-bin.tar.gz||17M||Latest binary distribution for JDK 1.4 ||||19M||Latest binary distribution for JDK 1.4

Step II: Unpack Cocoon

Unpack downloaded archive to any convenient place. You will get a directory tree that starts with cocoon-2.0.4. Within this directory tree, you find the web application archive cocoon.war at the top level. Besides this, you find a whole set of documentation in HTML format under the subdirectory "docs".

Step III: Deploy Cocoon

Copy the file cocoon.war into the web applications folder of your servlet container. On Tomcat, this will be the webapps folder within the main Tomcat folder.

Deploying on an application server:

Deploying manually:

After unzipping you will see a complete webapp folder structure containing your cocoon web application.

After your container is ready for operation, you can switch to your browser and enter


For a default Tomcat setup, this will be


You will get the welcome message from Cocoon. Congratulations. You have mastered the first step to XML publishing.

Where to go next

Now you have managed to install the Cocoon publishing framework, and it's time to start some serious investigations on what you have installed at all. I propose following documents:

You can also move on to the Cocoon documentation set and have a look into these online documents:

If you want to start building and deploying Cocoon applications elsewhere, you will probably need a MinimalCocoonConfiguration.

First aid if something goes wrong.

There is always the chance, that something goes wrong during setup. The most critical part of the installation is the insertion of the webapp into the container environment. With Tomcat this is usually no big deal at all.

Here are some tips, how to proceed if Cocoon won't show up.

Look at the startup logs of your container.

For Tomcat you will find the logs under $TOMCAT_ROOT/logs For other containers you need to know by yourself.

Look at the Cocoon logs

You will find the cocoon logs within the Cocoon webapp under the folder WEB-INF/logs. Once you moved to this folder you will find four log files:


< Search within these files for java exception stack traces. You will find the root causes of all your problems near the beginning of the log files. Unfortunately you will get faced with some very nasty technical information which usually is good for developers only. Still you may find a clue to your problem within these logs. Hint: look at the beginning of a stacktrace block - especially for XSLT errors, a meaningful hint can be found on the first line (you might have to scroll to the right).

page metadata

- AUTHOR: Hussayn Dabbous

BeginnerInstallation (last edited 2009-09-20 23:42:39 by localhost)