webapps/docs/deployer-howto.xml - tomcat80 - Git at Google

 <?xml version="1.0" encoding="UTF-8"?>
 <!--
   Licensed to the Apache Software Foundation (ASF) under one or more
   contributor license agreements.  See the NOTICE file distributed with
   this work for additional information regarding copyright ownership.
   The ASF licenses this file to You under the Apache License, Version 2.0
   (the "License"); you may not use this file except in compliance with
   the License.  You may obtain a copy of the License at

       http://www.apache.org/licenses/LICENSE-2.0

   Unless required by applicable law or agreed to in writing, software
   distributed under the License is distributed on an "AS IS" BASIS,
   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
   See the License for the specific language governing permissions and
   limitations under the License.
 -->
 <!DOCTYPE document [
   <!ENTITY project SYSTEM "project.xml">
 ]>
 <document url="deployer-howto.html">

     &project;

     <properties>
         <author>Allistair Crossley</author>
         <title>Tomcat Web Application Deployment</title>
     </properties>

 <body>

 <section name="Table of Contents">
 <toc/>
 </section>

     <section name="Introduction">
         <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>
     </section>

     <section name="Installation">
         <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-<version-major-minor/>.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>
     </section>

     <section name="A word on Contexts">
         <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>
     </section>

     <section name="Deployment on Tomcat startup">
         <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>
     </section>

     <section name="Deploying on a running Tomcat server">
         <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>
     </section>

     <section name="Deploying using the Tomcat Manager">
         <p>
             The Tomcat Manager is covered in its <a href="manager-howto.html">own manual page</a>.
         </p>
     </section>

     <section name="Deploying using the Client Deployer Package">
         <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&#160;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>
     </section>

 </body>

 </document>
	<?xml version="1.0" encoding="UTF-8"?>
	<!--
	Licensed to the Apache Software Foundation (ASF) under one or more
	contributor license agreements. See the NOTICE file distributed with
	this work for additional information regarding copyright ownership.
	The ASF licenses this file to You under the Apache License, Version 2.0
	(the "License"); you may not use this file except in compliance with
	the License. You may obtain a copy of the License at

	http://www.apache.org/licenses/LICENSE-2.0

	Unless required by applicable law or agreed to in writing, software
	distributed under the License is distributed on an "AS IS" BASIS,
	WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
	See the License for the specific language governing permissions and
	limitations under the License.
	-->
	<!DOCTYPE document [
	<!ENTITY project SYSTEM "project.xml">
	]>
	<document url="deployer-howto.html">

	&project;

	<properties>
	<author>Allistair Crossley</author>
	<title>Tomcat Web Application Deployment</title>
	</properties>

	<body>

	<section name="Table of Contents">
	<toc/>
	</section>

	<section name="Introduction">
	<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>
	</section>

	<section name="Installation">
	<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-<version-major-minor/>.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>
	</section>

	<section name="A word on Contexts">
	<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>
	</section>

	<section name="Deployment on Tomcat startup">
	<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>
	</section>

	<section name="Deploying on a running Tomcat server">
	<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>
	</section>

	<section name="Deploying using the Tomcat Manager">
	<p>
	The Tomcat Manager is covered in its <a href="manager-howto.html">own manual page</a>.
	</p>
	</section>

	<section name="Deploying using the Client Deployer Package">
	<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>
	</section>

	</body>

	</document>