From users-return-265179-archive-asf-public=cust-asf.ponee.io@tomcat.apache.org Tue Jul 31 09:37:30 2018 Return-Path: X-Original-To: archive-asf-public@cust-asf.ponee.io Delivered-To: archive-asf-public@cust-asf.ponee.io Received: from mail.apache.org (hermes.apache.org [140.211.11.3]) by mx-eu-01.ponee.io (Postfix) with SMTP id 0A877180662 for ; Tue, 31 Jul 2018 09:37:29 +0200 (CEST) Received: (qmail 22494 invoked by uid 500); 31 Jul 2018 07:37:28 -0000 Mailing-List: contact users-help@tomcat.apache.org; run by ezmlm Precedence: bulk List-Help: List-Unsubscribe: List-Post: List-Id: Reply-To: "Tomcat Users List" Delivered-To: mailing list users@tomcat.apache.org Received: (qmail 22483 invoked by uid 99); 31 Jul 2018 07:37:28 -0000 Received: from pnap-us-west-generic-nat.apache.org (HELO spamd1-us-west.apache.org) (209.188.14.142) by apache.org (qpsmtpd/0.29) with ESMTP; Tue, 31 Jul 2018 07:37:28 +0000 Received: from localhost (localhost [127.0.0.1]) by spamd1-us-west.apache.org (ASF Mail Server at spamd1-us-west.apache.org) with ESMTP id B6477C73F5 for ; Tue, 31 Jul 2018 07:37:27 +0000 (UTC) X-Virus-Scanned: Debian amavisd-new at spamd1-us-west.apache.org X-Spam-Flag: NO X-Spam-Score: -0.302 X-Spam-Level: X-Spam-Status: No, score=-0.302 tagged_above=-999 required=6.31 tests=[HTML_MESSAGE=2, RCVD_IN_DNSWL_MED=-2.3, SPF_HELO_PASS=-0.001, SPF_PASS=-0.001] autolearn=disabled Received: from mx1-lw-eu.apache.org ([10.40.0.8]) by localhost (spamd1-us-west.apache.org [10.40.0.7]) (amavisd-new, port 10024) with ESMTP id Hr7_IE2sRFX2 for ; Tue, 31 Jul 2018 07:37:26 +0000 (UTC) Received: from mx1.redhat.com (mx3-rdu2.redhat.com [66.187.233.73]) by mx1-lw-eu.apache.org (ASF Mail Server at mx1-lw-eu.apache.org) with ESMTPS id B3E5D5F2AA for ; Tue, 31 Jul 2018 07:37:25 +0000 (UTC) Received: from smtp.corp.redhat.com (int-mx03.intmail.prod.int.rdu2.redhat.com [10.11.54.3]) (using TLSv1.2 with cipher AECDH-AES256-SHA (256/256 bits)) (No client certificate requested) by mx1.redhat.com (Postfix) with ESMTPS id 5D5248197005; Tue, 31 Jul 2018 07:37:19 +0000 (UTC) Received: from npe.org (dhcp-10-40-4-219.brq.redhat.com [10.40.4.219]) by smtp.corp.redhat.com (Postfix) with ESMTPS id B30451134CC9; Tue, 31 Jul 2018 07:37:18 +0000 (UTC) Subject: Re: Documentation for Catalina Base To: Tomcat Users List , Christopher Schultz References: <436092c8-96c4-3b0b-8e1a-514415d7348c@christopherschultz.net> From: Marek Czernek Message-ID: <400dad7b-d6de-14a1-a9f0-cd3891381686@redhat.com> Date: Tue, 31 Jul 2018 09:37:17 +0200 User-Agent: Mozilla/5.0 (X11; Linux x86_64; rv:52.0) Gecko/20100101 Thunderbird/52.5.2 MIME-Version: 1.0 In-Reply-To: <436092c8-96c4-3b0b-8e1a-514415d7348c@christopherschultz.net> Content-Type: multipart/alternative; boundary="------------E91E9F56970C437B53D5EB9B" Content-Language: en-US X-Scanned-By: MIMEDefang 2.78 on 10.11.54.3 X-Greylist: Sender IP whitelisted, not delayed by milter-greylist-4.5.16 (mx1.redhat.com [10.11.55.8]); Tue, 31 Jul 2018 07:37:19 +0000 (UTC) X-Greylist: inspected by milter-greylist-4.5.16 (mx1.redhat.com [10.11.55.8]); Tue, 31 Jul 2018 07:37:19 +0000 (UTC) for IP:'10.11.54.3' DOMAIN:'int-mx03.intmail.prod.int.rdu2.redhat.com' HELO:'smtp.corp.redhat.com' FROM:'mczernek@redhat.com' RCPT:'' --------------E91E9F56970C437B53D5EB9B Content-Type: text/plain; charset=utf-8; format=flowed Content-Transfer-Encoding: 8bit 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. >> 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 --------------E91E9F56970C437B53D5EB9B--