Author: markt
Date: Fri Aug 24 18:27:37 2018
New Revision: 1838925
URL: http://svn.apache.org/viewvc?rev=1838925&view=rev
Log:
Expand the information in the documentation web application regarding the use
of CATALINA_HOME and CATALINA_BASE.
Patch provided by Marek Czernek.
This closes #117
Modified:
tomcat/trunk/webapps/docs/changelog.xml
tomcat/trunk/webapps/docs/introduction.xml
Modified: tomcat/trunk/webapps/docs/changelog.xml
URL:
http://svn.apache.org/viewvc/tomcat/trunk/webapps/docs/changelog.xml?rev=1838925&r1=1838924&r2=1838925&view=diff
==============================================================================
--- tomcat/trunk/webapps/docs/changelog.xml (original)
+++ tomcat/trunk/webapps/docs/changelog.xml Fri Aug 24 18:27:37 2018
@@ -62,6 +62,15 @@
</fix>
</changelog>
</subsection>
+ <subsection name="Web applications">
+ <changelog>
+ <add>
+ Expand the information in the documentation web application regarding
+ the use of <code>CATALINA_HOME</code> and <code>CATALINA_BASE</code>.
+ Patch provided by Marek Czernek. (markt)
+ </add>
+ </changelog>
+ </subsection>
<subsection name="Other">
<changelog>
<fix>
Modified: tomcat/trunk/webapps/docs/introduction.xml
URL:
http://svn.apache.org/viewvc/tomcat/trunk/webapps/docs/introduction.xml?rev=1838925&r1=1838924&r2=1838925&view=diff
==============================================================================
--- tomcat/trunk/webapps/docs/introduction.xml (original)
+++ tomcat/trunk/webapps/docs/introduction.xml Fri Aug 24 18:27:37 2018
@@ -63,15 +63,6 @@ do let us know.</p>
<section name="Directories and Files">
-<p>Throughout the docs, you'll notice there are numerous references to
-<strong>$CATALINA_HOME</strong>. This represents the root of your Tomcat
-installation. When we say, "This information can be found in your
-$CATALINA_HOME/README.txt file" we mean to look at the README.txt file at the
-root of your Tomcat install. Optionally, Tomcat may be configured for multiple
-instances by defining <strong>$CATALINA_BASE</strong> for each instance. If
-multiple instances are not configured, <strong>$CATALINA_BASE</strong> is the
-same as <strong>$CATALINA_HOME</strong>.</p>
-
<p>These are some of the key tomcat directories:</p>
<ul>
@@ -89,6 +80,170 @@ same as <strong>$CATALINA_HOME</strong>.
</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">
---------------------------------------------------------------------
To unsubscribe, e-mail: [email protected]
For additional commands, e-mail: [email protected]
