WebSVN - Integrator Subversion - Blame - Rev 771 - /projeto-trade/apache-tomcat-9.0.112/webapps/docs/deployer-howto.html

Rev	Author	Line No.	Line
771	blopes	1	<!DOCTYPE html SYSTEM "about:legacy-compat">
		2	<html lang="en"><head><META http-equiv="Content-Type" content="text/html; charset=UTF-8"><link href="./images/docs-stylesheet.css" rel="stylesheet" type="text/css"><title>Apache Tomcat 9 (9.0.112) - Tomcat Web Application Deployment</title></head><body><div id="wrapper"><header><div id="header"><div><div><div class="logo noPrint"><a href="https://tomcat.apache.org/"><img alt="Tomcat Home" src="./images/tomcat.png"></a></div><div style="height: 1px;"></div><div class="asfLogo noPrint"><a href="https://www.apache.org/" target="_blank"><img src="./images/asf-logo.svg" alt="The Apache Software Foundation" style="width: 266px; height: 83px;"></a></div><h1>Apache Tomcat 9</h1><div class="versionInfo">
		3	Version 9.0.112,
		4	<time datetime="2025-11-06">Nov 6 2025</time></div><div style="height: 1px;"></div><div style="clear: left;"></div></div></div></div></header><div id="middle"><div><div id="mainLeft" class="noprint"><div><nav><div><h2>Links</h2><ul><li><a href="index.html">Docs Home</a></li><li><a href="https://cwiki.apache.org/confluence/display/TOMCAT/FAQ">FAQ</a></li></ul></div><div><h2>User Guide</h2><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="host-manager-howto.html">6) Host Manager</a></li><li><a href="realm-howto.html">7) Realms and AAA</a></li><li><a href="security-manager-howto.html">8) Security Manager</a></li><li><a href="jndi-resources-howto.html">9) JNDI Resources</a></li><li><a href="jndi-datasource-examples-howto.html">10) JDBC DataSources</a></li><li><a href="class-loader-howto.html">11) Classloading</a></li><li><a href="jasper-howto.html">12) JSPs</a></li><li><a href="ssl-howto.html">13) SSL/TLS</a></li><li><a href="ssi-howto.html">14) SSI</a></li><li><a href="cgi-howto.html">15) CGI</a></li><li><a href="proxy-howto.html">16) Proxy Support</a></li><li><a href="mbeans-descriptors-howto.html">17) MBeans Descriptors</a></li><li><a href="default-servlet.html">18) Default Servlet</a></li><li><a href="cluster-howto.html">19) Clustering</a></li><li><a href="balancer-howto.html">20) Load Balancer</a></li><li><a href="connectors.html">21) Connectors</a></li><li><a href="monitoring.html">22) Monitoring and Management</a></li><li><a href="logging.html">23) Logging</a></li><li><a href="apr.html">24) APR/Native</a></li><li><a href="virtual-hosting-howto.html">25) Virtual Hosting</a></li><li><a href="aio.html">26) Advanced IO</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><li><a href="rewrite.html">33) Rewrite</a></li><li><a href="cdi.html">34) CDI 2 and JAX-RS</a></li><li><a href="graal.html">35) AOT/GraalVM Support</a></li></ul></div><div><h2>Reference</h2><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 4.0 Javadocs</a></li><li><a href="jspapi/index.html">JSP 2.3 Javadocs</a></li><li><a href="elapi/index.html">EL 3.0 Javadocs</a></li><li><a href="websocketapi/index.html">WebSocket 1.1 Javadocs</a></li><li><a href="jaspicapi/index.html">JASPIC 1.1 Javadocs</a></li><li><a href="annotationapi/index.html">Common Annotations 1.3 Javadocs</a></li><li><a href="https://tomcat.apache.org/connectors-doc/">JK 1.2 Documentation</a></li></ul></div><div><h2>Apache Tomcat Development</h2><ul><li><a href="building.html">Building</a></li><li><a href="changelog.html">Changelog</a></li><li><a href="https://cwiki.apache.org/confluence/display/TOMCAT/Tomcat+Versions">Status</a></li><li><a href="developers.html">Developers</a></li><li><a href="architecture/index.html">Architecture</a></li><li><a href="tribes/introduction.html">Tribes</a></li></ul></div></nav></div></div><div id="mainRight"><div id="content"><h2>Tomcat Web Application Deployment</h2><h3 id="Table_of_Contents">Table of Contents</h3><div class="text">
		5	<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>
		6	</div><h3 id="Introduction">Introduction</h3><div class="text">
		7	<p>
		8	Deployment is the term used for the process of installing a web
		9	application (either a 3rd party WAR or your own custom web application)
		10	into the Tomcat server.
		11	</p>
		12	<p>
		13	Web application deployment may be accomplished in a number of ways
		14	within the Tomcat server.
		15	</p>
		16	<ul>
		17	<li>Statically; the web application is setup before Tomcat is started</li>
		18	<li>
		19	Dynamically; by directly manipulating already deployed web
		20	applications (relying on <em>auto-deployment</em>
		21	feature) or remotely by using the Tomcat Manager web
		22	application
		23	</li>
		24	</ul>
		25	<p>
		26	The <a href="manager-howto.html">Tomcat Manager</a> is a web
		27	application that can be used interactively (via HTML GUI) or
		28	programmatically (via URL-based API) to deploy and manage web
		29	applications.
		30	</p>
		31	<p>
		32	There are a number of ways to perform deployment that rely on
		33	the Manager web application. Apache Tomcat provides tasks
		34	for Apache Ant build tool.
		35	<a href="https://tomcat.apache.org/maven-plugin.html">Apache Tomcat Maven Plugin</a>
		36	project provides integration with Apache Maven.
		37	There is also a tool called the Client Deployer, which can be
		38	used from a command line and provides additional functionality
		39	such as compiling and validating web applications as well as
		40	packaging web application into web application resource (WAR)
		41	files.
		42	</p>
		43	</div><h3 id="Installation">Installation</h3><div class="text">
		44	<p>
		45	There is no installation required for static deployment of web
		46	applications as this is provided out of the box by Tomcat. Nor is any
		47	installation required for deployment functions with the Tomcat Manager,
		48	although some configuration is required as detailed in the
		49	<a href="manager-howto.html">Tomcat Manager manual</a>.
		50	An installation is however required if you wish
		51	to use the Tomcat Client Deployer (TCD).
		52	</p>
		53	<p>
		54	The TCD is not packaged with the Tomcat core
		55	distribution, and must therefore be downloaded separately from
		56	the Downloads area. The download is usually labelled
		57	<i>apache-tomcat-9.0.x-deployer</i>.
		58	</p>
		59	<p>
		60	TCD has prerequisites of Apache Ant 1.6.2+ and a Java installation.
		61	Your environment should define an ANT_HOME environment value pointing to
		62	the root of your Ant installation, and a JAVA_HOME value pointing to
		63	your Java installation. Additionally, you should ensure Ant's ant
		64	command, and the Java javac compiler command run from the command shell
		65	that your operating system provides.
		66	</p>
		67	<ol>
		68	<li>Download the TCD distribution</li>
		69	<li>
		70	The TCD package need not be extracted into any existing Tomcat
		71	installation, it can be extracted to any location.
		72	</li>
		73	<li>Read Using the <a href="#Deploying_using_the_Client_Deployer_Package">
		74	Tomcat Client Deployer</a></li>
		75	</ol>
		76	</div><h3 id="A_word_on_Contexts">A word on Contexts</h3><div class="text">
		77	<p>
		78	In talking about deployment of web applications, the concept of a
		79	<i>Context</i> is required to be understood. A Context is what Tomcat
		80	calls a web application.
		81	</p>
		82	<p>
		83	In order to configure a Context within Tomcat a <i>Context Descriptor</i>
		84	is required. A Context Descriptor is simply an XML file that contains
		85	Tomcat related configuration for a Context, e.g naming resources or
		86	session manager configuration. In earlier versions of
		87	Tomcat the content of a Context Descriptor configuration was often stored within
		88	Tomcat's primary configuration file <i>server.xml</i> but this is now
		89	discouraged (although it currently still works).
		90	</p>
		91	<p>
		92	Context Descriptors not only help Tomcat to know how to configure
		93	Contexts but other tools such as the Tomcat Manager and TCD often use
		94	these Context Descriptors to perform their roles properly.
		95	</p>
		96	<p>
		97	The locations for Context Descriptors are:
		98	</p>
		99	<ol>
		100	<li>$CATALINA_BASE/conf/[enginename]/[hostname]/[webappname].xml</li>
		101	<li>$CATALINA_BASE/webapps/[webappname]/META-INF/context.xml</li>
		102	</ol>
		103	<p>
		104	Files in (1) are named [webappname].xml but files in (2) are named
		105	context.xml. If a Context Descriptor is not provided for a Context,
		106	Tomcat configures the Context using default values.
		107	</p>
		108	</div><h3 id="Deployment_on_Tomcat_startup">Deployment on Tomcat startup</h3><div class="text">
		109	<p>
		110	If you are not interested in using the Tomcat Manager, or TCD,
		111	then you'll need to deploy your web applications
		112	statically to Tomcat, followed by a Tomcat startup. The location you
		113	deploy web applications to for this type of deployment is called the
		114	<code>appBase</code> which is specified per Host. You either copy a
		115	so-called <i>exploded web application</i>, i.e non-compressed, to this
		116	location, or a compressed web application resource .WAR file.
		117	</p>
		118	<p>
		119	The web applications present in the location specified by the Host's
		120	(default Host is "localhost") <code>appBase</code> attribute (default
		121	appBase is "$CATALINA_BASE/webapps") will be deployed on Tomcat startup
		122	only if the Host's <code>deployOnStartup</code> attribute is "true".
		123	</p>
		124	<p>
		125	The following deployment sequence will occur on Tomcat startup in that
		126	case:
		127	</p>
		128	<ol>
		129	<li>Any Context Descriptors will be deployed first.</li>
		130	<li>
		131	Exploded web applications not referenced by any Context
		132	Descriptor will then be deployed. If they have an associated
		133	.WAR file in the appBase and it is newer than the exploded web application,
		134	the exploded directory will be removed and the webapp will be
		135	redeployed from the .WAR
		136	</li>
		137	<li>.WAR files will be deployed</li>
		138	</ol>
		139	</div><h3 id="Deploying_on_a_running_Tomcat_server">Deploying on a running Tomcat server</h3><div class="text">
		140	<p>
		141	It is possible to deploy web applications to a running Tomcat server.
		142	</p>
		143	<p>
		144	If the Host <code>autoDeploy</code> attribute is "true", the Host will
		145	attempt to deploy and update web applications dynamically, as needed,
		146	for example if a new .WAR is dropped into the <code>appBase</code>.
		147	For this to work, the Host needs to have background processing
		148	enabled which is the default configuration.
		149	</p>
		150
		151	<p>
		152	<code>autoDeploy</code> set to "true" and a running Tomcat allows for:
		153	</p>
		154	<ul>
		155	<li>Deployment of .WAR files copied into the Host <code>appBase</code>.</li>
		156	<li>
		157	Deployment of exploded web applications which are
		158	copied into the Host <code>appBase</code>.
		159	</li>
		160	<li>
		161	Re-deployment of a web application which has already been deployed from
		162	a .WAR when the new .WAR is provided. In this case the exploded
		163	web application is removed, and the .WAR is expanded again.
		164	Note that the explosion will not occur if the Host is configured
		165	so that .WARs are not exploded with a <code>unpackWARs</code>
		166	attribute set to "false", in which case the web application
		167	will be simply redeployed as a compressed archive.
		168	</li>
		169	<li>
		170	Re-loading of a web application if the /WEB-INF/web.xml file (or
		171	any other resource defined as a WatchedResource) is updated.
		172	</li>
		173	<li>
		174	Re-deployment of a web application if the Context Descriptor
		175	file from which the web application has been deployed is
		176	updated.
		177	</li>
		178	<li>
		179	Re-deployment of dependent web applications if the global or
		180	per-host Context Descriptor file used by the web application is
		181	updated.
		182	</li>
		183	<li>
		184	Re-deployment of a web application if a Context Descriptor file (with a
		185	filename corresponding to the Context path of the previously deployed
		186	web application) is added to the
		187	<code>$CATALINA_BASE/conf/[enginename]/[hostname]/</code>
		188	directory.
		189	</li>
		190	<li>
		191	Undeployment of a web application if its document base (docBase)
		192	is deleted. Note that on Windows, this assumes that anti-locking
		193	features (see Context configuration) are enabled, otherwise it is not
		194	possible to delete the resources of a running web application.
		195	</li>
		196	</ul>
		197	<p>
		198	Note that web application reloading can also be configured in the loader, in which
		199	case loaded classes will be tracked for changes.
		200	</p>
		201	</div><h3 id="Deploying_using_the_Tomcat_Manager">Deploying using the Tomcat Manager</h3><div class="text">
		202	<p>
		203	The Tomcat Manager is covered in its <a href="manager-howto.html">own manual page</a>.
		204	</p>
		205	</div><h3 id="Deploying_using_the_Client_Deployer_Package">Deploying using the Client Deployer Package</h3><div class="text">
		206	<p>
		207	Finally, deployment of web application may be achieved using the
		208	Tomcat Client Deployer. This is a package which can be used to
		209	validate, compile, compress to .WAR, and deploy web applications to
		210	production or development Tomcat servers. It should be noted that this feature
		211	uses the Tomcat Manager and as such the target Tomcat server should be
		212	running.
		213	</p>
		214
		215	<p>
		216	It is assumed the user will be familiar with Apache Ant for using the TCD.
		217	Apache Ant is a scripted build tool. The TCD comes pre-packaged with a
		218	build script to use. Only a modest understanding of Apache Ant is
		219	required (installation as listed earlier in this page, and familiarity
		220	with using the operating system command shell and configuring
		221	environment variables).
		222	</p>
		223
		224	<p>
		225	The TCD includes Ant tasks, the Jasper page compiler for JSP compilation
		226	before deployment, as well as a task which
		227	validates the web application Context Descriptor. The validator task (class
		228	<code>org.apache.catalina.ant.ValidatorTask</code>) allows only one parameter:
		229	the base path of an exploded web application.
		230	</p>
		231
		232	<p>
		233	The TCD uses an exploded web application as input (see the list of the
		234	properties used below). A web application that is programmatically
		235	deployed with the deployer may include a Context Descriptor in
		236	<code>/META-INF/context.xml</code>.
		237	</p>
		238
		239	<p>
		240	The TCD includes a ready-to-use Ant script, with the following targets:
		241	</p>
		242	<ul>
		243	<li>
		244	<code>compile</code> (default): Compile and validate the web
		245	application. This can be used standalone, and does not need a running
		246	Tomcat server. The compiled application will only run on the associated
		247	<em>Tomcat X.Y.Z</em> server release, and is not guaranteed to work
		248	on another Tomcat release, as the code generated by Jasper depends on its runtime
		249	component. It should also be noted that this target will also compile
		250	automatically any Java source file located in the
		251	<code>/WEB-INF/classes</code> folder of the web application.</li>
		252	<li>
		253	<code>deploy</code>: Deploy a web application (compiled or not) to
		254	a Tomcat server.
		255	</li>
		256	<li><code>undeploy</code>: Undeploy a web application</li>
		257	<li><code>start</code>: Start web application</li>
		258	<li><code>reload</code>: Reload web application</li>
		259	<li><code>stop</code>: Stop web application</li>
		260	</ul>
		261
		262	<p>
		263	In order for the deployment to be configured, create a file
		264	called <code>deployer.properties</code> in the TCD installation
		265	directory root. In this file, add the following name=value pairs per
		266	line:
		267	</p>
		268
		269	<p>
		270	Additionally, you will need to ensure that a user has been
		271	setup for the target Tomcat Manager (which TCD uses) otherwise the TCD
		272	will not authenticate with the Tomcat Manager and the deployment will
		273	fail. To do this, see the Tomcat Manager page.
		274	</p>
		275
		276	<ul>
		277	<li>
		278	<code>build</code>: The build folder used will be, by default,
		279	<code>${build}/webapp/${path}</code> (<code>${build}</code>, by
		280	default, points to <code>${basedir}/build</code>). After the end
		281	of the execution of the <code>compile</code> target, the web
		282	application .WAR will be located at
		283	<code>${build}/webapp/${path}.war</code>.
		284	</li>
		285	<li>
		286	<code>webapp</code>: The directory containing the exploded web application
		287	which will be compiled and validated. By default, the folder is
		288	<code>myapp</code>.
		289	</li>
		290	<li>
		291	<code>path</code>: Deployed context path of the web application,
		292	by default <code>/myapp</code>.
		293	</li>
		294	<li>
		295	<code>url</code>: Absolute URL to the Tomcat Manager web application of a
		296	running Tomcat server, which will be used to deploy and undeploy the
		297	web application. By default, the deployer will attempt to access
		298	a Tomcat instance running on localhost, at
		299	<code>http://localhost:8080/manager/text</code>.
		300	</li>
		301	<li>
		302	<code>username</code>: Tomcat Manager username (user should have a role of
		303	manager-script)
		304	</li>
		305	<li><code>password</code>: Tomcat Manager password.</li>
		306	</ul>
		307	</div></div></div></div></div><footer><div id="footer">
		308	Copyright © 1999-2025, The Apache Software Foundation
		309	<br>
		310	Apache Tomcat, Tomcat, Apache, the Apache Tomcat logo and the Apache logo
		311	are either registered trademarks or trademarks of the Apache Software
		312	Foundation.
		313	</div></footer></div></body></html>

Subversion Repositories Integrator Subversion

(root)/projeto-trade/apache-tomcat-9.0.112/webapps/docs/deployer-howto.html - Rev 771