APACHECON 2019EUROPE Oct. 22nd – 24th
TM
AGENDA● Where to find documentation● Interesting bits found in the deep
labyrinth of documentation
APACHECON 2019EUROPE Oct. 22nd – 24th
TM
CONVENTIONS USED ON THE SLIDES
● Shorten long package names from org.apache.tomcat to o.a.t (or c for catalina)
APACHECON 2019EUROPE Oct. 22nd – 24th
TM
LOST IN THE DOCS● Possible reasons
● Not reading the docs● Too much docs● Too many features● Source-Documented
APACHECON 2019EUROPE Oct. 22nd – 24th
TM
HOW TO READ THE DOCSFour main sources for documentation● User Guide● Reference● Wiki● Source
APACHECON 2019EUROPE Oct. 22nd – 24th
TM
DOCS: TOMCAT USER GUIDECommon use cases with sample code
https://tomcat.apache.org/tomcat-9.0-doc
When in doubt Start here
APACHECON 2019EUROPE Oct. 22nd – 24th
TM
DOCS: REFERENCEList of all configurable elements
Grouped by function
https://tomcat.apache.org/tomcat-9.0-doc/config/index.html
Good when you know what to look for
APACHECON 2019EUROPE Oct. 22nd – 24th
TM
DOCS: WIKICommunity generated content
https://cwiki.apache.org/confluence/display/TOMCAT
Helpful when you are looking for broader information about general usage
APACHECON 2019EUROPE Oct. 22nd – 24th
TM
DOCS: SOURCEWho needs documentation anyway
https://github.com/apache/tomcat/
Right place when you think documentation is wrong or missing
APACHECON 2019EUROPE Oct. 22nd – 24th
TM
DOCS: OTHER SOURCESHave a look around on the internet
E.g. by searching “site:tomcat.apache.org stuck thread” or use the mailing list
http://tomcat.apache.org/lists.html
For hard problems mailing list is really helpful
APACHECON 2019EUROPE Oct. 22nd – 24th
TM
LOST IN THE DOCS● Randomly picked interesting topics● Subjective choice
APACHECON 2019EUROPE Oct. 22nd – 24th
TM
PARALLEL DEPLOYMENT● Enables deploying of new versions of your
software without interruption● Routes sessions to the correct version of
your app● Removes old versions when they are not
used anymore (undeployOldVersions)
APACHECON 2019EUROPE Oct. 22nd – 24th
TM
PARALLEL DEPLOYMENTMORE DOCS
Mentioned in Tomcat Reference and User Guide:https://tomcat.apache.org/tomcat-9.0-doc/config/context.htmlhttps://tomcat.apache.org/tomcat-9.0-doc/manager-howto.html
APACHECON 2019EUROPE Oct. 22nd – 24th
TM
PARALLEL DEPLOYMENTUSAGE
Deploy a new WAR with a name ending on ##VERSION_STRINGExample: ROOT##001.war
Look out for warnings in the logs. You may hold on to your objects too tightly.
APACHECON 2019EUROPE Oct. 22nd – 24th
TM
LOST IN SYSTEM PROPSTomcat can be fine tuned using quite a few system properties
They are listed at the reference section
http://tomcat.apache.org/tomcat-9.0-doc/config/systemprops.html
APACHECON 2019EUROPE Oct. 22nd – 24th
TM
LOST IN TOO MANY SYSTEM PROPS
● System props can be defined in conf/catalina.properties
● System props are set for the whole JVM● CATALINA_OPTS is used on startup only
APACHECON 2019EUROPE Oct. 22nd – 24th
TM
PROPERTY_SOURCEInserts values into Tomcat’s configuration files (context.xml, server.xml, web.xml)
New PropertySource that reads values from environment variables
Mentioned in Tomcat Reference:https://tomcat.apache.org/tomcat-9.0-doc/config/systemprops.html
APACHECON 2019EUROPE Oct. 22nd – 24th
TM
PROPERTY_SOURCEUSAGE
In config file reference a value<Context> <Resource name=“jdbc/database“ port=“${db.port}“</Context>
that is set by Java system propertyCATALINA_OPTS=“-Ddb.port=4223“
APACHECON 2019EUROPE Oct. 22nd – 24th
TM
PROPERTY_SOURCEADVANCED
o.a.t.util.digester. PROPERTY_SOURCE=my.PropertySource
Create my.PropertySource that implements o.a.t.util.IntrospectionUtils.PropertySource and place it in ${CATALINA_BASE}/lib
APACHECON 2019EUROPE Oct. 22nd – 24th
TM
RECYCLE_FACADESTomcat is re-using request/response objects
If you are holding onto those objects, you will get in troubleThis option gives you a new one every time
APACHECON 2019EUROPE Oct. 22nd – 24th
TM
RECYCLE_FACADESSet org.apache.catalina.connector.RECYCLE_FACADES to trueMentioned in Tomcat Reference
https://tomcat.apache.org/tomcat-9.0-doc/config/systemprops.html
APACHECON 2019EUROPE Oct. 22nd – 24th
TM
DEFAULTS FOR VIRTUAL HOSTSTomcat can set defaults for web.xml and context.xml based on virtual hosts
Useful to customize webapps for different parties on the same instance
APACHECON 2019EUROPE Oct. 22nd – 24th
TM
DEFAULTS FOR VIRTUAL HOST PREPS
Add a virtual host to server.xml inside Engine tag<Host name=“customerone“ appBase=“portal-webapps“ unpackWars=“true“ autoDeploy=“true“ />
Create the webapps and conf folder$ mkdir -p conf/Catalina/customerone
$ mkdir portal-webapps
APACHECON 2019EUROPE Oct. 22nd – 24th
TM
DEFAULTS FOR VIRTUAL HOSTSUSAGE
● Put web.xml.default and/or context.xml.default files in conf/Catalina/customerone
● Possible content is same as web.xml and context.xml● Order of element lookup in the files is
1) Files deployed with the webapp2) Files found in the virtual host config dir3) Files found in the default host
(which is called localhost in default setup)
APACHECON 2019EUROPE Oct. 22nd – 24th
TM
DEFAULTS FOR VIRTUAL HOSTS
Mentioned in Tomcat Referencehttps://tomcat.apache.org/tomcat-9.0-doc/config/context.html
Mentioned in Tomcat User Guidehttps://tomcat.apache.org/tomcat-9.0-doc/virtual-hosting-howto.html
APACHECON 2019EUROPE Oct. 22nd – 24th
TM
SOURCE CODE DOCSA new way of Tomcat’s cluster setup using Kubernetes is documented in the source only
OK, it can be found in the wiki, too
APACHECON 2019EUROPE Oct. 22nd – 24th
TM
CLUSTER SETUP FOR KUBERNETES
● Tomcat’s builtin session replication uses multicast to find cluster nodes
● Kubernetes doesn‘t like multicast● Configure Membership Provider for
Kubernetes● Configure your application on Kubernetes
APACHECON 2019EUROPE Oct. 22nd – 24th
TM
CLUSTER SETUP FOR KUBERNETES (TOMCAT SIDE)
Add a cluster definition in server.xml to your Engine or Host tag<Cluster className="org.apache.catalina.ha.tcp.SimpleTcpCluster"> <Channel className="org.apache.catalina.tribes.group.GroupChannel"> <Membership className="o.a.c.t.membership.cloud.CloudMembershipService"/> </Channel></Cluster>
APACHECON 2019EUROPE Oct. 22nd – 24th
TM
CLUSTER SETUP DOCS● https://www.slideshare.net/jfclere/from-a-
cluster-to-the-cloud● https://github.com/jfclere/tomcat-kuberne
tes● https://cwiki.apache.org/confluence/displa
y/tomcat/ClusteringCloud
APACHECON 2019EUROPE Oct. 22nd – 24th
TM
VALVES● A small selection of built-in valves
● StuckThreadDetectionValve● SemaphoreValve● RewriteValve
APACHECON 2019EUROPE Oct. 22nd – 24th
TM
VALVES EXAMPLE 1● StuckThreadDetectionValve detects
requests that take too long● Information about those requests is
available through JMX and will be logged● Optionally interrupts stuck threads
APACHECON 2019EUROPE Oct. 22nd – 24th
TM
VALVES EXAMPLE 2● SemaphoreValve guards a resource from too
much concurrency● Most useful for synchronous servlets● Guards all or nothing :(● Subclasses can control concurrency by overwriting
SemaphoreValve#controlConcurrency(request, response)
APACHECON 2019EUROPE Oct. 22nd – 24th
TM
VALVES EXAMPLE 3● RewriteValve mimics Apache httpd
rewrite module● Use it for simple rewrite rules that are read
from a file named rewrite.config
APACHECON 2019EUROPE Oct. 22nd – 24th
TM
LOST IN TOO MANY FEATURESYou may be wondering why Tomcat provides two different pool implementations for JDBC
APACHECON 2019EUROPE Oct. 22nd – 24th
TM
WHICH JDBC POOL● jdbc-pool
fixed problems found in old dbcp based poolcapable of advanced stuffdevelopment has stalled
● tomcat-dbcpdbcp2 based pool (fixed the problems with old dbcp based pool)is actively maintained
APACHECON 2019EUROPE Oct. 22nd – 24th
TM
LOST ON THE RUNAn often overlooked gem is the file RUNNING.txt in the root directory of a fresh Tomcat installation
APACHECON 2019EUROPE Oct. 22nd – 24th
TM
BIN/SETENV.SHCustomize environment settings
Don’t edit catalina.sh or startup.sh● You don’t need to● Makes updates easier
APACHECON 2019EUROPE Oct. 22nd – 24th
TM
MULTI-INSTANCE SETUP● easy updates and lightweight instances● CATALINA_HOME
points to the extracted binaries downloaded from Tomcat homepage, can be read only
● CATALINA_BASEpoints to a stripped down installation that gets laid over CATALINA_HOME
APACHECON 2019EUROPE Oct. 22nd – 24th
TM
MULTI-INSTANCE SETUPUSAGE
$ TCV=apache-tomcat-9.0.27$ mkdir -p /srv/tomcat && cd /srv/tomcat$ tar xf “/tmp/${TCV}.tar.gz”$ mkdir -p tc-instance/{bin,logs,webapps,temp}$ cp -r “${TCV}/conf” tc-instance$ export CATALINA_HOME=”$PWD/${TCV}”$ export CATALINA_BASE=”$PWD/tc-instance”$ “${CATALINA_HOME}/bin/startup.sh”
APACHECON 2019EUROPE Oct. 22nd – 24th
TM
RESOURCE FRAMEWORK● Every “file” – classes, jars, static resources –
in Tomcat is read through the resource framework. (Tomcat 8.5 and up)
● Replaces VirtualDirContext and VirtualWebappClassLoader from Tomcat 7.0 and below
APACHECON 2019EUROPE Oct. 22nd – 24th
TM
RESOURCES EXAMPLE<Context><Resources><PreResourcesbase=”${catalina.base}/special-config.jar”
className=”o.a.c.webresources.JarResourceSet”
webAppMount=”/WEB-INF/classes” />
</Resources></Context>
APACHECON 2019EUROPE Oct. 22nd – 24th
TM
RESOURCES TYPES● WebResourceSet (Interface)● DirResourceSet (files as files)● FileResourceSet (one file as a file)● JarResourceSet (files inside jar as files)
APACHECON 2019EUROPE Oct. 22nd – 24th
TM
RESOURCES ORDERING● PreResources● MainResources● ClassResources● JarResources● PostResources
TM
APACHECON 2019EUROPE Oct. 22nd – 24th
LOST IN THE DOCS
● Thanks for listening
● Questions?
TM
APACHECON 2019EUROPE Oct. 22nd – 24th
LOST IN THE DOCS
● Thanks for listening
● Find missing docs and add them