<html><head><META http-equiv="Content-Type" content="text/html; charset=iso-8859-1"><title>Apache Tomcat 6.0 (6.0.41) - Tomcat Web Application Deployment</title><meta name="author" content="Allistair Crossley"><style type="text/css" media="print">
			.noPrint {display: none;}
			td#mainBody {width: 100%;}
		</style></head><body bgcolor="#ffffff" text="#000000" link="#525D76" alink="#525D76" vlink="#525D76"><table border="0" width="100%" cellspacing="0"><!--PAGE HEADER--><tr><td><!--PROJECT LOGO--><a href="http://tomcat.apache.org/"><img src="./images/tomcat.gif" align="right" alt="
      The Apache Tomcat Servlet/JSP Container
    " border="0"></a></td><td><h1><font face="arial,helvetica,sanserif">Apache Tomcat 6.0</font></h1><font face="arial,helvetica,sanserif">Version 6.0.41, May 19 2014</font></td><td><!--APACHE LOGO--><a href="http://www.apache.org/"><img src="./images/asf-logo.gif" align="right" alt="Apache Logo" border="0"></a></td></tr></table><table border="0" width="100%" cellspacing="4"><!--HEADER SEPARATOR--><tr><td colspan="2"><hr noshade="noshade" size="1"></td></tr><tr><!--LEFT SIDE NAVIGATION--><td width="20%" valign="top" nowrap="nowrap" class="noPrint"><p><strong>Links</strong></p><ul><li><a href="index.html">Docs Home</a></li><li><a href="http://wiki.apache.org/tomcat/FAQ">FAQ</a></li></ul><p><strong>User Guide</strong></p><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="realm-howto.html">6) Realms and AAA</a></li><li><a href="security-manager-howto.html">7) Security Manager</a></li><li><a href="jndi-resources-howto.html">8) JNDI Resources</a></li><li><a href="jndi-datasource-examples-howto.html">9) JDBC DataSources</a></li><li><a href="class-loader-howto.html">10) Classloading</a></li><li><a href="jasper-howto.html">11) JSPs</a></li><li><a href="ssl-howto.html">12) SSL</a></li><li><a href="ssi-howto.html">13) SSI</a></li><li><a href="cgi-howto.html">14) CGI</a></li><li><a href="proxy-howto.html">15) Proxy Support</a></li><li><a href="mbeans-descriptor-howto.html">16) MBean Descriptor</a></li><li><a href="default-servlet.html">17) Default Servlet</a></li><li><a href="cluster-howto.html">18) Clustering</a></li><li><a href="balancer-howto.html">19) Load Balancer</a></li><li><a href="connectors.html">20) Connectors</a></li><li><a href="monitoring.html">21) Monitoring and Management</a></li><li><a href="logging.html">22) Logging</a></li><li><a href="apr.html">23) APR/Native</a></li><li><a href="virtual-hosting-howto.html">24) Virtual Hosting</a></li><li><a href="aio.html">25) Advanced IO</a></li><li><a href="extras.html">26) Additional Components</a></li><li><a href="maven-jars.html">27) Mavenized</a></li></ul><p><strong>Reference</strong></p><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">Javadocs</a></li><li><a href="http://tomcat.apache.org/connectors-doc/">JK 1.2 Documentation</a></li></ul><p><strong>Apache Tomcat Development</strong></p><ul><li><a href="building.html">Building</a></li><li><a href="changelog.html">Changelog</a></li><li><a href="http://wiki.apache.org/tomcat/TomcatVersions">Status</a></li><li><a href="developers.html">Developers</a></li><li><a href="architecture/index.html">Architecture</a></li><li><a href="funcspecs/index.html">Functional Specs.</a></li></ul></td><!--RIGHT SIDE MAIN BODY--><td width="80%" valign="top" align="left" id="mainBody"><h1>Apache Tomcat 6.0</h1><h2>Tomcat Web Application Deployment</h2><table border="0" cellspacing="0" cellpadding="2"><tr><td bgcolor="#525D76"><font color="#ffffff" face="arial,helvetica.sanserif"><a name="Table of Contents"><!--()--></a><a name="Table_of_Contents"><strong>Table of Contents</strong></a></font></td></tr><tr><td><blockquote>
<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>
</blockquote></td></tr></table><table border="0" cellspacing="0" cellpadding="2"><tr><td bgcolor="#525D76"><font color="#ffffff" face="arial,helvetica.sanserif"><a name="Introduction"><strong>Introduction</strong></a></font></td></tr><tr><td><blockquote>
        <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/">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>
    </blockquote></td></tr></table><table border="0" cellspacing="0" cellpadding="2"><tr><td bgcolor="#525D76"><font color="#ffffff" face="arial,helvetica.sanserif"><a name="Installation"><strong>Installation</strong></a></font></td></tr><tr><td><blockquote>
        <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-6.0.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>
    </blockquote></td></tr></table><table border="0" cellspacing="0" cellpadding="2"><tr><td bgcolor="#525D76"><font color="#ffffff" face="arial,helvetica.sanserif"><a name="A word on Contexts"><!--()--></a><a name="A_word_on_Contexts"><strong>A word on Contexts</strong></a></font></td></tr><tr><td><blockquote>
        <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>
    </blockquote></td></tr></table><table border="0" cellspacing="0" cellpadding="2"><tr><td bgcolor="#525D76"><font color="#ffffff" face="arial,helvetica.sanserif"><a name="Deployment on Tomcat startup"><!--()--></a><a name="Deployment_on_Tomcat_startup"><strong>Deployment on Tomcat startup</strong></a></font></td></tr><tr><td><blockquote>
        <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>
        <p>
            Note again that for each deployed web application, a 
            Context Descriptor will be created <i>unless one exists already</i>.
        </p>
    </blockquote></td></tr></table><table border="0" cellspacing="0" cellpadding="2"><tr><td bgcolor="#525D76"><font color="#ffffff" face="arial,helvetica.sanserif"><a name="Deploying on a running Tomcat server"><!--()--></a><a name="Deploying_on_a_running_Tomcat_server"><strong>Deploying on a running Tomcat server</strong></a></font></td></tr><tr><td><blockquote>
        <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-deployment 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 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>
    </blockquote></td></tr></table><table border="0" cellspacing="0" cellpadding="2"><tr><td bgcolor="#525D76"><font color="#ffffff" face="arial,helvetica.sanserif"><a name="Deploying using the Tomcat Manager"><!--()--></a><a name="Deploying_using_the_Tomcat_Manager"><strong>Deploying using the Tomcat Manager</strong></a></font></td></tr><tr><td><blockquote>
        <p>
            The Tomcat Manager is covered in its <a href="manager-howto.html">own manual page</a>. 
        </p>
    </blockquote></td></tr></table><table border="0" cellspacing="0" cellpadding="2"><tr><td bgcolor="#525D76"><font color="#ffffff" face="arial,helvetica.sanserif"><a name="Deploying using the Client Deployer Package"><!--()--></a><a name="Deploying_using_the_Client_Deployer_Package"><strong>Deploying using the Client Deployer Package</strong></a></font></td></tr><tr><td><blockquote>
        <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
                Tomcat 6.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>
        
        <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-script)
            </li>
            <li><code>password</code>: Tomcat Manager password.</li>
        </ul>
    </blockquote></td></tr></table></td></tr><!--FOOTER SEPARATOR--><tr><td colspan="2"><hr noshade="noshade" size="1"></td></tr><!--PAGE FOOTER--><tr><td colspan="2"><div align="center"><font color="#525D76" size="-1"><em>
        Copyright &copy; 1999-2014, Apache Software Foundation
        </em></font></div></td></tr></table></body></html>