<?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, which as its name imply, 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 namign 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>
</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.0.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>
