/usr/share/tomcat7-docs/docs/deployer-howto.html is in tomcat7-docs 7.0.56-3+deb8u11.
This file is owned by root:root, with mode 0o644.
The actual contents of the file can be viewed below.
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 282 283 284 285 286 287 288 289 290 291 292 293 294 295 296 297 298 299 300 301 302 303 304 305 306 307 308 309 310 311 312 313 314 315 316 317 318 319 320 321 322 323 324 325 326 327 328 329 330 331 332 333 334 335 336 337 338 339 340 341 342 343 344 345 346 347 348 349 350 351 352 353 354 355 356 357 358 359 360 361 362 363 364 365 366 367 368 369 370 371 372 373 374 375 376 377 378 379 380 381 382 383 384 385 386 387 388 389 390 391 392 393 394 395 396 397 398 399 400 401 402 403 404 405 406 407 408 409 410 411 | <html><head><META http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"><title>Apache Tomcat 7 (7.0.56) - Tomcat Web Application Deployment</title><meta name="author" content="Allistair Crossley"><style type="text/css" media="print">
.noPrint {display: none;}
td#mainBody {width: 100%;}
</style><style type="text/css">
code {background-color:rgb(224,255,255);padding:0 0.1em;}
code.attributeName, code.propertyName {background-color:transparent;}
table {
border-collapse: collapse;
text-align: left;
}
table *:not(table) {
/* Prevent border-collapsing for table child elements like <div> */
border-collapse: separate;
}
th {
text-align: left;
}
div.codeBox pre code, code.attributeName, code.propertyName, code.noHighlight, .noHighlight code {
background-color: transparent;
}
div.codeBox {
overflow: auto;
margin: 1em 0;
}
div.codeBox pre {
margin: 0;
padding: 4px;
border: 1px solid #999;
border-radius: 5px;
background-color: #eff8ff;
display: table; /* To prevent <pre>s from taking the complete available width. */
/*
When it is officially supported, use the following CSS instead of display: table
to prevent big <pre>s from exceeding the browser window:
max-width: available;
width: min-content;
*/
}
div.codeBox pre.wrap {
white-space: pre-wrap;
}
table.defaultTable tr, table.detail-table tr {
border: 1px solid #CCC;
}
table.defaultTable tr:nth-child(even), table.detail-table tr:nth-child(even) {
background-color: #FAFBFF;
}
table.defaultTable tr:nth-child(odd), table.detail-table tr:nth-child(odd) {
background-color: #EEEFFF;
}
table.defaultTable th, table.detail-table th {
background-color: #88b;
color: #fff;
}
table.defaultTable th, table.defaultTable td, table.detail-table th, table.detail-table td {
padding: 5px 8px;
}
p.notice {
border: 1px solid rgb(255, 0, 0);
background-color: rgb(238, 238, 238);
color: rgb(0, 51, 102);
padding: 0.5em;
margin: 1em 2em 1em 1em;
}
</style></head><body bgcolor="#ffffff" text="#000000" link="#525D76" alink="#525D76" vlink="#525D76"><table border="0" width="100%" cellspacing="0"><!--PAGE HEADER--><tr><td><!--PROJECT LOGO--><a href="http://tomcat.apache.org/"><img src="./images/tomcat.gif" align="right" alt="
The Apache Tomcat Servlet/JSP Container
" border="0"></a></td><td><h1><font face="arial,helvetica,sanserif">Apache Tomcat 7</font></h1><font face="arial,helvetica,sanserif">Version 7.0.56, Jun 20 2017</font></td><td><!--APACHE LOGO--><a href="http://www.apache.org/"><img src="./images/asf-logo.gif" align="right" alt="Apache Logo" border="0"></a></td></tr></table><table border="0" width="100%" cellspacing="4"><!--HEADER SEPARATOR--><tr><td colspan="2"><hr noshade size="1"></td></tr><tr><!--LEFT SIDE NAVIGATION--><td width="20%" valign="top" nowrap class="noPrint"><p><strong>Links</strong></p><ul><li><a href="index.html">Docs Home</a></li><li><a href="http://wiki.apache.org/tomcat/FAQ">FAQ</a></li><li><a href="#comments_section">User Comments</a></li></ul><p><strong>User Guide</strong></p><ul><li><a href="introduction.html">1) Introduction</a></li><li><a href="setup.html">2) Setup</a></li><li><a href="appdev/index.html">3) First webapp</a></li><li><a href="deployer-howto.html">4) Deployer</a></li><li><a href="manager-howto.html">5) Manager</a></li><li><a href="realm-howto.html">6) Realms and AAA</a></li><li><a href="security-manager-howto.html">7) Security Manager</a></li><li><a href="jndi-resources-howto.html">8) JNDI Resources</a></li><li><a href="jndi-datasource-examples-howto.html">9) JDBC DataSources</a></li><li><a href="class-loader-howto.html">10) Classloading</a></li><li><a href="jasper-howto.html">11) JSPs</a></li><li><a href="ssl-howto.html">12) SSL</a></li><li><a href="ssi-howto.html">13) SSI</a></li><li><a href="cgi-howto.html">14) CGI</a></li><li><a href="proxy-howto.html">15) Proxy Support</a></li><li><a href="mbeans-descriptor-howto.html">16) MBean Descriptor</a></li><li><a href="default-servlet.html">17) Default Servlet</a></li><li><a href="cluster-howto.html">18) Clustering</a></li><li><a href="balancer-howto.html">19) Load Balancer</a></li><li><a href="connectors.html">20) Connectors</a></li><li><a href="monitoring.html">21) Monitoring and Management</a></li><li><a href="logging.html">22) Logging</a></li><li><a href="apr.html">23) APR/Native</a></li><li><a href="virtual-hosting-howto.html">24) Virtual Hosting</a></li><li><a href="aio.html">25) Advanced IO</a></li><li><a href="extras.html">26) Additional Components</a></li><li><a href="maven-jars.html">27) Mavenized</a></li><li><a href="security-howto.html">28) Security Considerations</a></li><li><a href="windows-service-howto.html">29) Windows Service</a></li><li><a href="windows-auth-howto.html">30) Windows Authentication</a></li><li><a href="jdbc-pool.html">31) Tomcat's JDBC Pool</a></li><li><a href="web-socket-howto.html">32) WebSocket</a></li></ul><p><strong>Reference</strong></p><ul><li><a href="RELEASE-NOTES.txt">Release Notes</a></li><li><a href="config/index.html">Configuration</a></li><li><a href="api/index.html">Tomcat Javadocs</a></li><li><a href="servletapi/index.html">Servlet Javadocs</a></li><li><a href="jspapi/index.html">JSP 2.2 Javadocs</a></li><li><a href="elapi/index.html">EL 2.2 Javadocs</a></li><li><a href="websocketapi/index.html">WebSocket 1.0 Javadocs</a></li><li><a href="http://tomcat.apache.org/connectors-doc/">JK 1.2 Documentation</a></li></ul><p><strong>Apache Tomcat Development</strong></p><ul><li><a href="building.html">Building</a></li><li><a href="changelog.html">Changelog</a></li><li><a href="http://wiki.apache.org/tomcat/TomcatVersions">Status</a></li><li><a href="developers.html">Developers</a></li><li><a href="architecture/index.html">Architecture</a></li><li><a href="funcspecs/index.html">Functional Specs.</a></li><li><a href="tribes/introduction.html">Tribes</a></li></ul></td><!--RIGHT SIDE MAIN BODY--><td width="80%" valign="top" align="left" id="mainBody"><h1>Tomcat Web Application Deployment</h1><table border="0" cellspacing="0" cellpadding="2"><tr><td bgcolor="#525D76"><font color="#ffffff" face="arial,helvetica.sanserif"><a name="Table of Contents"><!--()--></a><a name="Table_of_Contents"><strong>Table of Contents</strong></a></font></td></tr><tr><td><blockquote>
<ul><li><a href="#Introduction">Introduction</a></li><li><a href="#Installation">Installation</a></li><li><a href="#A_word_on_Contexts">A word on Contexts</a></li><li><a href="#Deployment_on_Tomcat_startup">Deployment on Tomcat startup</a></li><li><a href="#Deploying_on_a_running_Tomcat_server">Deploying on a running Tomcat server</a></li><li><a href="#Deploying_using_the_Tomcat_Manager">Deploying using the Tomcat Manager</a></li><li><a href="#Deploying_using_the_Client_Deployer_Package">Deploying using the Client Deployer Package</a></li></ul>
</blockquote></td></tr></table><table border="0" cellspacing="0" cellpadding="2"><tr><td bgcolor="#525D76"><font color="#ffffff" face="arial,helvetica.sanserif"><a name="Introduction"><strong>Introduction</strong></a></font></td></tr><tr><td><blockquote>
<p>
Deployment is the term used for the process of installing a web
application (either a 3rd party WAR or your own custom web application)
into the Tomcat server.
</p>
<p>
Web application deployment may be accomplished in a number of ways
within the Tomcat server.
</p>
<ul>
<li>Statically; the web application is setup before Tomcat is started</li>
<li>
Dynamically; by directly manipulating already deployed web
applications (relying on <em>auto-deployment</em>
feature) or remotely by using the Tomcat Manager web
application
</li>
</ul>
<p>
The <a href="manager-howto.html">Tomcat Manager</a> is a web
application that can be used interactively (via HTML GUI) or
programmatically (via URL-based API) to deploy and manage web
applications.
</p>
<p>
There are a number of ways to perform deployment that rely on
the Manager web application. Apache Tomcat provides tasks
for Apache Ant build tool.
<a href="http://tomcat.apache.org/maven-plugin.html">Apache Tomcat Maven Plugin</a>
project provides integration with Apache Maven.
There is also a tool called the Client Deployer, which can be
used from a command line and provides additional functionality
such as compiling and validating web applications as well as
packaging web application into web application resource (WAR)
files.
</p>
</blockquote></td></tr></table><table border="0" cellspacing="0" cellpadding="2"><tr><td bgcolor="#525D76"><font color="#ffffff" face="arial,helvetica.sanserif"><a name="Installation"><strong>Installation</strong></a></font></td></tr><tr><td><blockquote>
<p>
There is no installation required for static deployment of web
applications as this is provided out of the box by Tomcat. Nor is any
installation required for deployment functions with the Tomcat Manager,
although some configuration is required as detailed in the
<a href="manager-howto.html">Tomcat Manager manual</a>.
An installation is however required if you wish
to use the Tomcat Client Deployer (TCD).
</p>
<p>
The TCD is not packaged with the Tomcat core
distribution, and must therefore be downloaded separately from
the Downloads area. The download is usually labelled
<i>apache-tomcat-7.0.x-deployer</i>.
</p>
<p>
TCD has prerequisites of Apache Ant 1.6.2+ and a Java installation.
Your environment should define an ANT_HOME environment value pointing to
the root of your Ant installation, and a JAVA_HOME value pointing to
your Java installation. Additionally, you should ensure Ant's ant
command, and the Java javac compiler command run from the command shell
that your operating system provides.
</p>
<ol>
<li>Download the TCD distribution</li>
<li>
The TCD package need not be extracted into any existing Tomcat
installation, it can be extracted to any location.
</li>
<li>Read Using the <a href="#Deploying_using_the_Client_Deployer_Package">
Tomcat Client Deployer</a></li>
</ol>
</blockquote></td></tr></table><table border="0" cellspacing="0" cellpadding="2"><tr><td bgcolor="#525D76"><font color="#ffffff" face="arial,helvetica.sanserif"><a name="A word on Contexts"><!--()--></a><a name="A_word_on_Contexts"><strong>A word on Contexts</strong></a></font></td></tr><tr><td><blockquote>
<p>
In talking about deployment of web applications, the concept of a
<i>Context</i> is required to be understood. A Context is what Tomcat
calls a web application.
</p>
<p>
In order to configure a Context within Tomcat a <i>Context Descriptor</i>
is required. A Context Descriptor is simply an XML file that contains
Tomcat related configuration for a Context, e.g naming resources or
session manager configuration. In earlier versions of
Tomcat the content of a Context Descriptor configuration was often stored within
Tomcat's primary configuration file <i>server.xml</i> but this is now
discouraged (although it currently still works).
</p>
<p>
Context Descriptors not only help Tomcat to know how to configure
Contexts but other tools such as the Tomcat Manager and TCD often use
these Context Descriptors to perform their roles properly.
</p>
<p>
The locations for Context Descriptors are:
</p>
<ol>
<li>$CATALINA_BASE/conf/[enginename]/[hostname]/[webappname].xml</li>
<li>$CATALINA_BASE/webapps/[webappname]/META-INF/context.xml</li>
</ol>
<p>
Files in (1) are named [webappname].xml but files in (2) are named
context.xml. If a Context Descriptor is not provided for a Context,
Tomcat configures the Context using default values.
</p>
</blockquote></td></tr></table><table border="0" cellspacing="0" cellpadding="2"><tr><td bgcolor="#525D76"><font color="#ffffff" face="arial,helvetica.sanserif"><a name="Deployment on Tomcat startup"><!--()--></a><a name="Deployment_on_Tomcat_startup"><strong>Deployment on Tomcat startup</strong></a></font></td></tr><tr><td><blockquote>
<p>
If you are not interested in using the Tomcat Manager, or TCD,
then you'll need to deploy your web applications
statically to Tomcat, followed by a Tomcat startup. The location you
deploy web applications to for this type of deployment is called the
<code>appBase</code> which is specified per Host. You either copy a
so-called <i>exploded web application</i>, i.e non-compressed, to this
location, or a compressed web application resource .WAR file.
</p>
<p>
The web applications present in the location specified by the Host's
(default Host is "localhost") <code>appBase</code> attribute (default
appBase is "$CATALINA_BASE/webapps") will be deployed on Tomcat startup
only if the Host's <code>deployOnStartup</code> attribute is "true".
</p>
<p>
The following deployment sequence will occur on Tomcat startup in that
case:
</p>
<ol>
<li>Any Context Descriptors will be deployed first.</li>
<li>
Exploded web applications not referenced by any Context
Descriptor will then be deployed. If they have an associated
.WAR file in the appBase and it is newer than the exploded web application,
the exploded directory will be removed and the webapp will be
redeployed from the .WAR
</li>
<li>.WAR files will be deployed</li>
</ol>
</blockquote></td></tr></table><table border="0" cellspacing="0" cellpadding="2"><tr><td bgcolor="#525D76"><font color="#ffffff" face="arial,helvetica.sanserif"><a name="Deploying on a running Tomcat server"><!--()--></a><a name="Deploying_on_a_running_Tomcat_server"><strong>Deploying on a running Tomcat server</strong></a></font></td></tr><tr><td><blockquote>
<p>
It is possible to deploy web applications to a running Tomcat server.
</p>
<p>
If the Host <code>autoDeploy</code> attribute is "true", the Host will
attempt to deploy and update web applications dynamically, as needed,
for example if a new .WAR is dropped into the <code>appBase</code>.
For this to work, the Host needs to have background processing
enabled which is the default configuration.
</p>
<p>
<code>autoDeploy</code> set to "true" and a running Tomcat allows for:
</p>
<ul>
<li>Deployment of .WAR files copied into the Host <code>appBase</code>.</li>
<li>
Deployment of exploded web applications which are
copied into the Host <code>appBase</code>.
</li>
<li>
Re-deployment of a web application which has already been deployed from
a .WAR when the new .WAR is provided. In this case the exploded
web application is removed, and the .WAR is expanded again.
Note that the explosion will not occur if the Host is configured
so that .WARs are not exploded with a <code>unpackWARs</code>
attribute set to "false", in which case the web application
will be simply redeployed as a compressed archive.
</li>
<li>
Re-loading of a web application if the /WEB-INF/web.xml file (or
any other resource defined as a WatchedResource) is updated.
</li>
<li>
Re-deployment of a web application if the Context Descriptor
file from which the web application has been deployed is
updated.
</li>
<li>
Re-deployment of dependent web applications if the global or
per-host Context Descriptor file used by the web application is
updated.
</li>
<li>
Re-deployment of a web application if a Context Descriptor file (with a
filename corresponding to the Context path of the previously deployed
web application) is added to the
<code>$CATALINA_BASE/conf/[enginename]/[hostname]/</code>
directory.
</li>
<li>
Undeployment of a web application if its document base (docBase)
is deleted. Note that on Windows, this assumes that anti-locking
features (see Context configuration) are enabled, otherwise it is not
possible to delete the resources of a running web application.
</li>
</ul>
<p>
Note that web application reloading can also be configured in the loader, in which
case loaded classes will be tracked for changes.
</p>
</blockquote></td></tr></table><table border="0" cellspacing="0" cellpadding="2"><tr><td bgcolor="#525D76"><font color="#ffffff" face="arial,helvetica.sanserif"><a name="Deploying using the Tomcat Manager"><!--()--></a><a name="Deploying_using_the_Tomcat_Manager"><strong>Deploying using the Tomcat Manager</strong></a></font></td></tr><tr><td><blockquote>
<p>
The Tomcat Manager is covered in its <a href="manager-howto.html">own manual page</a>.
</p>
</blockquote></td></tr></table><table border="0" cellspacing="0" cellpadding="2"><tr><td bgcolor="#525D76"><font color="#ffffff" face="arial,helvetica.sanserif"><a name="Deploying using the Client Deployer Package"><!--()--></a><a name="Deploying_using_the_Client_Deployer_Package"><strong>Deploying using the Client Deployer Package</strong></a></font></td></tr><tr><td><blockquote>
<p>
Finally, deployment of web application may be achieved using the
Tomcat Client Deployer. This is a package which can be used to
validate, compile, compress to .WAR, and deploy web applications to
production or development Tomcat servers. It should be noted that this feature
uses the Tomcat Manager and as such the target Tomcat server should be
running.
</p>
<p>
It is assumed the user will be familiar with Apache Ant for using the TCD.
Apache Ant is a scripted build tool. The TCD comes pre-packaged with a
build script to use. Only a modest understanding of Apache Ant is
required (installation as listed earlier in this page, and familiarity
with using the operating system command shell and configuring
environment variables).
</p>
<p>
The TCD includes Ant tasks, the Jasper page compiler for JSP compilation
before deployment, as well as a task which
validates the web application Context Descriptor. The validator task (class
<code>org.apache.catalina.ant.ValidatorTask</code>) allows only one parameter:
the base path of an exploded web application.
</p>
<p>
The TCD uses an exploded web application as input (see the list of the
properties used below). A web application that is programmatically
deployed with the deployer may include a Context Descriptor in
<code>/META-INF/context.xml</code>.
</p>
<p>
The TCD includes a ready-to-use Ant script, with the following targets:
</p>
<ul>
<li>
<code>compile</code> (default): Compile and validate the web
application. This can be used standalone, and does not need a running
Tomcat server. The compiled application will only run on the associated
<em>Tomcat X.Y.Z</em> server release, and is not guaranteed to work
on another Tomcat release, as the code generated by Jasper depends on its runtime
component. It should also be noted that this target will also compile
automatically any Java source file located in the
<code>/WEB-INF/classes</code> folder of the web application.</li>
<li>
<code>deploy</code>: Deploy a web application (compiled or not) to
a Tomcat server.
</li>
<li><code>undeploy</code>: Undeploy a web application</li>
<li><code>start</code>: Start web application</li>
<li><code>reload</code>: Reload web application</li>
<li><code>stop</code>: Stop web application</li>
</ul>
<p>
In order for the deployment to be configured, create a file
called <code>deployer.properties</code> in the TCD installation
directory root. In this file, add the following name=value pairs per
line:
</p>
<p>
Additionally, you will need to ensure that a user has been
setup for the target Tomcat Manager (which TCD uses) otherwise the TCD
will not authenticate with the Tomcat Manager and the deployment will
fail. To do this, see the Tomcat Manager page.
</p>
<ul>
<li>
<code>build</code>: The build folder used will be, by default,
<code>${build}/webapp/${path}</code> (<code>${build}</code>, by
default, points to <code>${basedir}/build</code>). After the end
of the execution of the <code>compile</code> target, the web
application .WAR will be located at
<code>${build}/webapp/${path}.war</code>.
</li>
<li>
<code>webapp</code>: The directory containing the exploded web application
which will be compiled and validated. By default, the folder is
<code>myapp</code>.
</li>
<li>
<code>path</code>: Deployed context path of the web application,
by default <code>/myapp</code>.
</li>
<li>
<code>url</code>: Absolute URL to the Tomcat Manager web application of a
running Tomcat server, which will be used to deploy and undeploy the
web application. By default, the deployer will attempt to access
a Tomcat instance running on localhost, at
<code>http://localhost:8080/manager/text</code>.
</li>
<li>
<code>username</code>: Tomcat Manager username (user should have a role of
manager-script)
</li>
<li><code>password</code>: Tomcat Manager password.</li>
</ul>
</blockquote></td></tr></table></td></tr><tr class="noPrint"><td width="20%" valign="top" nowrap class="noPrint"></td><td width="80%" valign="top" align="left"><table border="0" cellspacing="0" cellpadding="2"><tr><td bgcolor="#525D76"><font color="#ffffff" face="arial,helvetica.sanserif"><a name="comments_section" id="comments_section"><strong>Comments</strong></a></font></td></tr><tr><td><blockquote><p class="notice"><strong>Notice: </strong>This comments section collects your suggestions
on improving documentation for Apache Tomcat.<br><br>
If you have trouble and need help, read
<a href="http://tomcat.apache.org/findhelp.html">Find Help</a> page
and ask your question on the tomcat-users
<a href="http://tomcat.apache.org/lists.html">mailing list</a>.
Do not ask such questions here. This is not a Q&A section.<br><br>
The Apache Comments System is explained <a href="./comments.html">here</a>.
Comments may be removed by our moderators if they are either
implemented or considered invalid/off-topic.</p><script type="text/javascript"><!--//--><![CDATA[//><!--
var comments_shortname = 'tomcat';
var comments_identifier = 'http://tomcat.apache.org/tomcat-7.0-doc/deployer-howto.html';
(function(w, d) {
if (w.location.hostname.toLowerCase() == "tomcat.apache.org") {
d.write('<div id="comments_thread"><\/div>');
var s = d.createElement('script');
s.type = 'text/javascript';
s.async = true;
s.src = 'https://comments.apache.org/show_comments.lua?site=' + comments_shortname + '&page=' + comments_identifier;
(d.getElementsByTagName('head')[0] || d.getElementsByTagName('body')[0]).appendChild(s);
}
else {
d.write('<div id="comments_thread"><strong>Comments are disabled for this page at the moment.<\/strong><\/div>');
}
})(window, document);
//--><!]]></script></blockquote></td></tr></table></td></tr><!--FOOTER SEPARATOR--><tr><td colspan="2"><hr noshade size="1"></td></tr><!--PAGE FOOTER--><tr><td colspan="2"><div align="center"><font color="#525D76" size="-1"><em>
Copyright © 1999-2017, Apache Software Foundation
</em></font></div></td></tr></table></body></html>
|