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.
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.
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:
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:
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 ||cocoon-2.0.4-bin.zip||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 ||cocoon-2.0.4-vm14-bin.zip||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.
- 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.
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
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:
- 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.
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).
- AUTHOR: Hussayn Dabbous
- AUTHOR-CONTACT: mailto:firstname.lastname@example.org[[BR]] - REVIEWED-BY: Vadim