You are viewing a plain text version of this content. The canonical link for it is here.
Posted to users@tomcat.apache.org by Marek Czernek <mc...@redhat.com> on 2018/07/30 07:22:25 UTC
Documentation for Catalina Base
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.
My questions are:
1) Did I overlook it being documented somewhere?
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.
If the answer to both of my questions is no, we'll create a patch
against the Tomcat docs.
[1] https://tomcat.apache.org/tomcat-9.0-doc/RUNNING.txt
Cheers,
--
Marek Czernek
JWS/JBCS Associate Quality Engineer, RHCA
Find me at www.halfastack.com
Re: Documentation for Catalina Base
Posted by Marek Czernek <mc...@redhat.com>.
Hi there,
Well this just confirms that this doc change is helping more people and
the doc should be improved.
I have changed the path but as far as I know, the path is literally
irrelevant. If you unzip your tomcat to D:\tmp\, that will be your
catalina.home.
Glad this will help someone.
On 08/09/2018 05:59 PM, Lemke, Michael ST/HZA-ZIC2 wrote:
> On Thursday, August 09, 2018 4:23 PM, Marek Czernek wrote:
>> Hi,
>>
>> any thoughts about the PR anyone? [1] Feel free to suggest any
>> improvements, or help me better the docs with your comments of course.
>>
>> [1] https://github.com/apache/tomcat/pull/117
> Hi Marek,
>
> thanks for writing this. Wish you'd done it earlier as I had the very same problem about two months ago (search for "Tomcat Installation on Windows" in this mailing list). My suggestion would be to have CATALINA_HOME reference something like C:\Program Files\apache-tomcat-9.0.10 on Windows. That would make it very clear that this is code you are not supposed to touch. But I have the feeling that tomcat isn't too strict about such a concept and might require you to do so anyway.
>
> Michael
>
>
>> Cheers,
>>
>> On 07/30/2018 09: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.
>>>
>>> My questions are:
>>>
>>> 1) Did I overlook it being documented somewhere?
>>>
>>> 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.
>>>
>>> If the answer to both of my questions is no, we'll create a patch
>>> against the Tomcat docs.
>>>
>>>
>>> [1] https://tomcat.apache.org/tomcat-9.0-doc/RUNNING.txt
>>>
>>>
>>> Cheers,
>>>
>> --
>>
>> Marek Czernek
>>
>> JWS/JBCS Associate Quality Engineer, RHCA
>>
>> Find me at www.halfastack.com
>>
> ---------------------------------------------------------------------
> To unsubscribe, e-mail: users-unsubscribe@tomcat.apache.org
> For additional commands, e-mail: users-help@tomcat.apache.org
>
--
Marek Czernek
JWS/JBCS Associate Quality Engineer, RHCA
Find me at www.halfastack.com
RE: Documentation for Catalina Base
Posted by "Lemke, Michael ST/HZA-ZIC2" <le...@schaeffler.com>.
On Thursday, August 09, 2018 4:23 PM, Marek Czernek wrote:
>Hi,
>
>any thoughts about the PR anyone? [1] Feel free to suggest any
>improvements, or help me better the docs with your comments of course.
>
>[1] https://github.com/apache/tomcat/pull/117
Hi Marek,
thanks for writing this. Wish you'd done it earlier as I had the very same problem about two months ago (search for "Tomcat Installation on Windows" in this mailing list). My suggestion would be to have CATALINA_HOME reference something like C:\Program Files\apache-tomcat-9.0.10 on Windows. That would make it very clear that this is code you are not supposed to touch. But I have the feeling that tomcat isn't too strict about such a concept and might require you to do so anyway.
Michael
>
>Cheers,
>
>On 07/30/2018 09: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.
>>
>> My questions are:
>>
>> 1) Did I overlook it being documented somewhere?
>>
>> 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.
>>
>> If the answer to both of my questions is no, we'll create a patch
>> against the Tomcat docs.
>>
>>
>> [1] https://tomcat.apache.org/tomcat-9.0-doc/RUNNING.txt
>>
>>
>> Cheers,
>>
>
>--
>
>Marek Czernek
>
>JWS/JBCS Associate Quality Engineer, RHCA
>
>Find me at www.halfastack.com
>
Re: Documentation for Catalina Base
Posted by Marek Czernek <mc...@redhat.com>.
Hi,
any thoughts about the PR anyone? [1] Feel free to suggest any
improvements, or help me better the docs with your comments of course.
[1] https://github.com/apache/tomcat/pull/117
Cheers,
On 07/30/2018 09: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.
>
> My questions are:
>
> 1) Did I overlook it being documented somewhere?
>
> 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.
>
> If the answer to both of my questions is no, we'll create a patch
> against the Tomcat docs.
>
>
> [1] https://tomcat.apache.org/tomcat-9.0-doc/RUNNING.txt
>
>
> Cheers,
>
--
Marek Czernek
JWS/JBCS Associate Quality Engineer, RHCA
Find me at www.halfastack.com
Re: Documentation for Catalina Base
Posted by Christopher Schultz <ch...@christopherschultz.net>.
-----BEGIN PGP SIGNED MESSAGE-----
Hash: SHA256
Stefan,
On 7/31/18 4:24 AM, Stefan Mayr wrote:
> Hi,
>
> Am 30.07.2018 um 18:25 schrieb Christopher Schultz:
>> -----BEGIN PGP SIGNED MESSAGE----- Hash: SHA256
>>
>> 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?
>>
>>> My questions are:
>>>
>>> 1) Did I overlook it being documented somewhere?
>>
>> Other than in RUNNING.txt (where it is thoroughly described), it
>> is documented in:
>>
>> 1. bin/catalina.sh and bin/catalina.bat 2. The "Directories and
>> Files" section of each Tomcat X documentation (e.g.
>> https://tomcat.apache.org/tomcat-9.0-doc/introduction.html#Directorie
s_a
>>
>>
nd_Files)
>> 3. The "Introduction" section of each Tomcat X configuration
>> guide for the "context" container (e.g.
>> https://tomcat.apache.org/tomcat-9.0-doc/config/context.html#Introduc
tio
>>
>>
n)
>>
>>> 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?
>>
>>> If the answer to both of my questions is no, we'll create a
>>> patch against the Tomcat docs.
>>>
>>> [1] https://tomcat.apache.org/tomcat-9.0-doc/RUNNING.txt
>>
>> Patches are always welcome, but I believe it is currently
>> properly-documented.
>>
>> Is there something specific you were looking for and could not
>> find?
>
> That's the point to ask for some details I'm struggeling with
>
> 1. $CATALINA_BASE/bin/tomcat-juli.jar: when do I need to place this
> jar in this directory? It is only clear to have it in CATALINA_BASE
> for the documented switch to log4j. From reading catalina.sh I
> would say it is only necessary to place it in CATALINA_BASE when we
> want to use a different version. Is this assumption correct?
That file should generally be in CATALINA_HOME/bin and should match
the version of Tomcat is shipped with. If you want to use log4j for
logging, I would *always* place the replacement JULI implementation
into CATALINA_BASE/lib and leave the Tomcat "stock" installation alone.
> 2. $CATALINA_BASE/conf: What files have to be in this directory?
server.xml
web.xml (though I have argued that this should inherit from CATALINA_HOM
E)
There are other things that you might want to add, depending upon your
needs.
> If they are not present - are they loaded from CATALINA_HOME?
> RUNNING.txt only mentions server.xml. But it looks like we need to
> have at least a copy of web.xml in this directory too.
Yes, this is true:
https://bz.apache.org/bugzilla/show_bug.cgi?id=61877
> Reading catalina.sh we also should copy (or link) catalina.policy
> when running with a security manager.
Correct.
> For other files the situation is not clear, e.g.
> catalina.properties, context.xml
Both catalina.properties and context.xml will fall-back to
CATALINA_HOME if they don't exist in CATALINA_BASE.
You may also want to put a static-user file e.g. tomcat-users.xml into
your CATALINA_BASE/conf directory. All paths in server.xml are
relative to CATALINA_BASE, so if you e.g. configure a <Resource> like
this:
<Resource name="UserDatabase" auth="Container"
type="org.apache.catalina.UserDatabase"
description="User database that can be updated and saved"
factory="org.apache.catalina.users.MemoryUserDatabaseFactory"
pathname="conf/tomcat-users.xml" />
Then conf/tomcat-users.xml will be found in CATALINA_BASE. Of course,
you can always use an absolute path and put it anywhere you want... it
doesn't have to be in that location, though many people will expect it
to be there if it's being used.
> ... Some stackoverflow answers to that question recommend to copy
> the whole conf directory from CATALINA_HOME to CATALINA_BASE. I'm
> not sure if this is a good idea if I don't need to change the
> defaults. The documentation could be improved by listing the files
> that are mandatory in CATALINA_BASE
+1
- -chris
-----BEGIN PGP SIGNATURE-----
Comment: GPGTools - http://gpgtools.org
Comment: Using GnuPG with Thunderbird - http://www.enigmail.net/
iQIzBAEBCAAdFiEEMmKgYcQvxMe7tcJcHPApP6U8pFgFAltgZVoACgkQHPApP6U8
pFgxjhAAlMCi5kCjPx9ENkgNu1ifBQ5ziI/Jl+76G2tjMgH4wWxXqAG3FONchNBT
5wztEvyHTmkwS13o3z+8/3liaHSY6NSsVKyfNAR6QQA44mDOTEgpwAdPMYDl1doo
WKTOjbm59jrPIAk1Fo5P3cyodzWBHU0G2R+EMlExZ/cHJ7LezDHZ+i8b6dKAsBSl
qlahYEZvDFbGCEkPAtl5LkshKkfu/ZCoJwPZecHlv9R/DVUs7uutSVL0ubmwLf7e
gv++zf5g8UOxRI3za8VnurM+Wjt0vxzizqh7krAQkz51MZaN+Vt6mzO4wAWb9KNr
vSKu0Xu/U/8dfPIUZ5BskAU6hXQ9zZptcQiiTUUDNCVdtoI0zjqwfMHRJ89wZgAr
E3yBoi4rYZ+JSRJxjSAXrOhRYKwVXFKHsTbjJbxWn3CCppvnasU2eOxCl7b/aJwQ
qbZotXjJwkvWwLus1qmfVbv/h6Ju/4VVjdqn00pQmxCkOGjNUa+YrNPsL8v6t+sk
Ner1S+trNcr2jZgHEgODiRwpM3l6fT9PYi8jLjT1cbd+6U+w8Y1rBt4/EURpF+tA
c4x26NnATHeXOmT8EjYxyC7v2IB0/LyNiB23c5YsExpOxEQNvC5K0uIXkdkAHIqt
uTKDtx5XDU1c+JUjWgk8uTX2NFandWVWWk9J7pt1HyxvKiQhaKk=
=lf9I
-----END PGP SIGNATURE-----
---------------------------------------------------------------------
To unsubscribe, e-mail: users-unsubscribe@tomcat.apache.org
For additional commands, e-mail: users-help@tomcat.apache.org
Re: Documentation for Catalina Base
Posted by Stefan Mayr <st...@mayr-stefan.de>.
Hi,
Am 30.07.2018 um 18:25 schrieb Christopher Schultz:
> -----BEGIN PGP SIGNED MESSAGE-----
> Hash: SHA256
>
> 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?
>
>> My questions are:
>>
>> 1) Did I overlook it being documented somewhere?
>
> Other than in RUNNING.txt (where it is thoroughly described), it is
> documented in:
>
> 1. bin/catalina.sh and bin/catalina.bat
> 2. The "Directories and Files" section of each Tomcat X documentation
> (e.g.
> https://tomcat.apache.org/tomcat-9.0-doc/introduction.html#Directories_a
> nd_Files)
> 3. The "Introduction" section of each Tomcat X configuration guide for
> the "context" container (e.g.
> https://tomcat.apache.org/tomcat-9.0-doc/config/context.html#Introductio
> n)
>
>> 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?
>
>> If the answer to both of my questions is no, we'll create a patch
>> against the Tomcat docs.
>>
>> [1] https://tomcat.apache.org/tomcat-9.0-doc/RUNNING.txt
>
> Patches are always welcome, but I believe it is currently
> properly-documented.
>
> Is there something specific you were looking for and could not find?
That's the point to ask for some details I'm struggeling with
1. $CATALINA_BASE/bin/tomcat-juli.jar: when do I need to place this jar
in this directory? It is only clear to have it in CATALINA_BASE for the
documented switch to log4j. From reading catalina.sh I would say it is
only necessary to place it in CATALINA_BASE when we want to use a
different version. Is this assumption correct?
2. $CATALINA_BASE/conf: What files have to be in this directory? If they
are not present - are they loaded from CATALINA_HOME? RUNNING.txt only
mentions server.xml. But it looks like we need to have at least a copy
of web.xml in this directory too. Reading catalina.sh we also should
copy (or link) catalina.policy when running with a security manager. For
other files the situation is not clear, e.g. catalina.properties,
context.xml, ... Some stackoverflow answers to that question recommend
to copy the whole conf directory from CATALINA_HOME to CATALINA_BASE.
I'm not sure if this is a good idea if I don't need to change the
defaults. The documentation could be improved by listing the files that
are mandatory in CATALINA_BASE
Regards,
Stefan
---------------------------------------------------------------------
To unsubscribe, e-mail: users-unsubscribe@tomcat.apache.org
For additional commands, e-mail: users-help@tomcat.apache.org
Re: Documentation for Catalina Base
Posted by Marek Czernek <mc...@redhat.com>.
Hi,
On 07/31/2018 03:24 PM, Christopher Schultz wrote:
> -----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
That sounds reasonable to me. Cheers, I'll see what we can do in terms
of documenting it! :)
>
> - -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
>
--
Marek Czernek
JWS/JBCS Associate Quality Engineer, RHCA
Find me at www.halfastack.com
Re: Documentation for Catalina Base
Posted by Christopher Schultz <ch...@christopherschultz.net>.
-----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
Re: Documentation for Catalina Base
Posted by Marek Czernek <mc...@redhat.com>.
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:
> -----BEGIN PGP SIGNED MESSAGE-----
> Hash: SHA256
>
> 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
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)
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?
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.
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
(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? :)
Cheers!
>> If the answer to both of my questions is no, we'll create a patch
>> against the Tomcat docs.
>>
>> [1] https://tomcat.apache.org/tomcat-9.0-doc/RUNNING.txt
> Patches are always welcome, but I believe it is currently
> properly-documented.
>
> Is there something specific you were looking for and could not find?
>
> - -chris
> -----BEGIN PGP SIGNATURE-----
> Comment: GPGTools - http://gpgtools.org
> Comment: Using GnuPG with Thunderbird - http://www.enigmail.net/
>
> iQIzBAEBCAAdFiEEMmKgYcQvxMe7tcJcHPApP6U8pFgFAltfO+AACgkQHPApP6U8
> pFgGqg//ZXOXdoT2H59lHUHRBM+p2gUHBzFzjUUzx/4QHE4r71rGxGWBFfaqi0ZW
> /TNs93JDhlELtaxwIU5BipIdoAqy7BXd/YpcslLOjwIdUKjr2YYd+JMm/FrAWbdM
> dMQjilWLw24TbewMnCUe5KnQnKfE+fL/ehTKrS2W69cYaEqkxklURKo253MNmRsv
> p3BsZOhKgP9DeTNPEk84GseXaAYN6Wm3b0QLkgB/rG4Q4XWnB7KzDBk79fVLi9Ac
> czbhY/fyCYaNSVqau7LRdfMvqNy34+dYi1wU6vKrmFx5yBjIggNuE/hxI6LhWgMm
> 17ivwBN/Vjgp1zZN/T/BpsatmN+wTsILEcapDSaodOT2fqgbeskdYdZj9lgXffRl
> rpVHYzEQ8Uc/kSFqxddFclKxpU8lE942up53E3bjmwyE7moxAD5chGEZItfRyKJe
> WIHfeErlEEebZiHNslLxV0S9/jomK51F8UplAr2iYDNvk712sPm/CySAF9UzXMcv
> w8iJINvhnObGDB2SRfWGHR69/B80AthRMQRCZHvI4jbPensUnm2+YTAZVk+Caina
> ULh5bZ/EpNJbku23ZRZLtRJPcPoKrcy8obwQlUS3Geyqp0JV71ig/CGnUe+Iv5B9
> UMxsDmnZ1AKx/dPFzp95c2gtOsWbxmGGecvxKZMvj3hQzSquxqw=
> =brp0
> -----END PGP SIGNATURE-----
>
> ---------------------------------------------------------------------
> To unsubscribe, e-mail: users-unsubscribe@tomcat.apache.org
> For additional commands, e-mail: users-help@tomcat.apache.org
>
--
Marek Czernek
JWS/JBCS Associate Quality Engineer, RHCA
Find me at www.halfastack.com
Re: Documentation for Catalina Base
Posted by Christopher Schultz <ch...@christopherschultz.net>.
-----BEGIN PGP SIGNED MESSAGE-----
Hash: SHA256
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?
> My questions are:
>
> 1) Did I overlook it being documented somewhere?
Other than in RUNNING.txt (where it is thoroughly described), it is
documented in:
1. bin/catalina.sh and bin/catalina.bat
2. The "Directories and Files" section of each Tomcat X documentation
(e.g.
https://tomcat.apache.org/tomcat-9.0-doc/introduction.html#Directories_a
nd_Files)
3. The "Introduction" section of each Tomcat X configuration guide for
the "context" container (e.g.
https://tomcat.apache.org/tomcat-9.0-doc/config/context.html#Introductio
n)
> 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?
> If the answer to both of my questions is no, we'll create a patch
> against the Tomcat docs.
>
> [1] https://tomcat.apache.org/tomcat-9.0-doc/RUNNING.txt
Patches are always welcome, but I believe it is currently
properly-documented.
Is there something specific you were looking for and could not find?
- -chris
-----BEGIN PGP SIGNATURE-----
Comment: GPGTools - http://gpgtools.org
Comment: Using GnuPG with Thunderbird - http://www.enigmail.net/
iQIzBAEBCAAdFiEEMmKgYcQvxMe7tcJcHPApP6U8pFgFAltfO+AACgkQHPApP6U8
pFgGqg//ZXOXdoT2H59lHUHRBM+p2gUHBzFzjUUzx/4QHE4r71rGxGWBFfaqi0ZW
/TNs93JDhlELtaxwIU5BipIdoAqy7BXd/YpcslLOjwIdUKjr2YYd+JMm/FrAWbdM
dMQjilWLw24TbewMnCUe5KnQnKfE+fL/ehTKrS2W69cYaEqkxklURKo253MNmRsv
p3BsZOhKgP9DeTNPEk84GseXaAYN6Wm3b0QLkgB/rG4Q4XWnB7KzDBk79fVLi9Ac
czbhY/fyCYaNSVqau7LRdfMvqNy34+dYi1wU6vKrmFx5yBjIggNuE/hxI6LhWgMm
17ivwBN/Vjgp1zZN/T/BpsatmN+wTsILEcapDSaodOT2fqgbeskdYdZj9lgXffRl
rpVHYzEQ8Uc/kSFqxddFclKxpU8lE942up53E3bjmwyE7moxAD5chGEZItfRyKJe
WIHfeErlEEebZiHNslLxV0S9/jomK51F8UplAr2iYDNvk712sPm/CySAF9UzXMcv
w8iJINvhnObGDB2SRfWGHR69/B80AthRMQRCZHvI4jbPensUnm2+YTAZVk+Caina
ULh5bZ/EpNJbku23ZRZLtRJPcPoKrcy8obwQlUS3Geyqp0JV71ig/CGnUe+Iv5B9
UMxsDmnZ1AKx/dPFzp95c2gtOsWbxmGGecvxKZMvj3hQzSquxqw=
=brp0
-----END PGP SIGNATURE-----
---------------------------------------------------------------------
To unsubscribe, e-mail: users-unsubscribe@tomcat.apache.org
For additional commands, e-mail: users-help@tomcat.apache.org