webapps/docs/introduction.xml - tomcat - Git at Google

 <?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>
	<?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>