Github user m-czernek commented on a diff in the pull request:
https://github.com/apache/tomcat/pull/117#discussion_r212238007
--- Diff: webapps/docs/introduction.xml ---
@@ -89,6 +80,122 @@ same as <strong>$CATALINA_HOME</strong>.</p>
</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, create the directory you want
to use
+ as CATALINA_BASE for the particular Tomcat instance. At minimum, it
must
+ contain:
+ <ul>
+ <li>conf/server.xml</li>
+ <li>conf/web.xml</li>
+ </ul>
+ That includes the <code>conf</code> directory. Otherwise, Tomcat may
+ fail to start.
+ </p>
+ <p>
+ Additionally, it may also contain the following:
+ <ul>
--- End diff --
Thank you for your thorough review and my apologies for the delay in
implementing it. I think what you said does make sense. I have implemented your
feedback, just please check whether what I wrote is indeed correct.
I provided the "order of lookup" note for directories where it made sense.
Not sure there is any lookup going on in logs, for example (Imho that's rather
scope than lookup, while for lib, lookup makes sense to me).
What do you think?
---
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscr...@tomcat.apache.org
For additional commands, e-mail: dev-h...@tomcat.apache.org
