RUNNING.txt

================================================================================
  Licensed to the Apache Software Foundation (ASF) under one or more
  contributor license agreements.  See the NOTICE file distributed with
  this work for additional information regarding copyright ownership.
  The ASF licenses this file to You under the Apache License, Version 2.0
  (the "License"); you may not use this file except in compliance with
  the License.  You may obtain a copy of the License at

      http://www.apache.org/licenses/LICENSE-2.0

  Unless required by applicable law or agreed to in writing, software
  distributed under the License is distributed on an "AS IS" BASIS,
  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  See the License for the specific language governing permissions and
  limitations under the License.
================================================================================

$Id$

            ===================================================
            Running The Apache Tomcat @VERSION_MAJOR_MINOR@ Servlet/JSP Container
            ===================================================

Apache Tomcat @VERSION_MAJOR_MINOR@ requires the Java Standard Edition Runtime
Environment (JRE) version 6.0 or later.

=============================
Running With JRE 6.0 Or Later
=============================

(1) Download and Install the Java SE Runtime Environment (JRE)

(1.1) Download the Java SE Runtime Environment (JRE),
      release version 6.0 or later, from
      http://www.oracle.com/technetwork/java/javase/downloads/index.html

(1.2) Install the JRE according to the instructions included with the
      release.

(1.3) Set an environment variable named JRE_HOME to the pathname of
      the directory into which you installed the JRE, e.g. c:\jre6.0
      or /usr/local/java/jre6.0.

NOTE: You may also use the full JDK rather than just the JRE. In this
      case set your JAVA_HOME environment variable to the pathname of
      the directory into which you installed the JDK, e.g. c:\jdk6.0
      or /usr/local/java/jdk6.0.


(2) Download and Install the Tomcat Binary Distribution

NOTE:  As an alternative to downloading a binary distribution, you can create
your own from the Tomcat source repository, as described in "BUILDING.txt".
If you do this, the value to use for "${catalina.home}" will be the "dist"
subdirectory of your source distribution.

(2.1) Download a binary distribution of Tomcat from:

      http://tomcat.apache.org/

(2.2) Unpack the binary distribution into a convenient location so that the
      distribution resides in its own directory (conventionally named
      "apache-tomcat-[version]").  For the purposes of the remainder of this document,
      the symbolic name "$CATALINA_HOME" is used to refer to the full
      pathname of the release directory.

NOTE: The scripts expect that the $CATALINA_HOME environment variable is
either set to the correct value, as defined above, or is absent. In the
latter case the scripts will try to calculate the value for $CATALINA_HOME
by themselves.


(3) Start Up Tomcat

(3.1) Tomcat can be started by executing the following commands:

      $CATALINA_HOME\bin\startup.bat          (Windows)

      $CATALINA_HOME/bin/startup.sh           (Unix)

(3.2) After startup, the default web applications included with Tomcat will be
      available by visiting:

      http://localhost:8080/

(3.3) Further information about configuring and running Tomcat can be found in
      the documentation included here, as well as on the Tomcat web site:

      http://tomcat.apache.org/


(4) Shut Down Tomcat

(4.1) Tomcat can be shut down by executing the following command:

      $CATALINA_HOME\bin\shutdown            (Windows)

      $CATALINA_HOME/bin/shutdown.sh         (Unix)


==================================================
Advanced Configuration - Multiple Tomcat Instances
==================================================

In many circumstances, it is desirable to have a single copy of a Tomcat
binary distribution shared among multiple users on the same server.  To make
this possible, you can set the $CATALINA_BASE environment variable to the
directory that contains the files for your 'personal' Tomcat instance.

When running with separate $CATALINA_HOME and $CATALINA_BASE, the files
and directories are split as following:

In $CATALINA_BASE:

 * bin  - Only the following files:
          setenv.sh (*nix), setenv.bat (windows) and tomcat-juli.jar

 * conf - Server configuration files (including server.xml)

 * lib  - Libraries

 * logs - Log and output files

 * webapps - Automatically loaded web applications

 * work - Temporary working directories for web applications

 * temp - Directory used by the JVM for temporary files (java.io.tmpdir)


In $CATALINA_HOME:

 * bin  - Startup and shutdown scripts

          The following files will be used only if they are absent in
          $CATALINA_BASE/bin:

          setenv.sh (*nix), setenv.bat (windows) and tomcat-juli.jar

 * lib  - Libraries

 * endorsed - Libraries that override standard "Endorsed Standards"
          libraries provided by JRE. See Classloading documentation
          in the User Guide for details. This directory is not created by
          default.

If $CATALINA_BASE environment variable is not set, it will default to the
same value as $CATALINA_HOME, which means that the same directory is used
for all relative path resolutions.


By default Tomcat will first try to load classes and JARs from
$CATALINA_BASE/lib and then from $CATALINA_HOME/lib. You may place instance
specific JARs and classes (e.g. JDBC drivers) in $CATALINA_BASE/lib whilst
keeping the standard Tomcat JARs in $CATALINA_HOME/lib.


The values of $CATALINA_BASE and $CATALINA_HOME are available in XML
configuration files processed by Tomcat as ${catalina.base} and
${catalina.home} respectively.


======================================
Using setenv.* to Tune Tomcat Scripts
======================================

The scripts used to run Tomcat can be further configured by setting several
environment variables. For the list of these environent variables see the
comment at the top of catalina.sh or .bat script.

The setenv.sh (*nix) or setenv.bat (windows) script can be used to
configure all those variables except $CATALINA_BASE and $CATALINA_HOME. The
standard scripts will execute the setenv.* script when it is present either
in $CATALINA_BASE/bin or in $CATALINA_HOME/bin.


================
Troubleshooting
================

There are only really 3 things likely to go wrong during the stand-alone
Tomcat install:

(1) The most common hiccup is when another web server (or any process for that
    matter) has laid claim to port 8080.  This is the default HTTP port that
    Tomcat attempts to bind to at startup.  To change this, open the file:

       $CATALINA_HOME/conf/server.xml

    and search for '8080'.  Change it to a port that isn't in use, and is
    greater than 1024, as ports less than or equal to 1024 require superuser
    access to bind under UNIX.

   Restart Tomcat and you're in business.  Be sure that you replace the "8080"
   in the URL you're using to access Tomcat.  For example, if you change the
   port to 1977, you would request the URL http://localhost:1977/ in your browser.

(2) An "out of environment space" error when running the batch files in
    Windows 95, 98, or ME operating systems.

    Right-click on the STARTUP.BAT and SHUTDOWN.BAT files.  Click on
    "Properties", then on the "Memory" tab.  For the "Initial environment" field,
    enter in something like 4096.

    After you click apply, Windows will create shortcuts which you can use
    to start and stop the container.

(3) The 'localhost' machine isn't found.  This could happen if you're behind a
    proxy.  If that's the case, make sure the proxy configuration for your
    browser knows that you shouldn't be going through the proxy to access the
    "localhost".

    In Netscape, this is under Edit/Preferences -> Advanced/Proxies, and in
    Internet Explorer, Tools -> Internet Options -> Connections -> LAN Settings.