tomcat-users mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Christopher Schultz <ch...@christopherschultz.net>
Subject Re: Documentation for Catalina Base
Date Tue, 31 Jul 2018 13:24:18 GMT
-----BEGIN PGP SIGNED MESSAGE-----
Hash: SHA256

Marek,

On 7/31/18 3:37 AM, Marek Czernek wrote:
> Hi Christopher,
> 
> thanks so much for finding the time to reply. Find my reasoning
> inline.
> 
> On 07/30/2018 06:25 PM, Christopher Schultz wrote: Marek,
> 
> On 7/30/18 3:22 AM, Marek Czernek wrote:
>>>> Hi there,
>>>> 
>>>> recently, we noticed the lack of documentation for Catalina
>>>> Base, and I wanted to find out more about it. Other than a
>>>> strangely obscure txt file [1], I did not find the concept
>>>> and usage of Catalina Base documented in the Tomcat docs.
> Do you mean the CATALINA_BASE environment variable, which is
> copied into a running JVM as the "catalina.base" system property?
>> Yep, you got it.
> 
>> <snipping to make this email a bit shorter>
>>>> 2) If not, is there any reason for it not being documented?
>>>> While I don't want to duplicate text, I do not consider a txt
>>>> file somewhere a sufficient docs.
> What, it needs to be in TeX, too?
>> :)) Joking aside though, documentation should say several things
>> at the very least:
> 
>> 1. What it is 2. How to use it 3. When to use it
> 
>> All the documentation links you provided simply say that such
>> variable exists and that you can use it to create multiple
>> instances of Tomcat. So in the HTML docs, I'm missing information
>> on:
> 
>> 1) How do you set it up

Well, it's an environment variable so... set it in your shell? There
are many ways to set an environment variable. Shall we cover them all?

>> 2) What exactly must be in catalina.base such that Tomcat
>> actually starts (since if you point it to an empty directory,
>> Tomcat fails to start)

The RUNNING.txt file explains exactly what must be in CATALINA_BASE
versus CATALINA_HOME. Is the primary complaint that this information
is not also in the online documentation?

>> 3) What are the advantages of catalina.base, i.e. why does it
>> exist. Saying that 'if you want to multiple instances of Tomcat,
>> use catalina.base' is, in my mind, missing why you'd want to use 
>> catalina.base instead of simply copy-paste the whole tomcat
>> directory as many times as you want. I mean, we want to foster
>> good practices, don't we?

RUNNING.txt suggests that a split-configuration allows for the
"desirable" situation of sharing a copy of Tomcat amongst multiple
users. It ignores, however, the most beneficial aspect on a split
configuration: ease of upgrading.

Perhaps that could be included in the documentation, wherever it ends up
.

>> When we have beautiful HTML documentation that is deep and
>> well-written, I wouldn't expect that users are suddenly required
>> to read a  shell/bat script, or some txt file that they randomly
>> found while googling, to get full information on catalina.base.

Fair enough.

>> So I personally see two options here:
> 
>> 1) We can document it in the Tomcat upstream documentation
> 
>> 2) We can document it in our downstream documentation

Having just recently written my own downstream documentation for
Apache Solr (whose documentation is indeed also deep and
well-written), I'd say that we don't want you to have to do that.

>> (and you might say that the third option is don't document it at
>> all, which I will raise internally and will see what would that
>> yield - I'll take the recommendation of the community very
>> seriously)
> 
>> If the Tomcat community believes that catalina.base is, in fact,
>> well documented, I'm of course OK with that; that's why I'm
>> asking here.
> 
>> What do you think? Do I make sense? :)

Makes sense.

Where would you have expected to see the documentation for these
settings? They are effectively used only from the various
launch-related scripts (e.g. bin/catalina.sh|bat and bin/service.bat)
but they can also be used in embedded (application) environments, too.
So I don't think it makes sense to put that documentation into e.g.
the "scripts documentation".

How about expanding this section, here:
https://tomcat.apache.org/tomcat-9.0-doc/introduction.html#Directories_a
nd_Files

- -chris
-----BEGIN PGP SIGNATURE-----
Comment: GPGTools - http://gpgtools.org
Comment: Using GnuPG with Thunderbird - http://www.enigmail.net/

iQIzBAEBCAAdFiEEMmKgYcQvxMe7tcJcHPApP6U8pFgFAltgYwEACgkQHPApP6U8
pFjN9RAApvnqRPtEtB7OGHSKxcVMSNrlIYmJad5+JQWvfyViFgl3M0/UsDSHV57I
rbU+M1PMbdMss/wi3Yul6VY6JFcwDkBNLjYQHCf/r5eAR7ChGl20kXJeTvnUoq1F
6rRqeUey3qzh5CvrvljWsm2ZBj+FuyQZa8RkLSU+h5yiZZqqz9o4ZpypWOqjzoNH
Y6YyZitwnYcpzrdKhBBfgWDS/Ly0sed4Vswf4NwCLh6PQB6HR0Xcs/xsY3hQ5WHm
TvI5I7F7/lvUhxSVeVOteuMm2qb9aBg15lJmMx6y4Zls+e4HnbPxpcinCmDZ68gV
IoG7HRJ1SlUvDQ6TaK7jXGjUuIrM5HA3nn9SajgE3W5S8pO0V/ad0YtMTLWsaXjz
AGbFXcrWt1kne8Mg5XcZUHV46Hiwfm3t5R2lzPy/gao+6uEEqdqUIJDfuC5rLvy9
Dk2gPV6bR50QI7bIFgq2p4xYnAR05Md/5T+Dl1qeMnJCUk56kmVRhxZP551/TD9E
ED+oM1xLpZ6KowORBG2LbAjuMSGNuEG29lfpGR/B/j9gvdOkwA0jOvEUYUVI1H5O
O2YEE6pfU0hS79L0WFFp5I8SbKa8xa4RqdW4lEGseWSvQBoJ/+X5XQZarXqYBaLZ
Vw/hRIY6/XIc+mG5ZsZxebGRiM+OzmHnrZ3z97f5AsSGMRYBb1o=
=0V/v
-----END PGP SIGNATURE-----

---------------------------------------------------------------------
To unsubscribe, e-mail: users-unsubscribe@tomcat.apache.org
For additional commands, e-mail: users-help@tomcat.apache.org


Mime
View raw message