Github user markt-asf commented on a diff in the pull request:
https://github.com/apache/tomcat/pull/117#discussion_r209555582
--- 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 --
Strictly speaking, I agree with you. My concern is that a novice user will
read this and think they only need those files whereas most users will want at
least logs, temp, webapps, work, most of conf/* and probably lib too.
Just considering the work directory - if that is missing and Tomcat can't
create one lots of stuff breaks, the most obvious of which is JSP compilation.
What I think is required here is a change of emphasis. Maybe start with
what is typically required (most / all of it) and then discuss what the bare
minimum looks like.
I'd also add notes to each dir about the relationship between HOME and
BASE. ie for bin/setenv.sh Tomcat looks in BASE then HOME. For lib, Tomcat
looks in BASE then HOME (configured in conf/catalina.propertis), for all other
dirs Tomcat only looks in BASE (unless configured to use an absolute path that
points elsewhere which could include HOME).
---
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscr...@tomcat.apache.org
For additional commands, e-mail: dev-h...@tomcat.apache.org
