<title>Deployer HOW-TO</title>

        <title>Tomcat Web Application Deployment</title>

<section name="Table of Contents">

    <section name="Table of Contents">

    <ul>

<p>

        <li><a href="#Introduction">Introduction</a></li>

<a href="#Introduction">Introduction</a><br />

        <li><a href="#Installation">Installation</a></li>

<a href="#Context descriptors">Context XML descriptors</a><br />

        <li><a href="#A word on Contexts">A word on Contexts</a></li>

<a href="#Deploying on Tomcat startup">Deploying on Tomcat startup</a><br />

        <li><a href="#Deployment on Tomcat startup">Deployment on Tomcat startup</a></li>

<a href="#Deploying on a running Tomcat server">Deploying on running Tomcat server</a><br />

        <li><a href="#Deploying on a running Tomcat server">Deploying on a running Tomcat server</a></li>

<a href="#Deploying using the Client Deployer Package">Deploying using the Client Deployer Package</a><br />

        <li><a href="#Deploying using the Tomcat Manager">Deploying using the Tomcat Manager</a></li>

<blockquote>

        <li><a href="#Deploying using the Client Deployer Package">Deploying using

</blockquote>

            the Tomcat Client Deployer</a></li>

</p>

    </ul>

</section>

    </section>

<section name="Introduction">

    <section name="Introduction">

        <p>

<p>The deployer, as its name implies, allows deploying and undeploying web

            Deployment is the term used for the process of installing a web

applications to the Tomcat server, either statically (the application is 

            application (either a 3rd party WAR or your own custom web application) 

setup before the server is started), or dynamically (in conjunction with the

            into the Tomcat server. 

Tomcat Manager web application or manipulating already deployed applications).

        </p>

</p>

        <p>

            Web application deployment may be accomplished in a number of ways

</section>

            within the Tomcat server.

            <ul>

<section name="Context descriptors">

                <li>Statically; the web application is setup before Tomcat is started</li>

                <li>

<p>A Context XML descriptor is a fragment of XML data which contains a valid

                    Dynamically; in conjunction with the Tomcat Manager web application or 

Context element which would normally be found in the main server configuration

                    manipulating already deployed web applications

file (conf/server.xml), and allows easy and automated manipulation 

                </li>

of web applications by the various management tools available in Tomcat. 

            </ul>

For a given host, the Context descriptors are located in 

        </p>

<code>$CATALINA_HOME/conf/[enginename]/[hostname]/foo.xml</code>. Note that 

        <p>

while the name of the file is not tied to the webapp name, Tomcat will create

            The Tomcat Manager is a tool that allows URL-based web application

Context descriptors which match the webapp name whenever it will generate a

            deployment features. There is also a tool called the Client Deployer,

Context descriptor.

            which is a command shell based script that interacts with the Tomcat

</p>

            Manager but provides additional functionality such as compiling and

            validating web applications as well as packaging web application into

<p>Context descriptors allow defining all aspects and configuration parameters

            web application resource (WAR) files.

of a Context, such as naming resources and session manager configuration.

        </p>

It should be noted that the docBase specified in the Context element can 

    </section>

refer to either the .WAR or the directory which will be created when the

.WAR is expanded or the .WAR itself.</p>

    <section name="Installation">

        <p>

</section>

            There is no installation required for static deployment of web

            applications as this is provided out of the box by Tomcat. Nor is any

<section name="Deploying on Tomcat startup">

            installation required for deployment functions with the Tomcat Manager, 

            although some configuration is required as detailed in the 

<p>The webapps which are present in the host appBase will be deployed if the

            Tomcat Manager manual. An installation is however required if you wish

host "deployOnStartup" property is true. The deployment process is 

            to use the Tomcat Client Deployer (TCD). 

the following:

        </p>   

<ul>

        <p>

    <li>The Context XML declarations will be deployed first</li>

            The TCD is not packaged with the Tomcat core 

    <li>Expanded web applications not referenced by Context XML declarations

            distribution, and must therefore be downloaded separately from 

        will then be deployed; if they have an associated .WAR file and it is

            the Downloads area. The download is usually labelled 

        newer than the expanded web application, the expanded directory will

            <i>jakarta-tomcat-5.5.x-deployer</i>.

        be removed and the webapp will be redeployed from the .WAR</li>

        </p>

    <li>.WAR files will be deployed</li>

        <p>

</ul>

            TCD has prerequisites of Apache Ant 1.6.2+ and a Java installation.

For each deployed web application, a matching Context XML descriptor will be

            Your environment should define an ANT_HOME environment value pointing to

created unless one exists already.

            the root of your Ant installation, and a JAVA_HOME value pointing to

</p>

            your Java installation. Additionally, you should ensure Ant's ant

            command, and the Java javac compiler command run from the command shell

</section>

            that your operating system provides.

        </p>

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

        <ol>

            <li>Download the TCD distribution</li>

<p>If the host "autoDeploy" property is true, the host will attempt to deploy 

            <li>

and update web applications dynamically, as needed. The host will need to

                The TCD package need not be extracted into any existing Tomcat

have background processing enabled for automatic reloading to work, which

                installation, it can be extracted to any location.

is the default.</p>

            </li>

            <li>Read Using the <a href="tdc">Tomcat Client Deployer</a></li>

<p>This includes:

        </ol>

<ul>

    </section>

    <li>Deployment of WARs which are copied to the host appBase.</li>

    <li>Deployment of expanded web applications which are copied to the host

    <section name="A word on Contexts">

        appBase.</li>

        <p>

    <li>Redeployment of a web application which has been deployed from a WAR

            In talking about deployment of web applications, the concept of a

        when the WAR is updated: the expanded web application is removed, 

            <i>Context</i> is required to be understood. A Context is what Tomcat 

        and the WAR is expanded again. This will not happen if the host is

            calls a web application.

        configured so that WARs are not expanded, in which case the webapp

        </p>

        will be simply redeployed.</li>

        <p>

    <li>Redeployment of the web application if the /WEB-INF/web.xml file is

            In order to configure a Context within Tomcat a <i>Context Descriptor</i>

        updated.</li>

            is required. A Context Descriptor is simply an XML file that contains

    <li>Redeployment of the web application if the context XML file from which

            Tomcat related configuration for a Context, e.g naming resources or 

        the web application has been deployed is updated.</li>

            session manager configuration. In earlier versions of

    <li>Redeployment of the web application if a context XML file (with a

            Tomcat the content of a Context Descriptor configuration was often stored within

        name corresponding to the context path of the previously deployed

            Tomcat's primary configuration file <i>server.xml</i> but this is now

        application) is added in the 

            discouraged (although it currently still works).

        <code>$CATALINA_HOME/conf/[enginename]/[hostname]/</code> folder.</li>

        </p>

    <li>Undeployment of the web application if its document base is deleted

        <p>        

        (on Windows, this assumes that anti locking features are enabled, otherwise

            Context Descriptors not only help Tomcat to know how to configure 

        it is not possible to delete the resources of a running web application).</li>

            Contexts but other tools such as the Tomcat Manager and TDC often use 

</ul>

            these Context Descriptors to perform their roles properly.

Note: Web application reloading can also be configured in the loader, in which

        </p>

case loaded classes will be tracked for changes.

        <p>

</p>

            The locations for Context Descriptors are;

            <ol>

</section>

                <li>$CATALINA_HOME/conf/[enginename]/[hostname]/context.xml</li>

                <li>$CATALINA_HOME/webapps/[webappname]/META-INF/context.xml</li>

<section name="Deploying using the Client Deployer Package">

            </ol>

            If a Context Descriptor is not provided for a Context, Tomcat

<p>The client deployer is a package which can be used to validate, compile,

            automatically creates one and places it in (1) with a filename of

and deploy a web application to a production or development server. It should 

            [webappname].xml although if manually created, the filename need not

be noted that this feature uses the Tomcat manager for automatic deployment.

            match the web application name as Tomcat is concerned only with the

</p>

            Context configuration contained within the Context Descriptor file(s).

        </p>

<p>The deployer includes the Catalina manager Ant tasks, the Jasper page

    </section>

compiler for JSP compilation before deployment, as well as a task which

validates the webapp's deployment descriptor. The validator task (class

    <section name="Deployment on Tomcat startup">

<code>org.apache.catalina.ant.ValidatorTask</code>) allows only one parameter:

        <p>

the base path of an expanded web application.</p>

            If you are not interested in using the Tomcat Manager, or TCD, 

            then you'll need to deploy your web applications 

<p>The deployer uses an unpacked web application as input (see the list of the

            statically to Tomcat, followed by a Tomcat startup. The location you

properties used by the deployer below). A web application which 

            deploy web applications to for this type of deployment is called the 

is programatically deployed with the deployer may include Tomcat specific 

            <code>appBase</code> which is specified per Host. You either copy a

deployment configuration, by including a Context configuration XML file in 

            so-called <i>exploded web application</i>, i.e non-compressed, to this

<code>/META-INF/context.xml</code>.</p>

            location, or a compressed web application resource .WAR file.

        </p>

<p>The deployer package includes a ready to use Ant script, with the following

        <p>

targets:

            The web applications present in the location specified by the Host's

<ul>

            (default Host is "localhost") <code>appBase</code> attribute (default

    <li><code>compile</code> (default): Compile and validate the web 

            appBase is "$CATALINA_HOME/webapps") will be deployed on Tomcat startup 

        application. This can be used standalone, and does not need a running

            only if the Host's <code>deployOnStartup</code> attribute is "true".

        Tomcat server. The compiled application will only run on the associated

        </p>

        Tomcat 5.5.x server release, and is not guaranteed to work on another

        <p>

        Tomcat release, as the code generated by Jasper depends on its runtime

            The following deployment sequence will occur on Tomcat startup in that

        component. It should also be noted that this target will also compile

            case:

        automatically any Java source file located in the 

        </p>

        <code>/WEB-INF/classes</code> folder of the web application.</li>

        <ol>

    <li><code>deploy</code>: Deploy a web application (compiled or not) to 

            <li>Any Context Descriptors will be deployed first.</li>

        a Tomcat server</li>

            <li>

    <li><code>undeploy</code>: Undeploy a web application</li>

                Exploded web applications not referenced by any Context

    <li><code>start</code>: Start web application</li>

                Descriptor will then be deployed. If they have an associated 

    <li><code>reload</code>: Reload web application</li>

                .WAR file in the appBase and it is newer than the exploded web application, 

    <li><code>stop</code>: Stop web application</li>

                the exploded directory will be removed and the webapp will be 

</ul>

                redeployed from the .WAR

The following properties can be specified, either as system properties, or by

            </li>

using a <code>deployer.properties</code> file located in the root folder of the

            <li>.WAR files will be deployed</li>

deployer package:

        </ol>

<ul>

        <p>

    <li><code>build</code>: The build folder used will be, by default, 

            Note again that for each deployed web application, a 

        <code>${build}/webapp${path}</code>. After the end of the execution

            Context Descriptor will be created <i>unless one exists already</i>.

        of the <code>compile</code> target, the web application WAR will be

        </p>

        located at <code>${build}/webapp${path}.war</code>.</li>

    </section>

    <li><code>webapp</code>: Folder containing the expanded web application 

        which will be compiled and validated. By default, the folder is

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

        <code>myapp</code>.</li>

        <p>

    <li><code>path</code>: Deployed context path of the web application, 

            It is possible to deploy web applications to a running Tomcat server.

        by default <code>/myapp</code>.</li>

        </p>

    <li><code>url</code>: Absolute URL to the manager web application of a 

        <p>

        running Tomcat server, which will be used to deploy and undeploy the

            If the Host <code>autoDeploy</code> attribute is "true", the Host will 

        web application. By default, the deployer will attempt to access 

            attempt to deploy and update web applications dynamically, as needed,

        a Tomcat instance running on localhost, at 

            for example if a new .WAR is dropped into the <code>appBase</code>. 

        <code>http://localhost:8080/manager</code>.</li>

            For this to work, the Host needs to have background processing 

    <li><code>username</code>: Username to be used to connect to the Tomcat 

            enabled which is the default configuration.

        manager.</li>

        </p>

    <li><code>password</code>: Password to be used to connect to the Tomcat

        manager.</li>

        <p>

</ul>

            <code>autoDeploy</code> set to "true" and a running Tomcat allows for:

</p>

        </p>

        <ul>

</section>

            <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-deployment of a web application if the /WEB-INF/web.xml file 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 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_HOME/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 familar 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 programatically 

            deployed with the deployer may include a Context Desciptor 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

                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>

        <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>. 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</code>.

            </li>

            <li>

                <code>username</code>: Tomcat Manager username (user should have a role of

                manager)

            </li>

            <li><code>password</code>: Tomcat Manager password.</li>

        </ul>

    </section>