container/webapps/docs/deployer-howto.xml - tomcat55 - Git at Google

 <?xml version="1.0"?>
 <!DOCTYPE document [
   <!ENTITY project SYSTEM "project.xml">
 ]>
 <document url="deployer-howto.html">

     &project;

     <properties>
         <author email="remm@apache.org">Remy Maucherat</author>
         <title>Deployer HOW-TO</title>
     </properties>

 <body>

 <section name="Table of Contents">

 <p>
 <a href="#Introduction">Introduction</a><br />
 <a href="#Context descriptors">Context XML descriptors</a><br />
 <a href="#Deploying on Tomcat startup">Deploying on Tomcat startup</a><br />
 <a href="#Deploying on a running Tomcat server">Deploying on running Tomcat server</a><br />
 <a href="#Deploying using the Client Deployer Package">Deploying using the Client Deployer Package</a><br />
 <blockquote>
 </blockquote>
 </p>

 </section>

 <section name="Introduction">

 <p>The deployer, as its name implies, allows deploying and undeploying web
 applications to the Tomcat server, either statically (the application is
 setup before the server is started), or dynamically (in conjunction with the
 Tomcat Manager web application or manipulating already deployed applications).
 </p>

 </section>

 <section name="Context descriptors">

 <p>A Context XML descriptor is a fragment of XML data which contains a valid
 Context element which would normally be found in the main server configuration
 file (conf/server.xml), and allows easy and automated manipulation
 of web applications by the various management tools available in Tomcat.
 For a given host, the Context descriptors are located in
 <code>$CATALINA_HOME/conf/[enginename]/[hostname]/foo.xml</code>. Note that
 while the name of the file is not tied to the webapp name, Tomcat will create
 Context descriptors which match the webapp name whenever it will generate a
 Context descriptor.
 </p>

 <p>Context descriptors allow defining all aspects and configuration parameters
 of a Context, such as naming resources and session manager configuration.
 It should be noted that the docBase specified in the Context element can
 refer to either the .WAR or the directory which will be created when the
 .WAR is expanded or the .WAR itself.</p>

 </section>

 <section name="Deploying on Tomcat startup">

 <p>The webapps which are present in the host appBase will be deployed if the
 host "deployOnStartup" property is true. The deployment process is
 the following:
 <ul>
     <li>The Context XML declarations will be deployed first</li>
     <li>Expanded web applications not referenced by Context XML declarations
         will then be deployed; if they have an associated .WAR file and it is
         newer than the expanded web application, the expanded directory will
         be removed and the webapp will be redeployed from the .WAR</li>
     <li>.WAR files will be deployed</li>
 </ul>
 For each deployed web application, a matching Context XML descriptor will be
 created unless one exists already.
 </p>

 </section>

 <section name="Deploying on a running Tomcat server">

 <p>If the host "autoDeploy" property is true, the host will attempt to deploy
 and update web applications dynamically, as needed. The host will need to
 have background processing enabled for automatic reloading to work, which
 is the default.</p>

 <p>This includes:
 <ul>
     <li>Deployment of WARs which are copied to the host appBase.</li>
     <li>Deployment of expanded web applications which are copied to the host
         appBase.</li>
     <li>Redeployment of a web application which has been deployed from a WAR
         when the WAR is updated: the expanded web application is removed,
         and the WAR is expanded again. This will not happen if the host is
         configured so that WARs are not expanded, in which case the webapp
         will be simply redeployed.</li>
     <li>Redeployment of the web application if the /WEB-INF/web.xml file is
         updated.</li>
     <li>Redeployment of the web application if the context XML file from which
         the web application has been deployed is updated.</li>
     <li>Redeployment of the web application if a context XML file (with a
         name corresponding to the context path of the previously deployed
         application) is added in the
         <code>$CATALINA_HOME/conf/[enginename]/[hostname]/</code> folder.</li>
     <li>Undeployment of the web application if its document base is deleted
         (on Windows, this assumes that anti locking features are enabled, otherwise
         it is not possible to delete the resources of a running web application).</li>
 </ul>
 Note: 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 Client Deployer Package">

 <p>The client deployer is a package which can be used to validate, compile,
 and deploy a web application to a production or development server. It should
 be noted that this feature uses the Tomcat manager for automatic deployment.
 </p>

 <p>The deployer includes the Catalina manager Ant tasks, the Jasper page
 compiler for JSP compilation before deployment, as well as a task which
 validates the webapp's deployment descriptor. The validator task (class
 <code>org.apache.catalina.ant.ValidatorTask</code>) allows only one parameter:
 the base path of an expanded web application.</p>

 <p>The deployer uses an unpacked web application as input (see the list of the
 properties used by the deployer below). A web application which
 is programatically deployed with the deployer may include Tomcat specific
 deployment configuration, by including a Context configuration XML file in
 <code>/META-INF/context.xml</code>.</p>

 <p>The deployer package includes a ready to use Ant script, with the following
 targets:
 <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
         Tomcat 5.5.x 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>
 The following properties can be specified, either as system properties, or by
 using a <code>deployer.properties</code> file located in the root folder of the
 deployer package:
 <ul>
     <li><code>build</code>: The build folder used will be, by default,
         <code>${build}/webapp${path}</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>: Folder containing the expanded 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 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</code>.</li>
     <li><code>username</code>: Username to be used to connect to the Tomcat
         manager.</li>
     <li><code>password</code>: Password to be used to connect to the Tomcat
         manager.</li>
 </ul>
 </p>

 </section>

 </body>

 </document>
	<?xml version="1.0"?>
	<!DOCTYPE document [
	<!ENTITY project SYSTEM "project.xml">
	]>
	<document url="deployer-howto.html">

	&project;

	<properties>
	<author email="remm@apache.org">Remy Maucherat</author>
	<title>Deployer HOW-TO</title>
	</properties>

	<body>

	<section name="Table of Contents">

	<p>
	<a href="#Introduction">Introduction</a><br />
	<a href="#Context descriptors">Context XML descriptors</a><br />
	<a href="#Deploying on Tomcat startup">Deploying on Tomcat startup</a><br />
	<a href="#Deploying on a running Tomcat server">Deploying on running Tomcat server</a><br />
	<a href="#Deploying using the Client Deployer Package">Deploying using the Client Deployer Package</a><br />
	<blockquote>
	</blockquote>
	</p>

	</section>

	<section name="Introduction">

	<p>The deployer, as its name implies, allows deploying and undeploying web
	applications to the Tomcat server, either statically (the application is
	setup before the server is started), or dynamically (in conjunction with the
	Tomcat Manager web application or manipulating already deployed applications).
	</p>

	</section>

	<section name="Context descriptors">

	<p>A Context XML descriptor is a fragment of XML data which contains a valid
	Context element which would normally be found in the main server configuration
	file (conf/server.xml), and allows easy and automated manipulation
	of web applications by the various management tools available in Tomcat.
	For a given host, the Context descriptors are located in
	<code>$CATALINA_HOME/conf/[enginename]/[hostname]/foo.xml</code>. Note that
	while the name of the file is not tied to the webapp name, Tomcat will create
	Context descriptors which match the webapp name whenever it will generate a
	Context descriptor.
	</p>

	<p>Context descriptors allow defining all aspects and configuration parameters
	of a Context, such as naming resources and session manager configuration.
	It should be noted that the docBase specified in the Context element can
	refer to either the .WAR or the directory which will be created when the
	.WAR is expanded or the .WAR itself.</p>

	</section>

	<section name="Deploying on Tomcat startup">

	<p>The webapps which are present in the host appBase will be deployed if the
	host "deployOnStartup" property is true. The deployment process is
	the following:
	<ul>
	<li>The Context XML declarations will be deployed first</li>
	<li>Expanded web applications not referenced by Context XML declarations
	will then be deployed; if they have an associated .WAR file and it is
	newer than the expanded web application, the expanded directory will
	be removed and the webapp will be redeployed from the .WAR</li>
	<li>.WAR files will be deployed</li>
	</ul>
	For each deployed web application, a matching Context XML descriptor will be
	created unless one exists already.
	</p>

	</section>

	<section name="Deploying on a running Tomcat server">

	<p>If the host "autoDeploy" property is true, the host will attempt to deploy
	and update web applications dynamically, as needed. The host will need to
	have background processing enabled for automatic reloading to work, which
	is the default.</p>

	<p>This includes:
	<ul>
	<li>Deployment of WARs which are copied to the host appBase.</li>
	<li>Deployment of expanded web applications which are copied to the host
	appBase.</li>
	<li>Redeployment of a web application which has been deployed from a WAR
	when the WAR is updated: the expanded web application is removed,
	and the WAR is expanded again. This will not happen if the host is
	configured so that WARs are not expanded, in which case the webapp
	will be simply redeployed.</li>
	<li>Redeployment of the web application if the /WEB-INF/web.xml file is
	updated.</li>
	<li>Redeployment of the web application if the context XML file from which
	the web application has been deployed is updated.</li>
	<li>Redeployment of the web application if a context XML file (with a
	name corresponding to the context path of the previously deployed
	application) is added in the
	<code>$CATALINA_HOME/conf/[enginename]/[hostname]/</code> folder.</li>
	<li>Undeployment of the web application if its document base is deleted
	(on Windows, this assumes that anti locking features are enabled, otherwise
	it is not possible to delete the resources of a running web application).</li>
	</ul>
	Note: 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 Client Deployer Package">

	<p>The client deployer is a package which can be used to validate, compile,
	and deploy a web application to a production or development server. It should
	be noted that this feature uses the Tomcat manager for automatic deployment.
	</p>

	<p>The deployer includes the Catalina manager Ant tasks, the Jasper page
	compiler for JSP compilation before deployment, as well as a task which
	validates the webapp's deployment descriptor. The validator task (class
	<code>org.apache.catalina.ant.ValidatorTask</code>) allows only one parameter:
	the base path of an expanded web application.</p>

	<p>The deployer uses an unpacked web application as input (see the list of the
	properties used by the deployer below). A web application which
	is programatically deployed with the deployer may include Tomcat specific
	deployment configuration, by including a Context configuration XML file in
	<code>/META-INF/context.xml</code>.</p>

	<p>The deployer package includes a ready to use Ant script, with the following
	targets:
	<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
	Tomcat 5.5.x 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>
	The following properties can be specified, either as system properties, or by
	using a <code>deployer.properties</code> file located in the root folder of the
	deployer package:
	<ul>
	<li><code>build</code>: The build folder used will be, by default,
	<code>${build}/webapp${path}</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>: Folder containing the expanded 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 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</code>.</li>
	<li><code>username</code>: Username to be used to connect to the Tomcat
	manager.</li>
	<li><code>password</code>: Password to be used to connect to the Tomcat
	manager.</li>
	</ul>
	</p>

	</section>

	</body>

	</document>