BeginnerInstallTomcatWindows

installing tomcat in 15 minutes (cookbook approach for windows)

• TARGET-AUDIENCE: beginners

• COCOON-RELEASES: n.a

• DOCUMENT-STATUS: *draft* reviewed released

This document applies to :

• tomcat-4.1.18 and newer on Windows based Systems
  

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 setup tomcat, the official reference ServletContainer. This approach has been tested with tomcat 4.1.18 and newer releases.

Your basic skills

I assume, you

• have minimal knowledge about webapplications and application servers in general.
• know how to install a package
• basic knowledge of DOS-Box execution
  

Technical prerequisites

In order to install tomcat you need

• an operating Java-1.2, or a newer Java Virtual Machine
  

Links to other information sources

For general infos about installation of tomcat refer to the official Tomcat site. See

http://jakarta.apache.org/tomcat/tomcat-4.1-doc/RUNNING.txt

for download install build and so on.

Step I: Get the distrib

Retrieve the current distribution from

http://apache.serveftp.org/apache-site/dist/jakarta/tomcat-4/binaries/

On the distribution directory you will find several tomcat packages suitable for different operating systems. You would retrieve the .exe version, which comes along with a nice and easy to use install shield. If you want to use winzip, you also can download the zip distribution.

caveat: Make shure, which java version you have installed. If you are running the Java-1.4 runtime or JDK, please retrieve one of the tomcat distributions, which are clearly labeled with jdk14. If you are running a lower version of java, you must download one of the other distributions. You can check from a DOS-Box which java version you are running by issuing the following command:

 java -version 

Step II: Unpack it (if you use the zip-distrib)

NOTE: To avoid errors, make sure that there are no spaces in the path name if you want to use JSP.

unpack the zip-distribution

unpack the distrib to any convenient place. You should use the convention to unpack under the folder

c:\programs\tomcat

install the installshield based exe-version

you may simply call this exe file now. An installer will open up. You may complete the installing process with the given defaults. At the end your tomcat server is ready to operate and you can start it from the start menu

Start -> Programs -> Apache Tomcat 4.* -> Start Tomcat

You are ready with the installation. You may continue at the paragraph "startup Tomcat for the forst time"

Step III: Prepare for startup (only zip-distrib)

Once you have installed tomcat, you need to prepare it for startup. I recommend to try first starting the distribution as is. You only need to modify something, if the following ports are already occupied by some other program:

Please note, that your tomcat server comes with an included http-server. So you don't need a webserver like the apache-server to run your servlets. You simply start tomcat, then you are ready to access it from your browser.

modify the standard port settings

As pointed out above, you need to do this only, if you are shure, that the Tomcat standard ports are already occupied. If you are unshure, just start Tomcat and check for errors telling about
"Adress already bound"-messages. If this occurs, come here and do the following:

• Enter the subfolder named "conf"
  
• edit the file named server.xml
  *Search for the shutdown port definition

  <Server port="8005" shutdown="SHUTDOWN" debug="0">
  

  You may change the port to any convenient number above 1024 and below 32768.
  *Search for the http port definition

  <!-- Define a non-SSL Coyote HTTP/1.1 Connector on port 9011 -->
  <Connector className="org.apache.coyote.tomcat4.CoyoteConnector"
    port="8080" minProcessors="5" maxProcessors="75"
  

  You may change the port to any convenient number above 1024 and below 32768.
  *Search for the Webserver connector

  <!-- Define a Coyote/JK2 AJP 1.3 Connector on port 8009 -->
  <Connector className="org.apache.coyote.tomcat4.CoyoteConnector"
    port="8009" minProcessors="5" maxProcessors="75"
    enableLookups="true" redirectPort="8443"
    acceptCount="10" debug="0" connectionTimeout="0"
    useURIValidationHack="false"
    protocolHandlerClassName="org.apache.jk.server.JkCoyoteHandler"/>
  
  <!-- Define an AJP 1.3 Connector on port 8009 -->
  <!--
  <Connector className="org.apache.ajp.tomcat4.Ajp13Connector"
    port="8009" minProcessors="5" maxProcessors="75"
    acceptCount="10" debug="0"/>
  -->
  

  Depending on your system, either the Coyote/JK2 AJP Connector, the AJP 1.3 Connector is active. The inactive connector is commented out with XML comments of following syntax:

  <!-- anything except 2 consecutive '-' signs -->
  

  You may inactivate both connectors for the moment, but need to reactivate one as soon as you want to connect your Webserver with tomcat.
  

Start your container for the first time

installed exe-version:

from the start menu

Start -> Programs -> Apache Tomcat 4.* -> Start Tomcat

zip-distribution:

Enter the subfolder named "c:\programs\tomcat\bin" of your distribution. You will find a set of usefull batch files:

You may use catalina.bat for the beginning:

cd C:\ptograms\tomcat\jakarta-tomcat-4.1.16\bin
./catalina.bat

You have started tomcat now in foreground. The shell is blocked and tomcat runs. You can stop tomcat by pressing CTRL-C at any time.

An alternative way is to use ./startup.bat instead of ./catalina.bat This would start tomcat in the background sending the screen output into a logfile instead. To stop tomcat in background mode, use the batch file shutdown.bat

Verify operation

Once you have started tomcat, you can use your Browser to access the Welcome page. Assuming you have not modified the server.xml as described above, you may now access Tomcat by typing in your browser:

http://localhost:8080

You might have to replace localhost by the name of your server if your browser runs on a different machine. If you see the Tomcat welcome message, chances are very high, that your installation was correct. If you don't see anything see below.

Where to go next

Now you have managed to install the Tomcat Servlet Container. You have verified, that your container operates in your environment. Now it's time to get cocoon into play. I propose following documents:

BeginnerInstallation: We will show you, how you can setup cocoon within your new Servlet Container.

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 modification of the file $tomcat_root\conf\server.xml

Look at the startup logs

You will find the logs under $tomcat_root/logs This is a typical list of logfiles, you may find:

catalina.out

localhost_log.2003-01-15.txt

catalina_log.2003-01-14.txt

localhost_admin_log.2003-01-14.txt

localhost_examples_log.2003-01-14.txt

• If you encounter any problem with tomcat it is best to first look into catalina.out.
• If you can't find a clue to your problem there, look next at localhost_log.<date>.txt. You should get a clue by now.
• If you still can't access your server with your browser, recheck the first lines of catalina.out and look for following pattern:

  [INFO] Http11Protocol - -Initializing Coyote HTTP/1.1 on port 8080
  Starting service Tomcat-Standalonel
  Apache Tomcat/4.1.18
  

  and verify that your portsettings are corect.
• And don't forget to enter the correct URL to your browser:

  http://localhost:8080
  

• tip - put tools.jar in common/endorsed (in case you get 500 server error trying to run .jsp pages).

page metadata

• AUTHOR: Hussayn Dabbous

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

• REVIEWER-CONTACT:BR