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 :

• Have some basic knowledge about web applications and application servers in general.
• Know how to deploy a web application into a servlet container.
• Know how to unzip or untar a compressed package.
  

Technical Prerequisites

In order to install Cocoon, you need:

• An operating Java 1.2 (or newer) Virtual Machine.
• A servlet container installed and working correctly.
  

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)

BeginnerInstallTomcatUnix

BeginnerInstallTomcatWindows

Other information sources

• Installation of Cocoon at the official Cocoon - cover download install build and so on.
  

Step I: Get the release

Retrieve the distribution from any of the following locations:

• http://www.apache.org/dist/xml/cocoon/
• http://cocoon.apache.org/dist/
• local mirror
  

Below you find the direct links to some of the packages in the distribution area of Apache cocoon-2.0.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.

• If your servlet container is up and you have configured automatic deployment, cocoon starts operating after a few seconds.
• If your servlet container does not auto-deploy, you must deploy manually.
  

Deploying on an application server:

Please look at the page BeginnerDeployOnAppServer for further infos about deploying
on JBOSS.

Deploying manually:

• Create a folder named cocoon within the webapps folder of your servlet container.
  
• Copy cocoon.war into the newly created folder
• Unzip the war file:

  jar -xf cocoon.war

  
  

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

• Restart your container (if necessary)

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

http://yourContainerAdress:port/cocoon

For a default Tomcat setup, this will be

http://localhost:8080/cocoon

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:

• BeginnerSimpleXSLT: We will show you, how you can setup Cocoon to transform your XML files on the fly using your XSL transformations.
• BeginnerSitemap: We will give you a very brief introduction into the pipeline concept, what it does and how you can use it.
  

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

• Overview: This document presents an overall picture of Apache Cocoon.
• The Sitemap: This document describes the Cocoon sitemap concept in full details, why it's there, what it does, how it works and how you can use it. There is also a graphical overview of the sitemap.
  

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:

access.log
core.log
sitemap.log
error.log

<
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

• AUTHOR-CONTACT: hussayn.dabbous@saxess.comBR
• REVIEWED-BY: Vadim

• REVIEWER-CONTACT:BR