================================================================================ 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. You may also use the full JDK rather than just the JRE. In this case set you have to configure your environment variables differently - see below. (2) Download and Install the Tomcat Binary 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 name "CATALINA_HOME" is used to refer to the full pathname of the release directory. NOTE: As an alternative to downloading a binary distribution, you can create your own from the Tomcat source code, as described in "BUILDING.txt". You can either a) Do the full "release" build and find the created distributive in the "output/release" directory and then proceed with unpacking as above, or b) Do a simple build and use the "output/build" directory as "CATALINA_HOME". Be warned that there are some differences between contents of "output/build" and the official "release" distributive. (3) Configure Environment Variables Tomcat itself is a Java application and does not use environment variables, but the startup scripts use them to prepare the command that starts Tomcat. The full list of supported environment variables is provided as a comment at the top of catalina.bat (Windows) and catalina.sh (Unix) files. (3.1) CATALINA_HOME and CATALINA_BASE The CATALINA_HOME and CATALINA_BASE environment variables are used to specify location of Tomcat itself and of its active configuration respectively. The CATALINA_HOME environment variable should be set as defined in (2.2) above. The startup scripts have some logic to set this variable automatically if it is absent (based on the location of the script in Unixes and on the current directory in Windows), but it might be not perfect. The CATALINA_BASE environment variable is optional and is further described in "Multiple Tomcat Instances" section below. If it is not set it defaults to be equal to CATALINA_HOME. (3.2) JRE_HOME and other variables The third and the last environment variable that is needed to start Tomcat specifies location of JRE or JDK that should be used to start Tomcat. There are two different names of this variable, depending on whether JRE or JDK is used. Use the JRE_HOME variable to specify location of a JRE and JAVA_HOME variable to specify location of a JDK. All variables except CATALINA_HOME and CATALINA_BASE can be configured in a setenv.bat (Windows) or setenv.sh (Unix) file. The setenv file can be either in CATALINA_BASE/bin or in CATALINA_HOME/bin. If both are present, only the one in CATALINA_BASE is used. So, either set JRE_HOME variable by yourselves or create the file. For example, On Windows, %CATALINA_BASE%\bin\setenv.bat: set "JRE_HOME=%ProgramFiles%\Java\jre6" exit /b 0 On Unix, $CATALINA_BASE/bin/setenv.sh: JRE_HOME=/usr/java/latest (4) Start Up Tomcat (4.1) Tomcat can be started by executing one of the following commands: %CATALINA_HOME%\bin\startup.bat (Windows) $CATALINA_HOME/bin/startup.sh (Unix) or %CATALINA_HOME%\bin\catalina.bat start (Windows) $CATALINA_HOME/bin/catalina.sh start (Unix) (4.2) After startup, the default web applications included with Tomcat will be available by visiting: http://localhost:8080/ (4.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/ (5) Shut Down Tomcat (5.1) Tomcat can be shut down by executing one of the following commands: %CATALINA_HOME%\bin\shutdown.bat (Windows) $CATALINA_HOME/bin/shutdown.sh (Unix) or %CATALINA_HOME%\bin\catalina.bat stop (Windows) $CATALINA_HOME/bin/catalina.sh stop (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) or setenv.bat (Windows), * tomcat-juli.jar The setenv scripts were described above. The tomcat-juli library is documented in the Logging chapter in the User Guide. * conf - Server configuration files (including server.xml) * lib - Libraries and classes * 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), tomcat-juli.jar * lib - Libraries and classes, as explained below * endorsed - Libraries that override standard "Endorsed Standards" libraries provided by JRE. See Classloading documentation in the User Guide for details. By default this "endorsed" directory is absent. In the default configuration the JAR libraries and classes both in CATALINA_BASE/lib and in CATALINA_HOME/lib will be added to the common classpath, but the ones in CATALINA_BASE will be added first and thus will be searched first. The idea is that you may leave the standard Tomcat libraries in CATALINA_HOME/lib and add other ones such as database drivers into CATALINA_BASE/lib. In general it is advised to never share libraries between web applications, but put them into WEB-INF/lib directories inside the applications. See Classloading documentation in the User Guide for details. It might be useful to note that the values of CATALINA_HOME and CATALINA_BASE can be referenced in the XML configuration files processed by Tomcat as ${catalina.home} and ${catalina.base} respectively. For example, the standard manager web application can be kept in CATALINA_HOME/webapps/manager and loaded into CATALINA_BASE by using the following trick: * Copy the CATALINA_HOME/webapps/manager/META-INF/context.xml file as CATALINA_BASE/conf/Catalina/localhost/manager.xml * Add docBase attribute as shown below. The file will look like the following: See Deployer chapter in User Guide and Context and Host chapters in the Configuration Reference for more information on contexts and web application deployment. ================ 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 Firefox, this is under Tools/Preferences -> Advanced/Network -> Connection -> Settings..., and in Internet Explorer it is Tools -> Internet Options -> Connections -> LAN Settings.