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

  &project;

  <properties>
    <author email="craigmcc@apache.org">Craig R. McClanahan</author>
    <title>Deployment</title>
  </properties>

<body>


<section name="Background">

<p>Before describing how to organize your source code directories,
it is useful to examine the runtime organization of a web application.
Prior to the Servlet API Specification, version 2.2, there was little
consistency between server platforms.  However, servers that conform
to the 2.2 (or later) specification are required to accept a
<em>Web Application Archive</em> in a standard format, which is discussed
further below.</p>

<p>A web application is defined as a hierarchy of directories and files
in a standard layout.  Such a hierarchy can be accessed in its "unpacked"
form, where each directory and file exists in the filesystem separately,
or in a "packed" form known as a Web ARchive, or WAR file.  The former format
is more useful during development, while the latter is used when you
distribute your application to be installed.</p>

<p>The top-level directory of your web application hierarchy is also the
<em>document root</em> of your application.  Here, you will place the HTML
files and JSP pages that comprise your application's user interface.  When the
system administrator deploys your application into a particular server, he
or she assigns a <em>context path</em> to your application (a later section
of this manual describes deployment on Tomcat).  Thus, if the
system administrator assigns your application to the context path
<code>/catalog</code>, then a request URI referring to
<code>/catalog/index.html</code> will retrieve the <code>index.html</code>
file from your document root.</p>

</section>


<section name="Standard Directory Layout">

<p>To facilitate creation of a Web Application Archive file in the required
format, it is convenient to arrange the "executable" files of your web
application (that is, the files that Tomcat actually uses when executing
your app) in the same organization as required by the WAR format itself.
To do this, you will end up with the following contents in your
application's "document root" directory:</p>
<ul>
<li><strong>*.html, *.jsp, etc.</strong> - The HTML and JSP pages, along
    with other files that must be visible to the client browser (such as
    JavaScript, stylesheet files, and images) for your application.
    In larger applications you may choose to divide these files into
    a subdirectory hierarchy, but for smaller apps, it is generally
    much simpler to maintain only a single directory for these files.
    <br/><br/></li>
<li><strong>/WEB-INF/web.xml</strong> - The <em>Web Application Deployment
    Descriptor</em> for your application.  This is an XML file describing
    the servlets and other components that make up your application,
    along with any initialization parameters and container-managed
    security constraints that you want the server to enforce for you.
    This file is discussed in more detail in the following subsection.
    <br/><br/></li>
<li><strong>/WEB-INF/classes/</strong> - This directory contains any Java
    class files (and associated resources) required for your application,
    including both servlet and non-servlet classes, that are not combined
    into JAR files.  If your classes are organized into Java packages,
    you must reflect this in the directory hierarchy under
    <code>/WEB-INF/classes/</code>.  For example, a Java class named
    <code>com.mycompany.mypackage.MyServlet</code>
    would need to be stored in a file named
    <code>/WEB-INF/classes/com/mycompany/mypackage/MyServlet.class</code>.
    <br/><br/></li>
<li><strong>/WEB-INF/lib/</strong> - This directory contains JAR files that
    contain Java class files (and associated resources) required for your
    application, such as third party class libraries or JDBC drivers.</li>
</ul>

<p>When you install an application into Tomcat (or any other
2.2/2.3-compatible server), the classes in the <code>WEB-INF/classes/</code>
directory, as well as all classes in JAR files found in the
<code>WEB-INF/lib/</code> directory, are made visible to other classes
within your particular web application.  Thus, if
you include all of the required library classes in one of these places (be
sure to check licenses for redistribution rights for any third party libraries
you utilize), you will simplify the installation of your web application --
no adjustment to the system class path (or installation of global library
files in your server) will be necessary.</p>

<p>Much of this information was extracted from Chapter 9 of the Servlet
API Specification, version 2.3, which you should consult for more details.</p>

</section>


<section name="Shared Library Files">

<p>Like most servlet containers, Tomcat 5 also supports mechanisms to install
library JAR files (or unpacked classes) once, and make them visible to all
installed web applications (without having to be included inside the web
application itself.  The details of how Tomcat locates and shares such
classes are described in the
<a href="../class-loader-howto.html">Class Loader HOW-TO</a> documentation.
For the purposes of our discussion, there are two locations that are commonly
used within a Tomcat 5 installation for shared code:</p>
<ul>
<li><strong>$CATALINA_HOME/common/lib</strong> - JAR files placed here are
    visible both to web applications and internal Tomcat code.  This is a
    good place to put JDBC drivers that are required for both your application
    and internal Tomcat use (such as for a JDBCRealm).
    <br/><br/></li>
<li><strong>$CATALINA_HOME/shared/lib</strong> - JAR files placed here are
    visible to all web applications, but not to internal Tomcat code.  This
    is the right place for shared libraries that are specific to your
    application.<br/><br/></li>
</ul>

<p>Out of the box, a standard Tomcat 5 installation includes a variety
of pre-installed shared library files, including:</p>
<ul>
<li>The <em>Servlet 2.4</em> and <em>JSP 2.0</em> APIs that are fundamental
    to writing servlets and JavaServer Pages.<br/><br/></li>
<li>An <em>XML Parser</em> compliant with the JAXP (version 1.2) APIs, so
    your application can perform DOM-based or SAX-based processing of
    XML documents.<br/><br/></li>
</ul>

</section>


<section name="Web Application Deployment Descriptor">

    <blockquote><em>
    <p>The description below uses the variable name $CATALINA_HOME
    to refer to the directory into which you have installed Tomcat 5,
    and is the base directory against which most relative paths are
    resolved.  However, if you have configured Tomcat 5 for multiple
    instances by setting a CATALINA_BASE directory, you should use
    $CATALINA_BASE instead of $CATALINA_HOME for each of these
    references.</p>
    </em></blockquote>

<p>As mentioned above, the <code>/WEB-INF/web.xml</code> file contains the
Web Application Deployment Descriptor for your application.  As the filename
extension implies, this file is an XML document, and defines everything about
your application that a server needs to know (except the <em>context path</em>,
which is assigned by the system administrator when the application is
deployed).</p>

<p>The complete syntax and semantics for the deployment descriptor is defined
in Chapter 13 of the Servlet API Specification, version 2.3.  Over time, it
is expected that development tools will be provided that create and edit the
deployment descriptor for you.  In the meantime, to provide a starting point,
a <a href="web.xml.txt" target="_new">basic web.xml file</a>
is provided.  This file includes comments that describe the purpose of each
included element.</p>

<p><strong>NOTE</strong> - The Servlet Specification includes a Document
Type Descriptor (DTD) for the web application deployment descriptor, and
Tomcat 5 enforces the rules defined here when processing your application's
<code>/WEB-INF/web.xml</code> file.  In particular, you <strong>must</strong>
enter your descriptor elements (such as <code>&lt;filter&gt;</code>,
<code>&lt;servlet&gt;</code>, and <code>&lt;servlet-mapping&gt;</code> in
the order defined by the DTD (see Section 13.3).</p>

</section>


<section name="Tomcat Context Descriptor">

    <blockquote><em>
    <p>The description below uses the variable name $CATALINA_HOME
    to refer to the directory into which you have installed Tomcat 5,
    and is the base directory against which most relative paths are
    resolved.  However, if you have configured Tomcat 5 for multiple
    instances by setting a CATALINA_BASE directory, you should use
    $CATALINA_BASE instead of $CATALINA_HOME for each of these
    references.</p>
    </em></blockquote>

<p>A /META-INF/context.xml file can be used to define Tomcat specific
configuration options, such as loggers, data sources, session manager
configuration and more. This XML file must contain one Context element, which
will be considered as if it was the child of the Host element corresponding
to the Host to which the  The Tomcat configuration documentation contains
information on the Context element.</p>

</section>


<section name="Deployment With Tomcat 5">

<p>In order to be executed, a web application must be deployed on
a servlet container.  This is true even during development.
We will describe using Tomcat 5 to provide the execution environment.
A web application can be deployed in Tomcat by one of the following
approaches:</p>
<ul>
<li><em>Copy unpacked directory hierarchy into a subdirectory in directory
    <code>$CATALINA_HOME/webapps/</code></em>.  Tomcat will assign a
    context path to your application based on the subdirectory name you
    choose.  We will use this technique in the <code>build.xml</code>
    file that we construct, because it is the quickest and easiest approach
    during development.  Be sure to restart Tomcat after installing or
    updating your application.
    <br/><br/></li>
<li><em>Copy the web application archive file into directory
    <code>$CATALINA_HOME/webapps/</code></em>.  When Tomcat is started, it will
    automatically expand the web application archive file into its unpacked
    form, and execute the application that way.  This approach would typically
    be used to install an additional application, provided by a third party
    vendor or by your internal development staff, into an existing
    Tomcat installation.  <strong>NOTE</strong> - If you use this approach,
    and wish to update your application later, you must both replace the
    web application archive file <strong>AND</strong> delete the expanded
    directory that Tomcat created, and then restart Tomcat, in order to reflect
    your changes.
    <br/><br/></li>
<li><em>Use the Tomcat 5 "Manager" web application to deploy and undeploy
    web applications</em>.  Tomcat 5 includes a web application, deployed
    by default on context path <code>/manager</code>, that allows you to
    deploy and undeploy applications on a running Tomcat server without
    restarting it.  See the administrator documentation (TODO: hyperlink)
    for more information on using the Manager web application.<br/><br/></li>
<li><em>Use "Manager" Ant Tasks In Your Build Script</em>.  Tomcat 5
    includes a set of custom task definitions for the <code>Ant</code>
    build tool that allow you to automate the execution of commands to the
    "Manager" web application.  These tasks are used in the Tomcat deployer.
    <br/><br/></li>
<li><em>Use the Tomcat Deployer</em>.  Tomcat 5 includes a packaged tool
    bundling the Ant tasks, and can be used to automatically precompile JSPs
    which are part of the web application before deployment to the server.
    <br/><br/></li>
</ul>

<p>Deploying your app on other servlet containers will be specific to each
container, but all containers compatible with the Servlet API Specification
(version 2.2 or later) are required to accept a web application archive file.
Note that other containers are <strong>NOT</strong> required to accept an
unpacked directory structure (as Tomcat does), or to provide mechanisms for
shared library files, but these features are commonly available.</p>

</section>


</body>
</document>