blob: c2d9abda4cf841c3fcdb368d6f6d17c34c7a74b9 [file] [log] [blame]
刘洪青6266f992017-05-15 21:21:03 +08001<html><head><META http-equiv="Content-Type" content="text/html; charset=iso-8859-1"><title>Application Developer's Guide (7.0.77) - Deployment</title><meta name="author" content="Craig R. McClanahan"><style type="text/css" media="print">
2 .noPrint {display: none;}
3 td#mainBody {width: 100%;}
4</style><style type="text/css">
5code {background-color:rgb(224,255,255);padding:0 0.1em;}
6code.attributeName, code.propertyName {background-color:transparent;}
7
8
9table {
10 border-collapse: collapse;
11 text-align: left;
12}
13table *:not(table) {
14 /* Prevent border-collapsing for table child elements like <div> */
15 border-collapse: separate;
16}
17
18th {
19 text-align: left;
20}
21
22
23div.codeBox pre code, code.attributeName, code.propertyName, code.noHighlight, .noHighlight code {
24 background-color: transparent;
25}
26div.codeBox {
27 overflow: auto;
28 margin: 1em 0;
29}
30div.codeBox pre {
31 margin: 0;
32 padding: 4px;
33 border: 1px solid #999;
34 border-radius: 5px;
35 background-color: #eff8ff;
36 display: table; /* To prevent <pre>s from taking the complete available width. */
37 /*
38 When it is officially supported, use the following CSS instead of display: table
39 to prevent big <pre>s from exceeding the browser window:
40 max-width: available;
41 width: min-content;
42 */
43}
44
45div.codeBox pre.wrap {
46 white-space: pre-wrap;
47}
48
49
50table.defaultTable tr, table.detail-table tr {
51 border: 1px solid #CCC;
52}
53
54table.defaultTable tr:nth-child(even), table.detail-table tr:nth-child(even) {
55 background-color: #FAFBFF;
56}
57
58table.defaultTable tr:nth-child(odd), table.detail-table tr:nth-child(odd) {
59 background-color: #EEEFFF;
60}
61
62table.defaultTable th, table.detail-table th {
63 background-color: #88b;
64 color: #fff;
65}
66
67table.defaultTable th, table.defaultTable td, table.detail-table th, table.detail-table td {
68 padding: 5px 8px;
69}
70
71
72p.notice {
73 border: 1px solid rgb(255, 0, 0);
74 background-color: rgb(238, 238, 238);
75 color: rgb(0, 51, 102);
76 padding: 0.5em;
77 margin: 1em 2em 1em 1em;
78}
79</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="
Hongqing Liufd5ee812014-05-10 16:32:51 +080080 The Apache Tomcat Servlet/JSP Container
刘洪青6266f992017-05-15 21:21:03 +080081 " border="0"></a></td><td><h1><font face="arial,helvetica,sanserif">Apache Tomcat 7</font></h1><font face="arial,helvetica,sanserif">Version 7.0.77, Mar 28 2017</font></td><td><!--APACHE LOGO--><a href="http://www.apache.org/"><img src="../images/asf-logo.svg" align="right" alt="Apache Logo" border="0" style="width: 266px;height: 83px;"></a></td></tr></table><table border="0" width="100%" cellspacing="4"><!--HEADER SEPARATOR--><tr><td colspan="2"><hr noshade size="1"></td></tr><tr><!--LEFT SIDE NAVIGATION--><td width="20%" valign="top" nowrap class="noPrint"><p><strong>Links</strong></p><ul><li><a href="../index.html">Docs Home</a></li><li><a href="index.html">App Dev Guide Home</a></li><li><a href="http://wiki.apache.org/tomcat/FAQ">FAQ</a></li><li><a href="#comments_section">User Comments</a></li></ul><p><strong>Contents</strong></p><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></td><!--RIGHT SIDE MAIN BODY--><td width="80%" valign="top" align="left" id="mainBody"><h1>Deployment</h1><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>
82<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>
Hongqing Liufd5ee812014-05-10 16:32:51 +080083</blockquote></td></tr></table><table border="0" cellspacing="0" cellpadding="2"><tr><td bgcolor="#525D76"><font color="#ffffff" face="arial,helvetica.sanserif"><a name="Background"><strong>Background</strong></a></font></td></tr><tr><td><blockquote>
84
85<p>Before describing how to organize your source code directories,
86it is useful to examine the runtime organization of a web application.
87Prior to the Servlet API Specification, version 2.2, there was little
88consistency between server platforms. However, servers that conform
89to the 2.2 (or later) specification are required to accept a
90<em>Web Application Archive</em> in a standard format, which is discussed
91further below.</p>
92
93<p>A web application is defined as a hierarchy of directories and files
94in a standard layout. Such a hierarchy can be accessed in its "unpacked"
95form, where each directory and file exists in the filesystem separately,
96or in a "packed" form known as a Web ARchive, or WAR file. The former format
97is more useful during development, while the latter is used when you
98distribute your application to be installed.</p>
99
100<p>The top-level directory of your web application hierarchy is also the
101<em>document root</em> of your application. Here, you will place the HTML
102files and JSP pages that comprise your application's user interface. When the
103system administrator deploys your application into a particular server, he
104or she assigns a <em>context path</em> to your application (a later section
105of this manual describes deployment on Tomcat). Thus, if the
106system administrator assigns your application to the context path
107<code>/catalog</code>, then a request URI referring to
108<code>/catalog/index.html</code> will retrieve the <code>index.html</code>
109file from your document root.</p>
110
111</blockquote></td></tr></table><table border="0" cellspacing="0" cellpadding="2"><tr><td bgcolor="#525D76"><font color="#ffffff" face="arial,helvetica.sanserif"><a name="Standard Directory Layout"><!--()--></a><a name="Standard_Directory_Layout"><strong>Standard Directory Layout</strong></a></font></td></tr><tr><td><blockquote>
112
113<p>To facilitate creation of a Web Application Archive file in the required
114format, it is convenient to arrange the "executable" files of your web
115application (that is, the files that Tomcat actually uses when executing
116your app) in the same organization as required by the WAR format itself.
117To do this, you will end up with the following contents in your
118application's "document root" directory:</p>
119<ul>
120<li><strong>*.html, *.jsp, etc.</strong> - The HTML and JSP pages, along
121 with other files that must be visible to the client browser (such as
122 JavaScript, stylesheet files, and images) for your application.
123 In larger applications you may choose to divide these files into
124 a subdirectory hierarchy, but for smaller apps, it is generally
125 much simpler to maintain only a single directory for these files.
126 <br><br></li>
127<li><strong>/WEB-INF/web.xml</strong> - The <em>Web Application Deployment
128 Descriptor</em> for your application. This is an XML file describing
129 the servlets and other components that make up your application,
130 along with any initialization parameters and container-managed
131 security constraints that you want the server to enforce for you.
132 This file is discussed in more detail in the following subsection.
133 <br><br></li>
134<li><strong>/WEB-INF/classes/</strong> - This directory contains any Java
135 class files (and associated resources) required for your application,
136 including both servlet and non-servlet classes, that are not combined
137 into JAR files. If your classes are organized into Java packages,
138 you must reflect this in the directory hierarchy under
139 <code>/WEB-INF/classes/</code>. For example, a Java class named
140 <code>com.mycompany.mypackage.MyServlet</code>
141 would need to be stored in a file named
142 <code>/WEB-INF/classes/com/mycompany/mypackage/MyServlet.class</code>.
143 <br><br></li>
144<li><strong>/WEB-INF/lib/</strong> - This directory contains JAR files that
145 contain Java class files (and associated resources) required for your
146 application, such as third party class libraries or JDBC drivers.</li>
147</ul>
148
刘洪青6266f992017-05-15 21:21:03 +0800149<p>When you install an application into Tomcat (or any other 2.2 or later
150Servlet container), the classes in the <code>WEB-INF/classes/</code>
Hongqing Liufd5ee812014-05-10 16:32:51 +0800151directory, as well as all classes in JAR files found in the
152<code>WEB-INF/lib/</code> directory, are made visible to other classes
153within your particular web application. Thus, if
154you include all of the required library classes in one of these places (be
155sure to check licenses for redistribution rights for any third party libraries
156you utilize), you will simplify the installation of your web application --
157no adjustment to the system class path (or installation of global library
158files in your server) will be necessary.</p>
159
160<p>Much of this information was extracted from Chapter 9 of the Servlet
161API Specification, version 2.3, which you should consult for more details.</p>
162
163</blockquote></td></tr></table><table border="0" cellspacing="0" cellpadding="2"><tr><td bgcolor="#525D76"><font color="#ffffff" face="arial,helvetica.sanserif"><a name="Shared Library Files"><!--()--></a><a name="Shared_Library_Files"><strong>Shared Library Files</strong></a></font></td></tr><tr><td><blockquote>
164
刘洪青6266f992017-05-15 21:21:03 +0800165<p>Like most servlet containers, Tomcat also supports mechanisms to install
Hongqing Liufd5ee812014-05-10 16:32:51 +0800166library JAR files (or unpacked classes) once, and make them visible to all
167installed web applications (without having to be included inside the web
168application itself). The details of how Tomcat locates and shares such
169classes are described in the
170<a href="../class-loader-howto.html">Class Loader HOW-TO</a> documentation.
刘洪青6266f992017-05-15 21:21:03 +0800171The location commonly used within a Tomcat installation for shared code is
Hongqing Liufd5ee812014-05-10 16:32:51 +0800172<strong>$CATALINA_HOME/lib</strong>. JAR files placed here are visible both to
173web applications and internal Tomcat code. This is a good place to put JDBC
174drivers that are required for both your application or internal Tomcat use
175(such as for a JDBCRealm).</p>
176
刘洪青6266f992017-05-15 21:21:03 +0800177<p>Out of the box, a standard Tomcat installation includes a variety
Hongqing Liufd5ee812014-05-10 16:32:51 +0800178of pre-installed shared library files, including:</p>
179<ul>
刘洪青6266f992017-05-15 21:21:03 +0800180<li>The <em>Servlet 3.0</em> and <em>JSP 2.2</em> APIs that are fundamental
Hongqing Liufd5ee812014-05-10 16:32:51 +0800181 to writing servlets and JavaServer Pages.<br><br></li>
182</ul>
183
184</blockquote></td></tr></table><table border="0" cellspacing="0" cellpadding="2"><tr><td bgcolor="#525D76"><font color="#ffffff" face="arial,helvetica.sanserif"><a name="Web Application Deployment Descriptor"><!--()--></a><a name="Web_Application_Deployment_Descriptor"><strong>Web Application Deployment Descriptor</strong></a></font></td></tr><tr><td><blockquote>
185
186<p>As mentioned above, the <code>/WEB-INF/web.xml</code> file contains the
187Web Application Deployment Descriptor for your application. As the filename
188extension implies, this file is an XML document, and defines everything about
189your application that a server needs to know (except the <em>context path</em>,
190which is assigned by the system administrator when the application is
191deployed).</p>
192
193<p>The complete syntax and semantics for the deployment descriptor is defined
194in Chapter 13 of the Servlet API Specification, version 2.3. Over time, it
195is expected that development tools will be provided that create and edit the
196deployment descriptor for you. In the meantime, to provide a starting point,
Hongqing Liu71898292014-10-15 13:31:32 +0800197a <a href="web.xml.txt" target="_blank">basic web.xml file</a>
Hongqing Liufd5ee812014-05-10 16:32:51 +0800198is provided. This file includes comments that describe the purpose of each
199included element.</p>
200
201<p><strong>NOTE</strong> - The Servlet Specification includes a Document
202Type Descriptor (DTD) for the web application deployment descriptor, and
刘洪青6266f992017-05-15 21:21:03 +0800203Tomcat enforces the rules defined here when processing your application's
Hongqing Liufd5ee812014-05-10 16:32:51 +0800204<code>/WEB-INF/web.xml</code> file. In particular, you <strong>must</strong>
205enter your descriptor elements (such as <code>&lt;filter&gt;</code>,
206<code>&lt;servlet&gt;</code>, and <code>&lt;servlet-mapping&gt;</code> in
207the order defined by the DTD (see Section 13.3).</p>
208
209</blockquote></td></tr></table><table border="0" cellspacing="0" cellpadding="2"><tr><td bgcolor="#525D76"><font color="#ffffff" face="arial,helvetica.sanserif"><a name="Tomcat Context Descriptor"><!--()--></a><a name="Tomcat_Context_Descriptor"><strong>Tomcat Context Descriptor</strong></a></font></td></tr><tr><td><blockquote>
210
211<p>A /META-INF/context.xml file can be used to define Tomcat specific
212configuration options, such as an access log, data sources, session manager
213configuration and more. This XML file must contain one Context element, which
214will be considered as if it was the child of the Host element corresponding
215to the Host to which the web application is being deployed. The
刘洪青6266f992017-05-15 21:21:03 +0800216<a href="../config/context.html">Tomcat configuration documentation</a> contains
Hongqing Liufd5ee812014-05-10 16:32:51 +0800217information on the Context element.</p>
218
刘洪青6266f992017-05-15 21:21:03 +0800219</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 With Tomcat"><!--()--></a><a name="Deployment_With_Tomcat"><strong>Deployment With Tomcat</strong></a></font></td></tr><tr><td><blockquote>
Hongqing Liufd5ee812014-05-10 16:32:51 +0800220
刘洪青6266f992017-05-15 21:21:03 +0800221 <p><em>The description below uses the variable name $CATALINA_BASE to refer the
Hongqing Liufd5ee812014-05-10 16:32:51 +0800222 base directory against which most relative paths are resolved. If you have
刘洪青6266f992017-05-15 21:21:03 +0800223 not configured Tomcat for multiple instances by setting a CATALINA_BASE
Hongqing Liufd5ee812014-05-10 16:32:51 +0800224 directory, then $CATALINA_BASE will be set to the value of $CATALINA_HOME,
刘洪青6266f992017-05-15 21:21:03 +0800225 the directory into which you have installed Tomcat.</em></p>
Hongqing Liufd5ee812014-05-10 16:32:51 +0800226
227<p>In order to be executed, a web application must be deployed on
228a servlet container. This is true even during development.
刘洪青6266f992017-05-15 21:21:03 +0800229We will describe using Tomcat to provide the execution environment.
Hongqing Liufd5ee812014-05-10 16:32:51 +0800230A web application can be deployed in Tomcat by one of the following
231approaches:</p>
232<ul>
233<li><em>Copy unpacked directory hierarchy into a subdirectory in directory
234 <code>$CATALINA_BASE/webapps/</code></em>. Tomcat will assign a
235 context path to your application based on the subdirectory name you
236 choose. We will use this technique in the <code>build.xml</code>
237 file that we construct, because it is the quickest and easiest approach
238 during development. Be sure to restart Tomcat after installing or
239 updating your application.
240 <br><br></li>
241<li><em>Copy the web application archive file into directory
242 <code>$CATALINA_BASE/webapps/</code></em>. When Tomcat is started, it will
243 automatically expand the web application archive file into its unpacked
244 form, and execute the application that way. This approach would typically
245 be used to install an additional application, provided by a third party
246 vendor or by your internal development staff, into an existing
247 Tomcat installation. <strong>NOTE</strong> - If you use this approach,
248 and wish to update your application later, you must both replace the
249 web application archive file <strong>AND</strong> delete the expanded
250 directory that Tomcat created, and then restart Tomcat, in order to reflect
251 your changes.
252 <br><br></li>
刘洪青6266f992017-05-15 21:21:03 +0800253<li><em>Use the Tomcat "Manager" web application to deploy and undeploy
254 web applications</em>. Tomcat includes a web application, deployed
Hongqing Liufd5ee812014-05-10 16:32:51 +0800255 by default on context path <code>/manager</code>, that allows you to
256 deploy and undeploy applications on a running Tomcat server without
刘洪青6266f992017-05-15 21:21:03 +0800257 restarting it. See <a href="../manager-howto.html">Manager App HOW-TO</a>
Hongqing Liufd5ee812014-05-10 16:32:51 +0800258 for more information on using the Manager web application.<br><br></li>
刘洪青6266f992017-05-15 21:21:03 +0800259<li><em>Use "Manager" Ant Tasks In Your Build Script</em>. Tomcat
Hongqing Liufd5ee812014-05-10 16:32:51 +0800260 includes a set of custom task definitions for the <code>Ant</code>
261 build tool that allow you to automate the execution of commands to the
262 "Manager" web application. These tasks are used in the Tomcat deployer.
263 <br><br></li>
刘洪青6266f992017-05-15 21:21:03 +0800264<li><em>Use the Tomcat Deployer</em>. Tomcat includes a packaged tool
Hongqing Liufd5ee812014-05-10 16:32:51 +0800265 bundling the Ant tasks, and can be used to automatically precompile JSPs
266 which are part of the web application before deployment to the server.
267 <br><br></li>
268</ul>
269
270<p>Deploying your app on other servlet containers will be specific to each
271container, but all containers compatible with the Servlet API Specification
272(version 2.2 or later) are required to accept a web application archive file.
273Note that other containers are <strong>NOT</strong> required to accept an
274unpacked directory structure (as Tomcat does), or to provide mechanisms for
275shared library files, but these features are commonly available.</p>
276
刘洪青6266f992017-05-15 21:21:03 +0800277</blockquote></td></tr></table></td></tr><tr class="noPrint"><td width="20%" valign="top" nowrap class="noPrint"></td><td width="80%" valign="top" align="left"><table border="0" cellspacing="0" cellpadding="2"><tr><td bgcolor="#525D76"><font color="#ffffff" face="arial,helvetica.sanserif"><a name="comments_section" id="comments_section"><strong>Comments</strong></a></font></td></tr><tr><td><blockquote><p class="notice"><strong>Notice: </strong>This comments section collects your suggestions
278 on improving documentation for Apache Tomcat.<br><br>
279 If you have trouble and need help, read
280 <a href="http://tomcat.apache.org/findhelp.html">Find Help</a> page
281 and ask your question on the tomcat-users
282 <a href="http://tomcat.apache.org/lists.html">mailing list</a>.
283 Do not ask such questions here. This is not a Q&amp;A section.<br><br>
284 The Apache Comments System is explained <a href="../comments.html">here</a>.
285 Comments may be removed by our moderators if they are either
286 implemented or considered invalid/off-topic.</p><script type="text/javascript"><!--//--><![CDATA[//><!--
287 var comments_shortname = 'tomcat';
288 var comments_identifier = 'http://tomcat.apache.org/tomcat-7.0-doc/appdev/deployment.html';
289 (function(w, d) {
290 if (w.location.hostname.toLowerCase() == "tomcat.apache.org") {
291 d.write('<div id="comments_thread"><\/div>');
292 var s = d.createElement('script');
293 s.type = 'text/javascript';
294 s.async = true;
295 s.src = 'https://comments.apache.org/show_comments.lua?site=' + comments_shortname + '&page=' + comments_identifier;
296 (d.getElementsByTagName('head')[0] || d.getElementsByTagName('body')[0]).appendChild(s);
297 }
298 else {
299 d.write('<div id="comments_thread"><strong>Comments are disabled for this page at the moment.<\/strong><\/div>');
300 }
301 })(window, document);
302 //--><!]]></script></blockquote></td></tr></table></td></tr><!--FOOTER SEPARATOR--><tr><td colspan="2"><hr noshade size="1"></td></tr><!--PAGE FOOTER--><tr><td colspan="2"><div align="center"><font color="#525D76" size="-1"><em>
303 Copyright &copy; 1999-2017, Apache Software Foundation
Hongqing Liufd5ee812014-05-10 16:32:51 +0800304 </em></font></div></td></tr></table></body></html>