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.
Tomcat 5.0.18/Cocoon 2.1.3 on Windows 2000 with j2sdk1.4.2_01
(courtesy of Jim Bloggs)
For Windows XP guide using j2sdk1.5.0_05,Tomcat 5.5.12, Cocoon 2.1.7, see WindowsXpJdkTomcatCocoonInstallation.
11 February 2004
Other Versions These same instructions should work for:
- any recent tomcat
- any jdk1.4
- any cocoon release or cvs snapshot.
- any windows environment (except probably 95, 98, maybe ME)
Installing Tomcat and Cocoon is easy if you know how, but can be complicated if you don't.
As I went through it, I promised myself I would make notes once I'd finished.
Outlined below are the steps I took to install Cocoon 2.1.3 on Tomcat 5.0.18 on Windows 2000 with
j2sdk1.4.2_01. I hope they help.
The following assumes you have already installed Sun's Java Development Kit (j2sdk1.4.2_01) in
directory c:\j2skd1.4.2_01.
1. Do this: Download the file called 5.0.18.zip from the
Tomcat 5.0.18 section near the bottom
of the Release Builds section:http://jakarta.apache.org/site/binindex.cgi
Consider this: It may be possible to use the .exe or Deployer files instead, but I used the zip.
2. Do this: Extract everything to c:\ using Winzip, which should create a directory called:
c:\jakarta-tomcat-5.0.18 {{{Consider this: You can tell Winzip will create a subdirectory by looking at the value in the path column
on the right hand side.}}}
3. Do this: Set the JAVA_HOME and CATALINA_HOME environment variables.
Right-click My Computer > Properties > Advanced > Environment variables... > System Variable pane, New... etc.
JAVA_HOME c:\j2sdk1.4.2_01 CATALINA_HOME c:\jakarta-tomcat-5.0.18{{{Consider this: Environment variables can also be set in a DOS box using DOS commands, but in that case,
they are only meaningful within and for the lifetime of that DOS box.}}}
4. Do this: Test the server by running the batch file provided.
c:\jakarta-tomcat\bin\startup.bat {{{Consider this: This is only one way of running the server. A better way is to install it as a Windows
service.}}}
5. Do this: View the default installation screen. The screen should be available when you see the message
INFO:Server startup in <nnnnn>ms, by visiting:
http://localhost:8080/ {{{Consider this: Tomcat listens on port 8080 by default. Apache listens on port 80 by default. Browsers
normally hit on port 80 unless told otherwise.}}}
6. Do this: Stop the server by running the batch file provided.
c:\jakarta-tomcat\bin\shutdown.bat {{{Consider this: Because the batch file appears to hang, you will need to run this batch file from another
DOS window.}}}
7. Do this: Install Tomcat as a Windows service by running the batch file provided.
c:\jakarta-tomcat\bin\service.bat
Consider this: Windows services can be controlled independently throught the Services control panel.
8. Do this: Change the service status to automatic for automatic start on reboot. The service should be named Apache Tomcat in:
Control Panel > Administrative Tools > Services
Consider this: You can start, stop and restart any service using the corresponding button in the top panel.
9. Do this: Download the file called cocoon-latest-src.zip from:
http://cocoon.apache.org/mirror.cgi
Consider this: It is necessary to download the entire source which can take a long time.
10. Do this: Extract the source to c:\ using Winzip, which should place everything in a directory called:
c:\cocoon-2.1.3
Consider this: You can find more details on installing Cocoon in c:\cocoon-2.1.3\INSTALL.txt
11. Do this: Build the binary. It may run for quite a while, in my case 30 mins.
build {{{Consider this: During this time there will be many disturbing warning messages. You can see other build
options by doing build -projecthelp}}}
12. Do this: Test Cocoon in the Jetty Servlet container.
cocoon servlet {{{Consider this: Jetty is provided with Cocoon so that it can be tested independently of a separately
installed servlet container such as Tomcat.}}}
13. Do this: View the Cocoon default installation screen here:
http://localhost:8888/ {{{Consider this: Jetty listens on port 8888, but in a moment, we will configure Cocoon to run with Tomcat
on port 8080.}}}
14. Do this: Stop the Jetty server.
^C
Consider this: Although inelegant, I couldn't find any other way of stopping Jetty.
15. Do this: Copy over the Xalan parser to Tomcat. Bit vague about this step, but seemed to work for me.
copy c:\cocoon-2.1.3\lib\endorsed\xalan.2.5.2.jar c:\jakarta-tomcat-5.0.18\common\endorsed\ {{{Consider this: The docs suggested copying over xercesXXX.jar and xml-apis.jar, but I omitted to because
the versions that came with Tomcat were dated after those shipping with Cocoon.}}} ;:This is changed with the latest release of Cocoon 2.1.4, so please check for yourself -HvdL
16. Do this: Copy over the webapp directory hierarchy as a subdirectory of the Tomcat webapps directory named cocoon
xcopy c:\cocoon-2.1.3\build\webapp c:\jakarta-tomcat-5.0.18\webapps\cocoon /D /S /V /I /F {{{Consider this: Alternatively, using Windows explorer, drag and drop the webapp folder into the webapps
folder whilst holding down the <ctrl> key. Then select the webapp folder, hit F2, and rename it cocoon.}}}
17. Do this: Restart Tomcat from the services window:
Control Panel > Administrative Tools > Services
Consider this: Tomcat should find Cocoon when it restarts.
18. Do this: View the Cocoon startup screen which should be avaliable here:
http://localhost:8080/cocoon/ {{{Consider this: The first time you run Cocoon, it will take some time to compile. You can create a more lean
and mean Cocoon by creating and editing the files local.build.properties and local.blocks.properties.}}}
19. Do this: Delete the source if you desire to save space and keep things tidy.
rd /S c:\cocoon-2.1.3 {{{Consider this: If you choose to keep the source and rebuild Cocoon later, you will have to clear out
the build directory by doing build clean}}}