source: nutchez-0.1/tomcat/webapps/docs/printer/html-manager-howto.html @ 69

Last change on this file since 69 was 66, checked in by waue, 16 years ago

NutchEz - an easy way to nutch
File size: 38.5 KB
Line 
1<html><head><META http-equiv="Content-Type" content="text/html; charset=iso-8859-1"><title>Apache Tomcat 6.0 - Tomcat Web Application Manager How To</title><meta value="Glenn L. Nielsen" name="author"><meta value="glenn@apache.org" name="email"></head><body vlink="#525D76" alink="#525D76" link="#525D76" text="#000000" bgcolor="#ffffff"><table cellspacing="0" width="100%" border="0"><!--PAGE HEADER--><tr><td><!--PROJECT LOGO--><a href="http://tomcat.apache.org/"><img border="0" alt="
2      The Apache Tomcat Servlet/JSP Container
3    " align="right" src="./../images/tomcat.gif"></a></td><td><font face="arial,helvetica,sanserif"><h1>Apache Tomcat 6.0</h1></font></td><td><!--APACHE LOGO--><a href="http://www.apache.org/"><img border="0" alt="Apache Logo" align="right" src="./../images/asf-logo.gif"></a></td></tr></table><table cellspacing="4" width="100%" border="0"><!--HEADER SEPARATOR--><tr><td colspan="2"><hr size="1" noshade></td></tr><tr><!--RIGHT SIDE MAIN BODY--><td align="left" valign="top" width="80%"><table cellspacing="4" width="100%" border="0"><tr><td valign="top" align="left"><h1>Apache Tomcat 6.0</h1><h2>Tomcat Web Application Manager How To</h2></td><td nowrap="true" valign="top" align="right"><img border="0" hspace="0" vspace="0" height="1" width="1" src="./../images/void.gif"></td></tr></table><table cellpadding="2" cellspacing="0" border="0"><tr><td bgcolor="#525D76"><font face="arial,helvetica.sanserif" color="#ffffff"><a name="Introduction"><strong>Introduction</strong></a></font></td></tr><tr><td><blockquote>
4
5<p>In many production environments it is very useful to have the capability
6to manage your web applications without having to shut down and restart
7Tomcat.  This document is for the HTML web interface to the web application
8<a href="manager-howto.html">manager</a>.</p>
9
10<p>The interface is divided into five sections:
11<ul>
12  <li><strong>Message</strong> - Displays success and failure messages.</li>
13  <li><strong>Manager</strong> - General manager operations like list and
14      help.</li>
15  <li><strong>Applications</strong> - List of web applications and
16      commands.</li>
17  <li><strong>Deploy</strong> - Deploying web applications.</li>
18  <li><strong>Server Information</strong> - Information about the Tomcat
19      server.</li>
20</ul>
21</p>
22
23</blockquote></td></tr></table><table cellpadding="2" cellspacing="0" border="0"><tr><td bgcolor="#525D76"><font face="arial,helvetica.sanserif" color="#ffffff"><a name="Message"><strong>Message</strong></a></font></td></tr><tr><td><blockquote>
24
25<p>
26Displays information about the success or failure of the last web application
27manager command you performed. If it succeeded <strong>OK</strong> is displayed
28and may be followed by a success message. If it failed <strong>FAIL</strong>
29is displayed followed by an error message. Common failure messages are
30documented below for each command.  The complete list of failure messages for
31each command can be found in the <a href="manager-howto.html">manager</a> web
32application documentation.
33</p>
34
35</blockquote></td></tr></table><table cellpadding="2" cellspacing="0" border="0"><tr><td bgcolor="#525D76"><font face="arial,helvetica.sanserif" color="#ffffff"><a name="Manager"><strong>Manager</strong></a></font></td></tr><tr><td><blockquote>
36
37<p>The Manager section has three links:
38<ul>
39  <li><strong>List Applications</strong> - Redisplay a list of web
40      applications.</li>
41  <li><strong>HTML Manager Help</strong> - A link to this document.</li>
42  <li><strong>Manager Help</strong> - A link to the comprehensive Manager
43      App HOW TO.</li>
44</ul>
45</p>
46
47</blockquote></td></tr></table><table cellpadding="2" cellspacing="0" border="0"><tr><td bgcolor="#525D76"><font face="arial,helvetica.sanserif" color="#ffffff"><a name="Applications"><strong>Applications</strong></a></font></td></tr><tr><td><blockquote>
48
49<p>The Applications section lists information about all the installed web
50applications and provides links for managing them. For each web application
51the following is displayed:
52<ul>
53  <li><strong>Path</strong> - The web applicaton context path.</li>
54  <li><strong>Display Name</strong> - The display name for the web application
55      if it has one configured in its "web.xml" file.</li>
56  <li><strong>Running</strong> - Whether the web application is running and
57      available (true), or not running and unavailable (false).</li>
58  <li><strong>Sessions</strong> - The number of active sessions for remote
59      users of this web application.  The number of sessions is a link which
60      when submitted displays more details about session usage by the web
61      application in the Message box.</li>
62  <li><strong>Commands</strong> - Lists all commands which can be performed on
63      the web application. Only those commands which can be performed will be
64      listed as a link which can be submitted. No commands can be performed on
65      the manager web application itself. The following commands can be
66      performed:
67      <ul>
68        <li><strong>Start</strong> - Start a web application which had been
69            stopped.</li>
70        <li><strong>Stop</strong> - Stop a web application which is currently
71            running and make it unavailable.</li>
72        <li><strong>Reload</strong> - Reload the web application so that new
73            ".jar" files in <code>/WEB-INF/lib/</code> or new classes in
74            <code>/WEB-INF/classes/</code> can be used.</li>
75        <li><strong>Undeploy</strong> - Stop and then remove this web
76             application from the server.</li>
77      </ul>
78  </li>
79</ul>
80</p>
81
82<table cellpadding="2" cellspacing="0" border="0"><tr><td bgcolor="#828DA6"><font face="arial,helvetica.sanserif" color="#ffffff"><a name="Start"><strong>Start</strong></a></font></td></tr><tr><td><blockquote>
83
84<p>Signal a stopped application to restart, and make itself available again.
85Stopping and starting is useful, for example, if the database required by
86your application becomes temporarily unavailable.  It is usually better to
87stop the web application that relies on this database rather than letting
88users continuously encounter database exceptions.</p>
89
90<p>If this command succeeds, you will see a Message like this:</p>
91<div align="left"><table border="0" cellpadding="0" cellspacing="4"><tr><td height="1" width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" src="./../images/void.gif"></td><td height="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" src="./../images/void.gif"></td><td height="1" width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" src="./../images/void.gif"></td></tr><tr><td width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" src="./../images/void.gif"></td><td height="1" bgcolor="#ffffff"><pre>
92OK - Started application at context path /examples
93</pre></td><td width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" src="./../images/void.gif"></td></tr><tr><td height="1" width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" src="./../images/void.gif"></td><td height="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" src="./../images/void.gif"></td><td height="1" width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" src="./../images/void.gif"></td></tr></table></div>
94
95<p>Otherwise, the Message will start with <code>FAIL</code> and include an
96error message.  Possible causes for problems include:
97<ul>
98<li><em>Encountered exception</em>
99    <blockquote>             
100    <p>An exception was encountered trying to start the web application.
101    Check the Tomcat 6 logs for the details.</p>
102    </blockquote></li>       
103<li><em>Invalid context path was specified</em>
104    <blockquote>             
105    <p>The context path must start with a slash character, unless you are
106    referencing the ROOT web application -- in which case the context path
107    must be a zero-length string.</p>
108    </blockquote></li>       
109<li><em>No context exists for path /foo</em>
110    <blockquote>             
111    <p>There is no deployed application on the context path
112    that you specified.</p> 
113    </blockquote></li>       
114<li><em>No context path was specified</em>
115    <blockquote>             
116    The <code>path</code> parameter is required.
117    </blockquote></li>       
118</ul>
119</p>
120
121</blockquote></td></tr></table>
122
123<table cellpadding="2" cellspacing="0" border="0"><tr><td bgcolor="#828DA6"><font face="arial,helvetica.sanserif" color="#ffffff"><a name="Stop"><strong>Stop</strong></a></font></td></tr><tr><td><blockquote>
124
125<p>Signal an existing application to make itself unavailable, but leave it
126deployed.  Any request that comes in while an application is
127stopped will see an HTTP error 404, and this application will show as
128"stopped" on a list applications command.</p>
129                             
130<p>If this command succeeds, you will see a Message like this:</p>
131<div align="left"><table border="0" cellpadding="0" cellspacing="4"><tr><td height="1" width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" src="./../images/void.gif"></td><td height="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" src="./../images/void.gif"></td><td height="1" width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" src="./../images/void.gif"></td></tr><tr><td width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" src="./../images/void.gif"></td><td height="1" bgcolor="#ffffff"><pre>
132OK - Stopped application at context path /examples
133</pre></td><td width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" src="./../images/void.gif"></td></tr><tr><td height="1" width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" src="./../images/void.gif"></td><td height="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" src="./../images/void.gif"></td><td height="1" width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" src="./../images/void.gif"></td></tr></table></div>
134                             
135<p>Otherwise, the Message will start with <code>FAIL</code> and include an
136error message.  Possible causes for problems include:
137<ul>                         
138<li><em>Encountered exception</em>
139    <blockquote>             
140    <p>An exception was encountered trying to stop the web application.
141    Check the Tomcat 6 logs for the details.</p>
142    </blockquote></li>       
143<li><em>Invalid context path was specified</em>
144    <blockquote>             
145    <p>The context path must start with a slash character, unless you are
146    referencing the ROOT web application -- in which case the context path
147    must be a zero-length string.</p>
148    </blockquote></li>       
149<li><em>No context exists for path /foo</em>
150    <blockquote>             
151    <p>There is no deployed application on the context path
152    that you specified.</p> 
153    </blockquote></li>       
154<li><em>No context path was specified</em>
155    <blockquote>             
156    The <code>path</code> parameter is required.
157    </blockquote></li>       
158</ul>
159</p>
160
161</blockquote></td></tr></table>
162
163<table cellpadding="2" cellspacing="0" border="0"><tr><td bgcolor="#828DA6"><font face="arial,helvetica.sanserif" color="#ffffff"><a name="Reload"><strong>Reload</strong></a></font></td></tr><tr><td><blockquote>
164
165<p>Signal an existing application to shut itself down and reload.  This can
166be useful when the web application context is not reloadable and you have
167updated classes or property files in the <code>/WEB-INF/classes</code>
168directory or when you have added or updated jar files in the
169<code>/WEB-INF/lib</code> directory.
170</p>
171<p><strong>NOTE:</strong> The <code>/WEB-INF/web.xml</code>
172web application configuration file is not checked on a reload;
173the previous web.xml configuration is used.
174If you have made changes to your web.xml file you must stop
175then start the web application.
176</p>
177
178<p>If this command succeeds, you will see a Message like this:</p>
179<div align="left"><table border="0" cellpadding="0" cellspacing="4"><tr><td height="1" width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" src="./../images/void.gif"></td><td height="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" src="./../images/void.gif"></td><td height="1" width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" src="./../images/void.gif"></td></tr><tr><td width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" src="./../images/void.gif"></td><td height="1" bgcolor="#ffffff"><pre>
180OK - Reloaded application at context path /examples
181</pre></td><td width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" src="./../images/void.gif"></td></tr><tr><td height="1" width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" src="./../images/void.gif"></td><td height="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" src="./../images/void.gif"></td><td height="1" width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" src="./../images/void.gif"></td></tr></table></div>
182
183<p>Otherwise, the Message will start with <code>FAIL</code> and include an
184error message.  Possible causes for problems include:
185<ul>
186<li><em>Encountered exception</em>
187    <blockquote>             
188    <p>An exception was encountered trying to restart the web application.
189    Check the Tomcat 6 logs for the details.</p>
190    </blockquote></li>       
191<li><em>Invalid context path was specified</em>
192    <blockquote>             
193    <p>The context path must start with a slash character, unless you are
194    referencing the ROOT web application -- in which case the context path
195    must be a zero-length string.</p>
196    </blockquote></li>       
197<li><em>No context exists for path /foo</em>
198    <blockquote>             
199    <p>There is no deployed application on the context path
200    that you specified.</p> 
201    </blockquote></li>       
202<li><em>No context path was specified</em>
203    <blockquote>             
204    The <code>path</code> parameter is required.
205    </blockquote></li>       
206<li><em>Reload not supported on WAR deployed at path /foo</em>
207    <blockquote>             
208    Currently, application reloading (to pick up changes to the classes or
209    <code>web.xml</code> file) is not supported when a web application is
210    installed directly from a WAR file, which happens when the host is
211    configured to not unpack WAR files. As it only works when the web
212    application is installed from an unpacked directory, if you are using
213    a WAR file, you should <code>undeploy</code> and then <code>deploy</code> 
214    the application again to pick up your changes.
215    </blockquote></li>       
216</ul>
217</p>
218
219</blockquote></td></tr></table>
220
221<table cellpadding="2" cellspacing="0" border="0"><tr><td bgcolor="#828DA6"><font face="arial,helvetica.sanserif" color="#ffffff"><a name="Undeploy"><strong>Undeploy</strong></a></font></td></tr><tr><td><blockquote>
222
223<p><strong><font color="red">WARNING</font> - This command will delete the
224contents of the web application directory and/or ".war" file if it exists within
225the <code>appBase</code> directory (typically "webapps") for this virtual host
226</strong>.  The web application temporary work directory is also deleted.  If
227you simply want to take an application out of service, you should use the
228<code>/stop</code> command instead.</p>
229                             
230<p>Signal an existing application to gracefully shut itself down, and then
231remove it from Tomcat (which also makes this context path available for
232reuse later).  This command is the logical opposite of the
233<code>/deploy</code> Ant command, and the related deploy features available
234in the HTML manager.</p>
235                             
236<p>If this command succeeds, you will see a Message like this:</p>
237<div align="left"><table border="0" cellpadding="0" cellspacing="4"><tr><td height="1" width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" src="./../images/void.gif"></td><td height="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" src="./../images/void.gif"></td><td height="1" width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" src="./../images/void.gif"></td></tr><tr><td width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" src="./../images/void.gif"></td><td height="1" bgcolor="#ffffff"><pre>
238OK - Undeployed application at context path /examples
239</pre></td><td width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" src="./../images/void.gif"></td></tr><tr><td height="1" width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" src="./../images/void.gif"></td><td height="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" src="./../images/void.gif"></td><td height="1" width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" src="./../images/void.gif"></td></tr></table></div>
240                             
241<p>Otherwise, the Message will start with <code>FAIL</code> and include an
242error message.  Possible causes for problems include:
243<ul>                         
244<li><em>Encountered exception</em>
245    <blockquote>             
246    <p>An exception was encountered trying to undeploy the web application.
247    Check the Tomcat logs for the details.</p>
248    </blockquote></li>       
249<li><em>Invalid context path was specified</em>
250    <blockquote>             
251    <p>The context path must start with a slash character, unless you are
252    referencing the ROOT web application -- in which case the context path
253    must be a zero-length string.</p>
254    </blockquote></li>       
255<li><em>No context exists for path /foo</em>
256    <blockquote>             
257    <p>There is no deployed application on the context path
258    that you specified.</p> 
259    </blockquote></li>       
260<li><em>No context path was specified</em>
261    <blockquote>             
262    The <code>path</code> parameter is required.
263    </blockquote></li>       
264</ul>
265</p>
266
267</blockquote></td></tr></table>
268
269</blockquote></td></tr></table><table cellpadding="2" cellspacing="0" border="0"><tr><td bgcolor="#525D76"><font face="arial,helvetica.sanserif" color="#ffffff"><a name="Deploy"><strong>Deploy</strong></a></font></td></tr><tr><td><blockquote>
270
271<p>Web applications can be deployed using files or directories located
272on the Tomcat server or you can upload a web application archive (WAR)
273file to the server.</p>
274
275<p>To install an application, fill in the appropriate fields for the type
276of install you want to do and then submit it using the <i>Install</i>
277button.</p>
278
279<table cellpadding="2" cellspacing="0" border="0"><tr><td bgcolor="#828DA6"><font face="arial,helvetica.sanserif" color="#ffffff"><a name="Deploy directory or WAR file located on server"><strong>Deploy directory or WAR file located on server</strong></a></font></td></tr><tr><td><blockquote>
280
281<p>Deploy and start a new web application, attached to the specified <i>Context
282Path:</i> (which must not be in use by any other web application).
283This command is the logical opposite of the <em>Undeploy</em> command.</p>
284
285<p>There are a number of different ways the deploy command can be used.</p>
286
287<h3>Deploy a Directory or WAR by URL</h3>
288
289<p>Install a web application directory or ".war" file located on the Tomcat
290server. If no <i>Context Path</i> is specified, the directory name or the
291war file name without the ".war" extension is used as the path. The
292<i>WAR or Directory URL</i> specifies a URL (including the <code>file:</code>
293scheme) for either a directory or a web application archive (WAR) file. The
294supported syntax for a URL referring to a WAR file is described on the Javadocs
295page for the <code>java.net.JarURLConnection</code> class.  Use only URLs that
296refer to the entire WAR file.</p>
297
298<p>In this example the web application located in the directory
299<code>C:\path\to\foo</code> on the Tomcat server (running on Windows)
300is deployed as the web application context named <code>/footoo</code>.
301<div align="left"><table border="0" cellpadding="0" cellspacing="4"><tr><td height="1" width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" src="./../images/void.gif"></td><td height="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" src="./../images/void.gif"></td><td height="1" width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" src="./../images/void.gif"></td></tr><tr><td width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" src="./../images/void.gif"></td><td height="1" bgcolor="#ffffff"><pre>
302Context Path: /footoo
303WAR or Directory URL: file:C:/path/to/foo
304</pre></td><td width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" src="./../images/void.gif"></td></tr><tr><td height="1" width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" src="./../images/void.gif"></td><td height="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" src="./../images/void.gif"></td><td height="1" width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" src="./../images/void.gif"></td></tr></table></div>
305</p>
306
307<p>In this example the ".war" file <code>/path/to/bar.war</code> on the
308Tomcat server (running on Unix) is deployed as the web application
309context named <code>/bar</code>. Notice that there is no <code>path</code>
310parameter so the context path defaults to the name of the web application
311archive file without the ".war" extension.
312<div align="left"><table border="0" cellpadding="0" cellspacing="4"><tr><td height="1" width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" src="./../images/void.gif"></td><td height="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" src="./../images/void.gif"></td><td height="1" width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" src="./../images/void.gif"></td></tr><tr><td width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" src="./../images/void.gif"></td><td height="1" bgcolor="#ffffff"><pre>
313WAR or Directory URL: jar:file:/path/to/bar.war!/
314</pre></td><td width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" src="./../images/void.gif"></td></tr><tr><td height="1" width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" src="./../images/void.gif"></td><td height="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" src="./../images/void.gif"></td><td height="1" width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" src="./../images/void.gif"></td></tr></table></div>
315</p>
316
317<h3>Deploy a Directory or War from the Host appBase</h3>
318
319<p>Install a web application directory or ".war" file located in your Host
320appBase directory. If no <i>Context Path</i> is specified the directory name
321or the war file name without the ".war" extension is used as the path.</p>
322
323<p>In this example the web application located in a subdirectory named
324<code>foo</code> in the Host appBase directory of the Tomcat server is
325deployed as the web application context named <code>/foo</code>. Notice
326that there is no <code>path</code> parameter so the context path defaults
327to the name of the web application directory.
328<div align="left"><table border="0" cellpadding="0" cellspacing="4"><tr><td height="1" width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" src="./../images/void.gif"></td><td height="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" src="./../images/void.gif"></td><td height="1" width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" src="./../images/void.gif"></td></tr><tr><td width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" src="./../images/void.gif"></td><td height="1" bgcolor="#ffffff"><pre>
329WAR or Directory URL: foo
330</pre></td><td width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" src="./../images/void.gif"></td></tr><tr><td height="1" width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" src="./../images/void.gif"></td><td height="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" src="./../images/void.gif"></td><td height="1" width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" src="./../images/void.gif"></td></tr></table></div>
331</p>
332
333<p>In this example the ".war" file <code>bar.war</code> located in your
334Host appBase directory on the Tomcat server is deployed as the web
335application context named <code>/bartoo</code>.
336<div align="left"><table border="0" cellpadding="0" cellspacing="4"><tr><td height="1" width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" src="./../images/void.gif"></td><td height="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" src="./../images/void.gif"></td><td height="1" width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" src="./../images/void.gif"></td></tr><tr><td width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" src="./../images/void.gif"></td><td height="1" bgcolor="#ffffff"><pre>
337Context Path: /bartoo
338WAR or Directory URL: bar.war
339</pre></td><td width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" src="./../images/void.gif"></td></tr><tr><td height="1" width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" src="./../images/void.gif"></td><td height="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" src="./../images/void.gif"></td><td height="1" width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" src="./../images/void.gif"></td></tr></table></div>
340</p>
341
342<h3>Deploy using a Context configuration ".xml" file</h3>
343
344<p>If the Host deployXML flag is set to true, you can install a web
345application using a Context configuration ".xml" file and an optional
346".war" file or web application directory. The <i>Context Path</i>
347is not used when installing a web application using a context ".xml"
348configuration file.</p>
349
350<p>A Context configuration ".xml" file can contain valid XML for a
351web application Context just as if it were configured in your
352Tomcat <code>server.xml</code> configuration file. Here is an
353example for Tomcat running on Windows:
354<div align="left"><table border="0" cellpadding="0" cellspacing="4"><tr><td height="1" width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" src="./../images/void.gif"></td><td height="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" src="./../images/void.gif"></td><td height="1" width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" src="./../images/void.gif"></td></tr><tr><td width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" src="./../images/void.gif"></td><td height="1" bgcolor="#ffffff"><pre>
355&lt;Context path="/foobar" docBase="C:\path\to\application\foobar"
356         debug="0"&gt;
357
358  &lt;!-- Link to the user database we will get roles from --&gt;
359  &lt;ResourceLink name="users" global="UserDatabase"
360                type="org.apache.catalina.UserDatabase"/&gt;
361
362&lt;/Context&gt;
363</pre></td><td width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" src="./../images/void.gif"></td></tr><tr><td height="1" width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" src="./../images/void.gif"></td><td height="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" src="./../images/void.gif"></td><td height="1" width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" src="./../images/void.gif"></td></tr></table></div>
364</p>
365
366<p>Use of the <i>WAR or Directory URL</i> is optional. When used
367to select a web application ".war" file or directory it overrides any
368docBase configured in the context configuration ".xml" file.</p>
369
370<p>Here is an example of installing an application using a Context
371configuration ".xml" file for Tomcat running on Windows.
372<div align="left"><table border="0" cellpadding="0" cellspacing="4"><tr><td height="1" width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" src="./../images/void.gif"></td><td height="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" src="./../images/void.gif"></td><td height="1" width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" src="./../images/void.gif"></td></tr><tr><td width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" src="./../images/void.gif"></td><td height="1" bgcolor="#ffffff"><pre>
373XML Configuration file URL: file:C:/path/to/context.xml
374</pre></td><td width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" src="./../images/void.gif"></td></tr><tr><td height="1" width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" src="./../images/void.gif"></td><td height="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" src="./../images/void.gif"></td><td height="1" width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" src="./../images/void.gif"></td></tr></table></div>
375</p>
376
377<p>Here is an example of installing an application using a Context
378configuration ".xml" file and a web application ".war" file located
379on the server (Tomcat running on Unix).
380<div align="left"><table border="0" cellpadding="0" cellspacing="4"><tr><td height="1" width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" src="./../images/void.gif"></td><td height="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" src="./../images/void.gif"></td><td height="1" width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" src="./../images/void.gif"></td></tr><tr><td width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" src="./../images/void.gif"></td><td height="1" bgcolor="#ffffff"><pre>
381XML Configuration file URL: file:/path/to/context.xml
382WAR or Directory URL: jar:file:/path/to/bar.war!/
383</pre></td><td width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" src="./../images/void.gif"></td></tr><tr><td height="1" width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" src="./../images/void.gif"></td><td height="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" src="./../images/void.gif"></td><td height="1" width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" src="./../images/void.gif"></td></tr></table></div>
384</p>
385
386</blockquote></td></tr></table>
387
388<table cellpadding="2" cellspacing="0" border="0"><tr><td bgcolor="#828DA6"><font face="arial,helvetica.sanserif" color="#ffffff"><a name="Upload a WAR file to install"><strong>Upload a WAR file to install</strong></a></font></td></tr><tr><td><blockquote>
389
390<p>Upload a WAR file from your local system and install it into the
391appBase for your Host. The name of the WAR file without the ".war"
392extension is used as the context path name.</p>
393
394<p>Use the <i>Browse</i> button to select a WAR file to upload to the
395server from your local desktop system.</p>
396
397<p>The .WAR file may include Tomcat specific deployment configuration, by
398including a Context configuration XML file in
399<code>/META-INF/context.xml</code>.</p>
400
401<p>Upload of a WAR file could fail for the following reasons:</p>
402<ul>
403<li><em>File uploaded must be a .war</em>
404    <blockquote>
405    <p>The upload install will only accept files which have the filename
406    extension of ".war".</p>
407    </blockquote></li>
408<li><em>War file already exists on server</em>
409    <blockquote>
410    <p>If a war file of the same name already exists in your Host's
411    appBase the upload will fail. Either undeploy the existing war file
412    from your Host's appBase or upload the new war file using a different
413    name.</p>
414    </blockquote></li>
415<li><em>File upload failed, no file</em>
416    <blockquote>
417    <p>The file upload failed, no file was received by the server.</p>
418    </blockquote></li>
419<li><em>Install Upload Failed, Exception:</em>
420    <blockquote>
421    <p>The war file upload or install failed with a Java Exception.
422    The exception message will be listed.</p>
423    </blockquote></li>
424</ul>
425
426</blockquote></td></tr></table>
427
428<table cellpadding="2" cellspacing="0" border="0"><tr><td bgcolor="#828DA6"><font face="arial,helvetica.sanserif" color="#ffffff"><a name="Deployment Notes"><strong>Deployment Notes</strong></a></font></td></tr><tr><td><blockquote>
429
430<p>If the Host is configured with unpackWARs=true and you install a war
431file, the war will be unpacked into a directory in your Host appBase
432directory.</p>
433
434<p>If the application war or directory is deployed in your Host appBase
435directory and either the Host is configured with autoDeploy=true or
436liveDeploy=true, the Context path must match the directory name or
437war file name without the ".war" extension.</p>
438
439<p>For security when untrusted users can manage web applications, the
440Host deployXML flag can be set to false.  This prevents untrusted users
441from installing web applications using a configuration XML file and
442also prevents them from installing application directories or ".war"
443files located outside of their Host appBase.</p>
444
445</blockquote></td></tr></table>
446
447<table cellpadding="2" cellspacing="0" border="0"><tr><td bgcolor="#828DA6"><font face="arial,helvetica.sanserif" color="#ffffff"><a name="Deploy Message"><strong>Deploy Message</strong></a></font></td></tr><tr><td><blockquote>
448
449<p>If deployment and startup is successful, you will receive a Message
450like this:</p>
451<div align="left"><table border="0" cellpadding="0" cellspacing="4"><tr><td height="1" width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" src="./../images/void.gif"></td><td height="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" src="./../images/void.gif"></td><td height="1" width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" src="./../images/void.gif"></td></tr><tr><td width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" src="./../images/void.gif"></td><td height="1" bgcolor="#ffffff"><pre>
452OK - Deployed application at context path /foo
453</pre></td><td width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" src="./../images/void.gif"></td></tr><tr><td height="1" width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" src="./../images/void.gif"></td><td height="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" src="./../images/void.gif"></td><td height="1" width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" src="./../images/void.gif"></td></tr></table></div>
454
455<p>Otherwise, the Message will start with <code>FAIL</code> and include an
456error message.  Possible causes for problems include:</p>
457<ul>
458<li><em>Application already exists at path /foo</em>
459    <blockquote>
460    <p>The context paths for all currently running web applications must be
461    unique.  Therefore, you must either undeploy the existing web
462    application using this context path, or choose a different context path
463    for the new one.</p>
464    </blockquote></li>
465<li><em>Document base does not exist or is not a readable directory</em>
466    <blockquote>
467    <p>The URL specified by the <i>WAR or Directory URL:</i> field must
468    identify a directory on this server that contains the "unpacked" version
469    of a web application, or the absolute URL of a web application archive
470    (WAR) file that contains this application.  Correct the value entered for
471    the <i>WAR or Directory URL:</i> field.</p>
472    </blockquote></li>
473<li><em>Encountered exception</em>
474    <blockquote>
475    <p>An exception was encountered trying to start the new web application.
476    Check the Tomcat 6 logs for the details, but likely explanations include
477    problems parsing your <code>/WEB-INF/web.xml</code> file, or missing
478    classes encountered when initializing application event listeners and
479    filters.</p>
480    </blockquote></li>
481<li><em>Invalid application URL was specified</em>
482    <blockquote>
483    <p>The URL for the <i>WAR or Directory URL:</i> field that you specified
484    was not valid.  Such URLs must start with <code>file:</code>, and URLs
485    for a WAR file must end in ".war".</p>
486    </blockquote></li>
487<li><em>Invalid context path was specified</em>
488    <blockquote>
489    <p>The context path must start with a slash character, unless you are
490    referencing the ROOT web application -- in which case the context path
491    must be a "/" string.</p>
492    </blockquote></li>
493<li><em>Context path must match the directory or WAR file name:</em>
494    <blockquote>
495    If the application war or directory is deployed in your Host appBase
496    directory and either the Host is configured with autoDeploy=true or
497    liveDeploy=true, the Context path must match the directory name or
498    war file name without the ".war" extension.
499    </blockquote></li>
500<li><em>Only web applications in the Host web application directory can
501     be deployed</em>
502     <blockquote>
503     If the Host deployXML flag is set to false this error will happen
504     if an attempt is made to install a web application directory or
505      ".war" file outside of the Host appBase directory.
506     </blockquote></li>
507</ul>
508
509</blockquote></td></tr></table>
510</blockquote></td></tr></table><table cellpadding="2" cellspacing="0" border="0"><tr><td bgcolor="#525D76"><font face="arial,helvetica.sanserif" color="#ffffff"><a name="Server Information"><strong>Server Information</strong></a></font></td></tr><tr><td><blockquote>
511
512<p>This section displays information about Tomcat, the operating system of
513the server Tomcat is hosted on, and the Java Virtual Machine Tomcat is
514running in.</p>
515
516</blockquote></td></tr></table></td></tr><!--FOOTER SEPARATOR--><tr><td colspan="2"><hr size="1" noshade></td></tr><!--PAGE FOOTER--><tr><td colspan="2"><div align="center"><font size="-1" color="#525D76"><em>
517        Copyright &copy; 1999-2008, Apache Software Foundation
518        </em></font></div></td></tr></table></body></html>
Note: See TracBrowser for help on using the repository browser.