305 lines
11 KiB
XML
305 lines
11 KiB
XML
<?xml version="1.0" encoding="UTF-8"?>
|
|
<!--
|
|
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.
|
|
-->
|
|
<!DOCTYPE document [
|
|
<!ENTITY project SYSTEM "project.xml">
|
|
]>
|
|
<document url="introduction.html">
|
|
|
|
&project;
|
|
|
|
<properties>
|
|
<author email="rslifka@sfu.ca">Robert Slifka</author>
|
|
<title>Introduction</title>
|
|
</properties>
|
|
|
|
<body>
|
|
|
|
<section name="Table of Contents">
|
|
<toc/>
|
|
</section>
|
|
|
|
<section name="Introduction">
|
|
|
|
<p>For administrators and web developers alike, there are some important bits
|
|
of information you should familiarize yourself with before starting out. This
|
|
document serves as a brief introduction to some of the concepts and
|
|
terminology behind the Tomcat container. As well, where to go when you need
|
|
help.</p>
|
|
|
|
</section>
|
|
|
|
|
|
<section name="Terminology">
|
|
|
|
<p>In the course of reading these documents, you will run across a number of
|
|
terms; some specific to Tomcat, and others defined by the
|
|
<a href="https://wiki.apache.org/tomcat/Specifications">Servlet and
|
|
JSP specifications</a>.</p>
|
|
|
|
<ul>
|
|
<li><strong>Context</strong> - In a nutshell, a Context is a
|
|
web application.</li>
|
|
</ul>
|
|
<p>That is it. If you find any more terms we need to add to this section, please
|
|
do let us know.</p>
|
|
|
|
</section>
|
|
|
|
|
|
<section name="Directories and Files">
|
|
|
|
<p>These are some of the key tomcat directories:</p>
|
|
|
|
<ul>
|
|
<li><strong>/bin</strong> - Startup, shutdown, and other scripts. The
|
|
<code>*.sh</code> files (for Unix systems) are functional duplicates of
|
|
the <code>*.bat</code> files (for Windows systems). Since the Win32
|
|
command-line lacks certain functionality, there are some additional
|
|
files in here.</li>
|
|
<li><strong>/conf</strong> - Configuration files and related DTDs. The most
|
|
important file in here is server.xml. It is the main configuration file
|
|
for the container.</li>
|
|
<li><strong>/logs</strong> - Log files are here by default.</li>
|
|
<li><strong>/webapps</strong> - This is where your webapps go.</li>
|
|
</ul>
|
|
|
|
</section>
|
|
|
|
<section name="CATALINA_HOME and CATALINA_BASE">
|
|
<p>Throughout the documentation, there are references to the two following
|
|
properties:
|
|
<ul>
|
|
<li>
|
|
<strong>CATALINA_HOME</strong>: Represents the root of your Tomcat
|
|
installation, for example <code>/home/tomcat/apache-tomcat-9.0.10</code>
|
|
or <code>C:\Program Files\apache-tomcat-9.0.10</code>.
|
|
</li>
|
|
<li>
|
|
<strong>CATALINA_BASE</strong>: Represents the root of a runtime
|
|
configuration of a specific Tomcat instance. If you want to have
|
|
multiple Tomcat instances on one machine, use the <code>CATALINA_BASE</code>
|
|
property.
|
|
</li>
|
|
</ul>
|
|
</p>
|
|
<p>
|
|
If you set the properties to different locations, the CATALINA_HOME location
|
|
contains static sources, such as <code>.jar</code> files, or binary files.
|
|
The CATALINA_BASE location contains configuration files, log files, deployed
|
|
applications, and other runtime requirements.
|
|
</p>
|
|
<subsection name="Why Use CATALINA_BASE">
|
|
<p>
|
|
By default, CATALINA_HOME and CATALINA_BASE point to the same directory.
|
|
Set CATALINA_BASE manually when you require running multiple Tomcat
|
|
instances on one machine. Doing so provides the following benefits:
|
|
</p>
|
|
<ul>
|
|
<li>
|
|
Easier management of upgrading to a newer version of Tomcat. Because all
|
|
instances with single CATALINA_HOME location share one set of
|
|
<code>.jar</code> files and binary files, you can easily upgrade the files
|
|
to newer version and have the change propagated to all Tomcat instances
|
|
using the same CATALIA_HOME directory.
|
|
</li>
|
|
<li>
|
|
Avoiding duplication of the same static <code>.jar</code> files.
|
|
</li>
|
|
<li>
|
|
The possibility to share certain settings, for example the <code>setenv</code> shell
|
|
or bat script file (depending on your operating system).
|
|
</li>
|
|
</ul>
|
|
</subsection>
|
|
<subsection name="Contents of CATALINA_BASE">
|
|
<p>
|
|
Before you start using CATALINA_BASE, first consider and create the
|
|
directory tree used by CATALINA_BASE. Note that if you do not create
|
|
all the recommended directories, Tomcat creates the directories
|
|
automatically. If it fails to create the necessary directory, for example
|
|
due to permission issues, Tomcat will either fail to start, or may not
|
|
function correctly.
|
|
</p>
|
|
<p>
|
|
Consider the following list of directories:
|
|
<ul>
|
|
<li>
|
|
<p>
|
|
The <code>bin</code> directory with the <code>setenv.sh</code>,
|
|
<code>setenv.bat</code>, and <code>tomcat-juli.jar</code> files.
|
|
</p>
|
|
<p>
|
|
<i>Recommended:</i> No.
|
|
</p>
|
|
<p>
|
|
<i>Order of lookup:</i> CATALINA_BASE is checked first; fallback is provided
|
|
to CATALINA_HOME.
|
|
</p>
|
|
</li>
|
|
<li>
|
|
<p>
|
|
The <code>lib</code> directory with further resources to be added on
|
|
classpath.
|
|
</p>
|
|
<p>
|
|
<i>Recommended:</i> Yes, if your application depends on external libraries.
|
|
</p>
|
|
<p>
|
|
<i>Order of lookup:</i> CATALINA_BASE is checked first; CATALINA_HOME is
|
|
loaded second.
|
|
</p>
|
|
</li>
|
|
<li>
|
|
<p>
|
|
The <code>logs</code> directory for instance-specific log files.
|
|
</p>
|
|
<p>
|
|
<i>Recommended:</i> Yes.
|
|
</p>
|
|
</li>
|
|
<li>
|
|
<p>
|
|
The <code>webapps</code> directory for automatically loaded web
|
|
applications.
|
|
</p>
|
|
<p>
|
|
<i>Recommended:</i> Yes, if you want to deploy applications.
|
|
</p>
|
|
<p>
|
|
<i>Order of lookup:</i> CATALINA_BASE only.
|
|
</p>
|
|
</li>
|
|
<li>
|
|
<p>
|
|
The <code>work</code> directory that contains temporary working
|
|
directories for the deployed web applications.
|
|
</p>
|
|
<p>
|
|
<i>Recommended:</i> Yes.
|
|
</p>
|
|
</li>
|
|
<li>
|
|
<p>
|
|
The <code>temp</code> directory used by the JVM for temporary files.
|
|
</p>
|
|
<p>
|
|
<i>Recommended:</i> Yes.
|
|
</p>
|
|
</li>
|
|
</ul>
|
|
</p>
|
|
<p>
|
|
We recommend you not to change the <code>tomcat-juli.jar</code> file.
|
|
However, in case you require your own logging implementation, you can
|
|
replace the <code>tomcat-juli.jar</code> file in a CATALINA_BASE location
|
|
for the specific Tomcat instance.
|
|
</p>
|
|
<p>
|
|
We also recommend you copy all configuration files from the
|
|
<code>CATALINA_HOME/conf</code> directory into the
|
|
<code>CATALINA_BASE/conf/</code> directory. In case a configuration file
|
|
is missing in CATALINA_BASE, there is no fallback to CATALINA_HOME.
|
|
Consequently, this may cause failure.
|
|
</p>
|
|
<p>
|
|
At minimum, CATALINA_BASE must contain:
|
|
<ul>
|
|
<li>conf/server.xml</li>
|
|
<li>conf/web.xml</li>
|
|
</ul>
|
|
That includes the <code>conf</code> directory. Otherwise, Tomcat fails
|
|
to start, or fails to function properly.
|
|
</p>
|
|
<p>
|
|
For advanced configuration information, see the
|
|
<a href="https://tomcat.apache.org/tomcat-9.0-doc/RUNNING.txt">
|
|
RUNNING.txt
|
|
</a> file.
|
|
</p>
|
|
</subsection>
|
|
<subsection name="How to Use CATALINA_BASE">
|
|
<p>
|
|
The CATALINA_BASE property is an environment variable. You can set it
|
|
before you execute the Tomcat start script, for example:
|
|
<ul>
|
|
<li>On Unix: <code>CATALINA_BASE=/tmp/tomcat_base1 bin/catalina.sh start</code></li>
|
|
<li>On Windows: <code>CATALINA_BASE=C:\tomcat_base1 bin/catalina.bat start</code></li>
|
|
</ul>
|
|
</p>
|
|
</subsection>
|
|
</section>
|
|
|
|
|
|
<section name="Configuring Tomcat">
|
|
|
|
<p>This section will acquaint you with the basic information used during
|
|
the configuration of the container.</p>
|
|
|
|
<p>All of the information in the configuration files is read at startup,
|
|
meaning that any change to the files necessitates a restart of the container.
|
|
</p>
|
|
|
|
</section>
|
|
|
|
|
|
<section name="Where to Go for Help">
|
|
|
|
<p>While we've done our best to ensure that these documents are clearly
|
|
written and easy to understand, we may have missed something. Provided
|
|
below are various web sites and mailing lists in case you get stuck.</p>
|
|
|
|
<p>Keep in mind that some of the issues and solutions vary between the
|
|
major versions of Tomcat. As you search around the web, there will be
|
|
some documentation that is not relevant to Tomcat <version-major/>, but
|
|
only to earlier versions.</p>
|
|
|
|
<ul>
|
|
<li>Current document - most documents will list potential hangups. Be sure
|
|
to fully read the relevant documentation as it will save you much time
|
|
and effort. There's nothing like scouring the web only to find out that
|
|
the answer was right in front of you all along!</li>
|
|
<li><a href="https://wiki.apache.org/tomcat/FAQ">Tomcat FAQ</a></li>
|
|
<li><a href="https://wiki.apache.org/tomcat/">Tomcat WIKI</a></li>
|
|
<li>Tomcat FAQ at <a href="http://www.jguru.com/faq/home.jsp?topic=Tomcat">jGuru</a></li>
|
|
<li>Tomcat mailing list archives - numerous sites archive the Tomcat mailing
|
|
lists. Since the links change over time, clicking here will search
|
|
<a href="https://www.google.com/search?q=tomcat+mailing+list+archives">Google</a>.
|
|
</li>
|
|
<li>The TOMCAT-USER mailing list, which you can subscribe to
|
|
<a href="https://tomcat.apache.org/lists.html">here</a>. If you don't
|
|
get a reply, then there's a good chance that your question was probably
|
|
answered in the list archives or one of the FAQs. Although questions
|
|
about web application development in general are sometimes asked and
|
|
answered, please focus your questions on Tomcat-specific issues.</li>
|
|
<li>The TOMCAT-DEV mailing list, which you can subscribe to
|
|
<a href="https://tomcat.apache.org/lists.html">here</a>. This list is
|
|
<strong>reserved</strong> for discussions about the development of Tomcat
|
|
itself. Questions about Tomcat configuration, and the problems you run
|
|
into while developing and running applications, will normally be more
|
|
appropriate on the TOMCAT-USER list instead.</li>
|
|
</ul>
|
|
|
|
<p>And, if you think something should be in the docs, by all means let us know
|
|
on the TOMCAT-DEV list.</p>
|
|
|
|
</section>
|
|
|
|
</body>
|
|
|
|
</document>
|