Subversion Repositories Integrator Subversion

Rev

Details | Last modification | View Log | RSS feed

Rev Author Line No. Line
771 blopes 1 
<!DOCTYPE html SYSTEM "about:legacy-compat">
2 
<html lang="en"><head><META http-equiv="Content-Type" content="text/html; charset=UTF-8"><link href="../images/docs-stylesheet.css" rel="stylesheet" type="text/css"><title>Application Developer's Guide (9.0.112) - Deployment</title></head><body><div id="wrapper"><header><div id="header"><div><div><div class="logo noPrint"><a href="https://tomcat.apache.org/"><img alt="Tomcat Home" src="../images/tomcat.png"></a></div><div style="height: 1px;"></div><div class="asfLogo noPrint"><a href="https://www.apache.org/" target="_blank"><img src="../images/asf-logo.svg" alt="The Apache Software Foundation" style="width: 266px; height: 83px;"></a></div><h1>Application Developer's Guide</h1><div class="versionInfo">
3 
            Version 9.0.112,
4 
            <time datetime="2025-11-06">Nov 6 2025</time></div><div style="height: 1px;"></div><div style="clear: left;"></div></div></div></div></header><div id="middle"><div><div id="mainLeft" class="noprint"><div><nav><div><h2>Links</h2><ul><li><a href="../index.html">Docs Home</a></li><li><a href="index.html">App Dev Guide Home</a></li><li><a href="https://cwiki.apache.org/confluence/display/TOMCAT/FAQ">FAQ</a></li><li><a href="#comments_section">User Comments</a></li></ul></div><div><h2>Contents</h2><ul><li><a href="index.html">Contents</a></li><li><a href="introduction.html">Introduction</a></li><li><a href="installation.html">Installation</a></li><li><a href="deployment.html">Deployment</a></li><li><a href="source.html">Source Code</a></li><li><a href="processes.html">Processes</a></li><li><a href="sample/">Example App</a></li></ul></div></nav></div></div><div id="mainRight"><div id="content"><h2>Deployment</h2><h3 id="Table_of_Contents">Table of Contents</h3><div class="text">
5 
<ul><li><a href="#Background">Background</a></li><li><a href="#Standard_Directory_Layout">Standard Directory Layout</a></li><li><a href="#Shared_Library_Files">Shared Library Files</a></li><li><a href="#Web_Application_Deployment_Descriptor">Web Application Deployment Descriptor</a></li><li><a href="#Tomcat_Context_Descriptor">Tomcat Context Descriptor</a></li><li><a href="#Deployment_With_Tomcat">Deployment With Tomcat</a></li></ul>
6 
</div><h3 id="Background">Background</h3><div class="text">
7 
 
8 
<p>Before describing how to organize your source code directories,
9 
it is useful to examine the runtime organization of a web application.
10 
Prior to the Servlet API Specification, version 2.2, there was little
11 
consistency between server platforms.  However, servers that conform
12 
to the 2.2 (or later) specification are required to accept a
13 
<em>Web Application Archive</em> in a standard format, which is discussed
14 
further below.</p>
15 
 
16 
<p>A web application is defined as a hierarchy of directories and files
17 
in a standard layout.  Such a hierarchy can be accessed in its "unpacked"
18 
form, where each directory and file exists in the filesystem separately,
19 
or in a "packed" form known as a Web ARchive, or WAR file.  The former format
20 
is more useful during development, while the latter is used when you
21 
distribute your application to be installed.</p>
22 
 
23 
<p>The top-level directory of your web application hierarchy is also the
24 
<em>document root</em> of your application.  Here, you will place the HTML
25 
files and JSP pages that comprise your application's user interface.  When the
26 
system administrator deploys your application into a particular server, they
27 
assign a <em>context path</em> to your application (a later section
28 
of this manual describes deployment on Tomcat).  Thus, if the
29 
system administrator assigns your application to the context path
30 
<code>/catalog</code>, then a request URI referring to
31 
<code>/catalog/index.html</code> will retrieve the <code>index.html</code>
32 
file from your document root.</p>
33 
 
34 
</div><h3 id="Standard_Directory_Layout">Standard Directory Layout</h3><div class="text">
35 
 
36 
<p>To facilitate creation of a Web Application Archive file in the required
37 
format, it is convenient to arrange the "executable" files of your web
38 
application (that is, the files that Tomcat actually uses when executing
39 
your app) in the same organization as required by the WAR format itself.
40 
To do this, you will end up with the following contents in your
41 
application's "document root" directory:</p>
42 
<ul>
43 
<li><strong>*.html, *.jsp, etc.</strong> - The HTML and JSP pages, along
44 
    with other files that must be visible to the client browser (such as
45 
    JavaScript, stylesheet files, and images) for your application.
46 
    In larger applications you may choose to divide these files into
47 
    a subdirectory hierarchy, but for smaller apps, it is generally
48 
    much simpler to maintain only a single directory for these files.
49 
    <br><br></li>
50 
<li><strong>/WEB-INF/web.xml</strong> - The <em>Web Application Deployment
51 
    Descriptor</em> for your application.  This is an XML file describing
52 
    the servlets and other components that make up your application,
53 
    along with any initialization parameters and container-managed
54 
    security constraints that you want the server to enforce for you.
55 
    This file is discussed in more detail in the following subsection.
56 
    <br><br></li>
57 
<li><strong>/WEB-INF/classes/</strong> - This directory contains any Java
58 
    class files (and associated resources) required for your application,
59 
    including both servlet and non-servlet classes, that are not combined
60 
    into JAR files.  If your classes are organized into Java packages,
61 
    you must reflect this in the directory hierarchy under
62 
    <code>/WEB-INF/classes/</code>.  For example, a Java class named
63 
    <code>com.mycompany.mypackage.MyServlet</code>
64 
    would need to be stored in a file named
65 
    <code>/WEB-INF/classes/com/mycompany/mypackage/MyServlet.class</code>.
66 
    <br><br></li>
67 
<li><strong>/WEB-INF/lib/</strong> - This directory contains JAR files that
68 
    contain Java class files (and associated resources) required for your
69 
    application, such as third party class libraries or JDBC drivers.</li>
70 
</ul>
71 
 
72 
<p>When you install an application into Tomcat (or any other 2.2 or later
73 
Servlet container), the classes in the <code>WEB-INF/classes/</code>
74 
directory, as well as all classes in JAR files found in the
75 
<code>WEB-INF/lib/</code> directory, are made visible to other classes
76 
within your particular web application.  Thus, if
77 
you include all of the required library classes in one of these places (be
78 
sure to check licenses for redistribution rights for any third party libraries
79 
you utilize), you will simplify the installation of your web application --
80 
no adjustment to the system class path (or installation of global library
81 
files in your server) will be necessary.</p>
82 
 
83 
<p>Much of this information was extracted from Chapter 9 of the Servlet
84 
API Specification, version 2.3, which you should consult for more details.</p>
85 
 
86 
</div><h3 id="Shared_Library_Files">Shared Library Files</h3><div class="text">
87 
 
88 
<p>Like most servlet containers, Tomcat also supports mechanisms to install
89 
library JAR files (or unpacked classes) once, and make them visible to all
90 
installed web applications (without having to be included inside the web
91 
application itself).  The details of how Tomcat locates and shares such
92 
classes are described in the
93 
<a href="../class-loader-howto.html">Class Loader How-To</a> documentation.
94 
The location commonly used within a Tomcat installation for shared code is
95 
<strong>$CATALINA_HOME/lib</strong>. JAR files placed here are visible both to
96 
web applications and internal Tomcat code. This is a good place to put JDBC
97 
drivers that are required for both your application or internal Tomcat use
98 
(such as for a DataSourceRealm).</p>
99 
 
100 
<p>Out of the box, a standard Tomcat installation includes a variety
101 
of pre-installed shared library files, including:</p>
102 
<ul>
103 
<li>The <em>Servlet 4.0</em> and <em>JSP 2.3</em> APIs that are fundamental
104 
    to writing servlets and JavaServer Pages.<br><br></li>
105 
</ul>
106 
 
107 
</div><h3 id="Web_Application_Deployment_Descriptor">Web Application Deployment Descriptor</h3><div class="text">
108 
 
109 
<p>As mentioned above, the <code>/WEB-INF/web.xml</code> file contains the
110 
Web Application Deployment Descriptor for your application.  As the filename
111 
extension implies, this file is an XML document, and defines everything about
112 
your application that a server needs to know (except the <em>context path</em>,
113 
which is assigned by the system administrator when the application is
114 
deployed).</p>
115 
 
116 
<p>The complete syntax and semantics for the deployment descriptor is defined
117 
in Chapter 13 of the Servlet API Specification, version 2.3.  Over time, it
118 
is expected that development tools will be provided that create and edit the
119 
deployment descriptor for you.  In the meantime, to provide a starting point,
120 
a <a href="web.xml.txt" target="_blank">basic web.xml file</a>
121 
is provided.  This file includes comments that describe the purpose of each
122 
included element.</p>
123 
 
124 
<p><strong>NOTE</strong> - The Servlet Specification includes a Document
125 
Type Descriptor (DTD) for the web application deployment descriptor, and
126 
Tomcat enforces the rules defined here when processing your application's
127 
<code>/WEB-INF/web.xml</code> file.  In particular, you <strong>must</strong>
128 
enter your descriptor elements (such as <code>&lt;filter&gt;</code>,
129 
<code>&lt;servlet&gt;</code>, and <code>&lt;servlet-mapping&gt;</code> in
130 
the order defined by the DTD (see Section 13.3).</p>
131 
 
132 
</div><h3 id="Tomcat_Context_Descriptor">Tomcat Context Descriptor</h3><div class="text">
133 
 
134 
<p>A /META-INF/context.xml file can be used to define Tomcat specific
135 
configuration options, such as an access log, data sources, session manager
136 
configuration and more. This XML file must contain one Context element, which
137 
will be considered as if it was the child of the Host element corresponding
138 
to the Host to which the web application is being deployed. The
139 
<a href="../config/context.html">Tomcat configuration documentation</a> contains
140 
information on the Context element.</p>
141 
 
142 
</div><h3 id="Deployment_With_Tomcat">Deployment With Tomcat</h3><div class="text">
143 
 
144 
    <p><em>The description below uses the variable name $CATALINA_BASE to refer the
145 
    base directory against which most relative paths are resolved. If you have
146 
    not configured Tomcat for multiple instances by setting a CATALINA_BASE
147 
    directory, then $CATALINA_BASE will be set to the value of $CATALINA_HOME,
148 
    the directory into which you have installed Tomcat.</em></p>
149 
 
150 
<p>In order to be executed, a web application must be deployed on
151 
a servlet container.  This is true even during development.
152 
We will describe using Tomcat to provide the execution environment.
153 
A web application can be deployed in Tomcat by one of the following
154 
approaches:</p>
155 
<ul>
156 
<li><em>Copy unpacked directory hierarchy into a subdirectory in directory
157 
    <code>$CATALINA_BASE/webapps/</code></em>.  Tomcat will assign a
158 
    context path to your application based on the subdirectory name you
159 
    choose.  We will use this technique in the <code>build.xml</code>
160 
    file that we construct, because it is the quickest and easiest approach
161 
    during development.  Be sure to restart Tomcat after installing or
162 
    updating your application.
163 
    <br><br></li>
164 
<li><em>Copy the web application archive file into directory
165 
    <code>$CATALINA_BASE/webapps/</code></em>.  When Tomcat is started, it will
166 
    automatically expand the web application archive file into its unpacked
167 
    form, and execute the application that way.  This approach would typically
168 
    be used to install an additional application, provided by a third party
169 
    vendor or by your internal development staff, into an existing
170 
    Tomcat installation.  <strong>NOTE</strong> - If you use this approach,
171 
    and wish to update your application later, you must both replace the
172 
    web application archive file <strong>AND</strong> delete the expanded
173 
    directory that Tomcat created, and then restart Tomcat, in order to reflect
174 
    your changes.
175 
    <br><br></li>
176 
<li><em>Use the Tomcat "Manager" web application to deploy and undeploy
177 
    web applications</em>.  Tomcat includes a web application, deployed
178 
    by default on context path <code>/manager</code>, that allows you to
179 
    deploy and undeploy applications on a running Tomcat server without
180 
    restarting it. See <a href="../manager-howto.html">Manager App How-To</a>
181 
    for more information on using the Manager web application.<br><br></li>
182 
<li><em>Use "Manager" Ant Tasks In Your Build Script</em>.  Tomcat
183 
    includes a set of custom task definitions for the <code>Ant</code>
184 
    build tool that allow you to automate the execution of commands to the
185 
    "Manager" web application.  These tasks are used in the Tomcat deployer.
186 
    <br><br></li>
187 
<li><em>Use the Tomcat Deployer</em>.  Tomcat includes a packaged tool
188 
    bundling the Ant tasks, and can be used to automatically precompile JSPs
189 
    which are part of the web application before deployment to the server.
190 
    <br><br></li>
191 
</ul>
192 
 
193 
<p>Deploying your app on other servlet containers will be specific to each
194 
container, but all containers compatible with the Servlet API Specification
195 
(version 2.2 or later) are required to accept a web application archive file.
196 
Note that other containers are <strong>NOT</strong> required to accept an
197 
unpacked directory structure (as Tomcat does), or to provide mechanisms for
198 
shared library files, but these features are commonly available.</p>
199 
 
200 
</div></div></div></div></div><footer><div id="footer">
201 
    Copyright &copy; 1999-2025, The Apache Software Foundation
202 
    <br>
203 
    Apache Tomcat, Tomcat, Apache, the Apache Tomcat logo and the Apache logo
204 
    are either registered trademarks or trademarks of the Apache Software
205 
    Foundation.
206 
    </div></footer></div></body></html>