container/webapps/docs/html-manager-howto.xml - tomcat55 - Git at Google

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

     &project;

     <properties>
         <author email="glenn@apache.org">Glenn L. Nielsen</author>
         <title>Tomcat Web Application Manager How To</title>
     </properties>

 <body>

 <section name="Introduction">

 <p>In many production environments it is very useful to have the capability
 to manage your web applications without having to shut down and restart
 Tomcat.  This document is for the HTML web interface to the web application
 <a href="manager-howto.html">manager</a>.</p>

 <p>The interface is divided into five sections:
 <ul>
   <li><strong>Message</strong> - Displays success and failure messages.</li>
   <li><strong>Manager</strong> - General manager operations like list and
       help.</li>
   <li><strong>Applications</strong> - List of web applications and
       commands.</li>
   <li><strong>Deploy</strong> - Deploying web applications.</li>
   <li><strong>Server Information</strong> - Information about the Tomcat
       server.</li>
 </ul>
 </p>

 </section>

 <section name="Message">

 <p>
 Displays information about the success or failure of the last web application
 manager command you performed. If it succeeded <strong>OK</strong> is displayed
 and may be followed by a success message. If it failed <strong>FAIL</strong>
 is displayed followed by an error message. Common failure messages are
 documented below for each command.  The complete list of failure messages for
 each command can be found in the <a href="manager-howto.html">manager</a> web
 application documentation.
 </p>

 </section>

 <section name="Manager">

 <p>The Manager section has three links:
 <ul>
   <li><strong>List Applications</strong> - Redisplay a list of web
       applications.</li>
   <li><strong>HTML Manager Help</strong> - A link to this document.</li>
   <li><strong>Manager Help</strong> - A link to the comprehensive Manager
       App HOW TO.</li>
 </ul>
 </p>

 </section>

 <section name="Applications">

 <p>The Applications section lists information about all the installed web
 applications and provides links for managing them. For each web application
 the following is displayed:
 <ul>
   <li><strong>Path</strong> - The web applicaton context path.</li>
   <li><strong>Display Name</strong> - The display name for the web application
       if it has one configured in its "web.xml" file.</li>
   <li><strong>Running</strong> - Whether the web application is running and
       available (true), or not running and unavailable (false).</li>
   <li><strong>Sessions</strong> - The number of active sessions for remote
       users of this web application.  The number of sessions is a link which
       when submitted displays more details about session usage by the web
       application in the Message box.</li>
   <li><strong>Commands</strong> - Lists all commands which can be performed on
       the web application. Only those commands which can be performed will be
       listed as a link which can be submitted. No commands can be performed on
       the manager web application itself. The following commands can be
       performed:
       <ul>
         <li><strong>Start</strong> - Start a web application which had been
             stopped.</li>
         <li><strong>Stop</strong> - Stop a web application which is currently
             running and make it unavailable.</li>
         <li><strong>Reload</strong> - Reload the web application so that new
             ".jar" files in <code>/WEB-INF/lib/</code> or new classes in
             <code>/WEB-INF/classes/</code> can be used.</li>
         <li><strong>Undeploy</strong> - Stop and then remove this web
              application from the server.</li>
       </ul>
   </li>
 </ul>
 </p>

 <subsection name="Start">

 <p>Signal a stopped application to restart, and make itself available again.
 Stopping and starting is useful, for example, if the database required by
 your application becomes temporarily unavailable.  It is usually better to
 stop the web application that relies on this database rather than letting
 users continuously encounter database exceptions.</p>

 <p>If this command succeeds, you will see a Message like this:</p>
 <source>
 OK - Started application at context path /examples
 </source>

 <p>Otherwise, the Message will start with <code>FAIL</code> and include an
 error message.  Possible causes for problems include:
 <ul>
 <li><em>Encountered exception</em>
     <blockquote>
     <p>An exception was encountered trying to start the web application.
     Check the Tomcat 5 logs for the details.</p>
     </blockquote></li>
 <li><em>Invalid context path was specified</em>
     <blockquote>
     <p>The context path must start with a slash character, unless you are
     referencing the ROOT web application -- in which case the context path
     must be a zero-length string.</p>
     </blockquote></li>
 <li><em>No context exists for path /foo</em>
     <blockquote>
     <p>There is no deployed application on the context path
     that you specified.</p>
     </blockquote></li>
 <li><em>No context path was specified</em>
     <blockquote>
     The <code>path</code> parameter is required.
     </blockquote></li>
 </ul>
 </p>

 </subsection>

 <subsection name="Stop">

 <p>Signal an existing application to make itself unavailable, but leave it
 deployed.  Any request that comes in while an application is
 stopped will see an HTTP error 404, and this application will show as
 "stopped" on a list applications command.</p>

 <p>If this command succeeds, you will see a Message like this:</p>
 <source>
 OK - Stopped application at context path /examples
 </source>

 <p>Otherwise, the Message will start with <code>FAIL</code> and include an
 error message.  Possible causes for problems include:
 <ul>
 <li><em>Encountered exception</em>
     <blockquote>
     <p>An exception was encountered trying to stop the web application.
     Check the Tomcat 5 logs for the details.</p>
     </blockquote></li>
 <li><em>Invalid context path was specified</em>
     <blockquote>
     <p>The context path must start with a slash character, unless you are
     referencing the ROOT web application -- in which case the context path
     must be a zero-length string.</p>
     </blockquote></li>
 <li><em>No context exists for path /foo</em>
     <blockquote>
     <p>There is no deployed application on the context path
     that you specified.</p>
     </blockquote></li>
 <li><em>No context path was specified</em>
     <blockquote>
     The <code>path</code> parameter is required.
     </blockquote></li>
 </ul>
 </p>

 </subsection>

 <subsection name="Reload">

 <p>Signal an existing application to shut itself down and reload.  This can
 be useful when the web application context is not reloadable and you have
 updated classes or property files in the <code>/WEB-INF/classes</code>
 directory or when you have added or updated jar files in the
 <code>/WEB-INF/lib</code> directory.
 </p>
 <p><strong>NOTE:</strong> The <code>/WEB-INF/web.xml</code>
 web application configuration file is not checked on a reload;
 the previous web.xml configuration is used.
 If you have made changes to your web.xml file you must stop
 then start the web application.
 </p>

 <p>If this command succeeds, you will see a Message like this:</p>
 <source>
 OK - Reloaded application at context path /examples
 </source>

 <p>Otherwise, the Message will start with <code>FAIL</code> and include an
 error message.  Possible causes for problems include:
 <ul>
 <li><em>Encountered exception</em>
     <blockquote>
     <p>An exception was encountered trying to restart the web application.
     Check the Tomcat 5 logs for the details.</p>
     </blockquote></li>
 <li><em>Invalid context path was specified</em>
     <blockquote>
     <p>The context path must start with a slash character, unless you are
     referencing the ROOT web application -- in which case the context path
     must be a zero-length string.</p>
     </blockquote></li>
 <li><em>No context exists for path /foo</em>
     <blockquote>
     <p>There is no deployed application on the context path
     that you specified.</p>
     </blockquote></li>
 <li><em>No context path was specified</em>
     <blockquote>
     The <code>path</code> parameter is required.
     </blockquote></li>
 <li><em>Reload not supported on WAR deployed at path /foo</em>
     <blockquote>
     Currently, application reloading (to pick up changes to the classes or
     <code>web.xml</code> file) is not supported when a web application is
     installed directly from a WAR file, which happens when the host is
     configured to not unpack WAR files. As it only works when the web
     application is installed from an unpacked directory, if you are using
     a WAR file, you should <code>undeploy</code> and then <code>deploy</code>
     the application again to pick up your changes.
     </blockquote></li>
 </ul>
 </p>

 </subsection>

 <subsection name="Undeploy">

 <p><strong><font color="red">WARNING</font> - This command will delete the
 contents of the web application directory and/or ".war" file if it exists within
 the <code>appBase</code> directory (typically "webapps") for this virtual host
 </strong>.  The web application temporary work directory is also deleted.  If
 you simply want to take an application out of service, you should use the
 <code>/stop</code> command instead.</p>

 <p>Signal an existing application to gracefully shut itself down, and then
 remove it from Tomcat (which also makes this context path available for
 reuse later).  This command is the logical opposite of the
 <code>/deploy</code> Ant command, and the related deploy features available
 in the HTML manager.</p>

 <p>If this command succeeds, you will see a Message like this:</p>
 <source>
 OK - Undeployed application at context path /examples
 </source>

 <p>Otherwise, the Message will start with <code>FAIL</code> and include an
 error message.  Possible causes for problems include:
 <ul>
 <li><em>Encountered exception</em>
     <blockquote>
     <p>An exception was encountered trying to undeploy the web application.
     Check the Tomcat logs for the details.</p>
     </blockquote></li>
 <li><em>Invalid context path was specified</em>
     <blockquote>
     <p>The context path must start with a slash character, unless you are
     referencing the ROOT web application -- in which case the context path
     must be a zero-length string.</p>
     </blockquote></li>
 <li><em>No context exists for path /foo</em>
     <blockquote>
     <p>There is no deployed application on the context path
     that you specified.</p>
     </blockquote></li>
 <li><em>No context path was specified</em>
     <blockquote>
     The <code>path</code> parameter is required.
     </blockquote></li>
 </ul>
 </p>

 </subsection>

 </section>

 <section name="Deploy">

 <p>Web applications can be deployed using files or directories located
 on the Tomcat server or you can upload a web application archive (WAR)
 file to the server.</p>

 <p>To install an application, fill in the appropriate fields for the type
 of install you want to do and then submit it using the <i>Install</i>
 button.</p>

 <subsection name="Deploy directory or WAR file located on server">

 <p>Deploy and start a new web application, attached to the specified <i>Context
 Path:</i> (which must not be in use by any other web application).
 This command is the logical opposite of the <em>Undeploy</em> command.</p>

 <p>There are a number of different ways the deploy command can be used.</p>

 <h3>Deploy a Directory or WAR by URL</h3>

 <p>Install a web application directory or ".war" file located on the Tomcat
 server. If no <i>Context Path</i> is specified, the directory name or the
 war file name without the ".war" extension is used as the path. The
 <i>WAR or Directory URL</i> specifies a URL (including the <code>file:</code>
 scheme) for either a directory or a web application archive (WAR) file. The
 supported syntax for a URL referring to a WAR file is described on the Javadocs
 page for the <code>java.net.JarURLConnection</code> class.  Use only URLs that
 refer to the entire WAR file.</p>

 <p>In this example the web application located in the directory
 <code>C:\path\to\foo</code> on the Tomcat server (running on Windows)
 is deployed as the web application context named <code>/footoo</code>.
 <source>
 Context Path: /footoo
 WAR or Directory URL: file:C:/path/to/foo
 </source>
 </p>

 <p>In this example the ".war" file <code>/path/to/bar.war</code> on the
 Tomcat server (running on Unix) is deployed as the web application
 context named <code>/bar</code>. Notice that there is no <code>path</code>
 parameter so the context path defaults to the name of the web application
 archive file without the ".war" extension.
 <source>
 WAR or Directory URL: jar:file:/path/to/bar.war!/
 </source>
 </p>

 <h3>Deploy a Directory or War from the Host appBase</h3>

 <p>Install a web application directory or ".war" file located in your Host
 appBase directory. If no <i>Context Path</i> is specified the directory name
 or the war file name without the ".war" extension is used as the path.</p>

 <p>In this example the web application located in a subdirectory named
 <code>foo</code> in the Host appBase directory of the Tomcat server is
 deployed as the web application context named <code>/foo</code>. Notice
 that there is no <code>path</code> parameter so the context path defaults
 to the name of the web application directory.
 <source>
 WAR or Directory URL: foo
 </source>
 </p>

 <p>In this example the ".war" file <code>bar.war</code> located in your
 Host appBase directory on the Tomcat server is deployed as the web
 application context named <code>/bartoo</code>.
 <source>
 Context Path: /bartoo
 WAR or Directory URL: bar.war
 </source>
 </p>

 <h3>Deploy using a Context configuration ".xml" file</h3>

 <p>If the Host deployXML flag is set to true, you can install a web
 application using a Context configuration ".xml" file and an optional
 ".war" file or web application directory. The <i>Context Path</i>
 is not used when installing a web application using a context ".xml"
 configuration file.</p>

 <p>A Context configuration ".xml" file can contain valid XML for a
 web application Context just as if it were configured in your
 Tomcat <code>server.xml</code> configuration file. Here is an
 example for Tomcat running on Windows:
 <source>
 &lt;Context path="/foobar" docBase="C:\path\to\application\foobar"
          debug="0"&gt;

   &lt;!-- Link to the user database we will get roles from --&gt;
   &lt;ResourceLink name="users" global="UserDatabase"
                 type="org.apache.catalina.UserDatabase"/&gt;

 &lt;/Context&gt;
 </source>
 </p>

 <p>Use of the <i>WAR or Directory URL</i> is optional. When used
 to select a web application ".war" file or directory it overrides any
 docBase configured in the context configuration ".xml" file.</p>

 <p>Here is an example of installing an application using a Context
 configuration ".xml" file for Tomcat running on Windows.
 <source>
 XML Configuration file URL: file:C:/path/to/context.xml
 </source>
 </p>

 <p>Here is an example of installing an application using a Context
 configuration ".xml" file and a web application ".war" file located
 on the server (Tomcat running on Unix).
 <source>
 XML Configuration file URL: file:/path/to/context.xml
 WAR or Directory URL: jar:file:/path/to/bar.war!/
 </source>
 </p>

 </subsection>

 <subsection name="Upload a WAR file to install">

 <p>Upload a WAR file from your local system and install it into the
 appBase for your Host. The name of the WAR file without the ".war"
 extension is used as the context path name.</p>

 <p>Use the <i>Browse</i> button to select a WAR file to upload to the
 server from your local desktop system.</p>

 <p>The .WAR file may include Tomcat specific deployment configuration, by
 including a Context configuration XML file in
 <code>/META-INF/context.xml</code>.</p>

 <p>Upload of a WAR file could fail for the following reasons:</p>
 <ul>
 <li><em>File uploaded must be a .war</em>
     <blockquote>
     <p>The upload install will only accept files which have the filename
     extension of ".war".</p>
     </blockquote></li>
 <li><em>War file already exists on server</em>
     <blockquote>
     <p>If a war file of the same name already exists in your Host's
     appBase the upload will fail. Either undeploy the existing war file
     from your Host's appBase or upload the new war file using a different
     name.</p>
     </blockquote></li>
 <li><em>File upload failed, no file</em>
     <blockquote>
     <p>The file upload failed, no file was received by the server.</p>
     </blockquote></li>
 <li><em>Install Upload Failed, Exception:</em>
     <blockquote>
     <p>The war file upload or install failed with a Java Exception.
     The exception message will be listed.</p>
     </blockquote></li>
 </ul>

 </subsection>

 <subsection name="Deployment Notes">

 <p>If the Host is configured with unpackWARs=true and you install a war
 file, the war will be unpacked into a directory in your Host appBase
 directory.</p>

 <p>If the application war or directory is deployed in your Host appBase
 directory and either the Host is configured with autoDeploy=true or
 liveDeploy=true, the Context path must match the directory name or
 war file name without the ".war" extension.</p>

 <p>For security when untrusted users can manage web applications, the
 Host deployXML flag can be set to false.  This prevents untrusted users
 from installing web applications using a configuration XML file and
 also prevents them from installing application directories or ".war"
 files located outside of their Host appBase.</p>

 </subsection>

 <subsection name="Deploy Message">

 <p>If deployment and startup is successful, you will receive a Message
 like this:</p>
 <source>
 OK - Deployed application at context path /foo
 </source>

 <p>Otherwise, the Message will start with <code>FAIL</code> and include an
 error message.  Possible causes for problems include:</p>
 <ul>
 <li><em>Application already exists at path /foo</em>
     <blockquote>
     <p>The context paths for all currently running web applications must be
     unique.  Therefore, you must either undeploy the existing web
     application using this context path, or choose a different context path
     for the new one.</p>
     </blockquote></li>
 <li><em>Document base does not exist or is not a readable directory</em>
     <blockquote>
     <p>The URL specified by the <i>WAR or Directory URL:</i> field must
     identify a directory on this server that contains the "unpacked" version
     of a web application, or the absolute URL of a web application archive
     (WAR) file that contains this application.  Correct the value entered for
     the <i>WAR or Directory URL:</i> field.</p>
     </blockquote></li>
 <li><em>Encountered exception</em>
     <blockquote>
     <p>An exception was encountered trying to start the new web application.
     Check the Tomcat 5 logs for the details, but likely explanations include
     problems parsing your <code>/WEB-INF/web.xml</code> file, or missing
     classes encountered when initializing application event listeners and
     filters.</p>
     </blockquote></li>
 <li><em>Invalid application URL was specified</em>
     <blockquote>
     <p>The URL for the <i>WAR or Directory URL:</i> field that you specified
     was not valid.  Such URLs must start with <code>file:</code>, and URLs
     for a WAR file must end in ".war".</p>
     </blockquote></li>
 <li><em>Invalid context path was specified</em>
     <blockquote>
     <p>The context path must start with a slash character, unless you are
     referencing the ROOT web application -- in which case the context path
     must be a "/" string.</p>
     </blockquote></li>
 <li><em>Context path must match the directory or WAR file name:</em>
     <blockquote>
     If the application war or directory is deployed in your Host appBase
     directory and either the Host is configured with autoDeploy=true or
     liveDeploy=true, the Context path must match the directory name or
     war file name without the ".war" extension.
     </blockquote></li>
 <li><em>Only web applications in the Host web application directory can
      be deployed</em>
      <blockquote>
      If the Host deployXML flag is set to false this error will happen
      if an attempt is made to install a web application directory or
       ".war" file outside of the Host appBase directory.
      </blockquote></li>
 </ul>

 </subsection>
 </section>

 <section name="Server Information">

 <p>This section displays information about Tomcat, the operating system of
 the server Tomcat is hosted on, and the Java Virtual Machine Tomcat is
 running in.</p>

 </section>

 </body>

 </document>
	<?xml version="1.0"?>
	<!DOCTYPE document [
	<!ENTITY project SYSTEM "project.xml">
	]>
	<document url="html-manager-howto.html">

	&project;

	<properties>
	<author email="glenn@apache.org">Glenn L. Nielsen</author>
	<title>Tomcat Web Application Manager How To</title>
	</properties>

	<body>

	<section name="Introduction">

	<p>In many production environments it is very useful to have the capability
	to manage your web applications without having to shut down and restart
	Tomcat. This document is for the HTML web interface to the web application
	<a href="manager-howto.html">manager</a>.</p>

	<p>The interface is divided into five sections:
	<ul>
	<li><strong>Message</strong> - Displays success and failure messages.</li>
	<li><strong>Manager</strong> - General manager operations like list and
	help.</li>
	<li><strong>Applications</strong> - List of web applications and
	commands.</li>
	<li><strong>Deploy</strong> - Deploying web applications.</li>
	<li><strong>Server Information</strong> - Information about the Tomcat
	server.</li>
	</ul>
	</p>

	</section>

	<section name="Message">

	<p>
	Displays information about the success or failure of the last web application
	manager command you performed. If it succeeded <strong>OK</strong> is displayed
	and may be followed by a success message. If it failed <strong>FAIL</strong>
	is displayed followed by an error message. Common failure messages are
	documented below for each command. The complete list of failure messages for
	each command can be found in the <a href="manager-howto.html">manager</a> web
	application documentation.
	</p>

	</section>

	<section name="Manager">

	<p>The Manager section has three links:
	<ul>
	<li><strong>List Applications</strong> - Redisplay a list of web
	applications.</li>
	<li><strong>HTML Manager Help</strong> - A link to this document.</li>
	<li><strong>Manager Help</strong> - A link to the comprehensive Manager
	App HOW TO.</li>
	</ul>
	</p>

	</section>

	<section name="Applications">

	<p>The Applications section lists information about all the installed web
	applications and provides links for managing them. For each web application
	the following is displayed:
	<ul>
	<li><strong>Path</strong> - The web applicaton context path.</li>
	<li><strong>Display Name</strong> - The display name for the web application
	if it has one configured in its "web.xml" file.</li>
	<li><strong>Running</strong> - Whether the web application is running and
	available (true), or not running and unavailable (false).</li>
	<li><strong>Sessions</strong> - The number of active sessions for remote
	users of this web application. The number of sessions is a link which
	when submitted displays more details about session usage by the web
	application in the Message box.</li>
	<li><strong>Commands</strong> - Lists all commands which can be performed on
	the web application. Only those commands which can be performed will be
	listed as a link which can be submitted. No commands can be performed on
	the manager web application itself. The following commands can be
	performed:
	<ul>
	<li><strong>Start</strong> - Start a web application which had been
	stopped.</li>
	<li><strong>Stop</strong> - Stop a web application which is currently
	running and make it unavailable.</li>
	<li><strong>Reload</strong> - Reload the web application so that new
	".jar" files in <code>/WEB-INF/lib/</code> or new classes in
	<code>/WEB-INF/classes/</code> can be used.</li>
	<li><strong>Undeploy</strong> - Stop and then remove this web
	application from the server.</li>
	</ul>
	</li>
	</ul>
	</p>

	<subsection name="Start">

	<p>Signal a stopped application to restart, and make itself available again.
	Stopping and starting is useful, for example, if the database required by
	your application becomes temporarily unavailable. It is usually better to
	stop the web application that relies on this database rather than letting
	users continuously encounter database exceptions.</p>

	<p>If this command succeeds, you will see a Message like this:</p>
	<source>
	OK - Started application at context path /examples
	</source>

	<p>Otherwise, the Message will start with <code>FAIL</code> and include an
	error message. Possible causes for problems include:
	<ul>
	<li><em>Encountered exception</em>
	<blockquote>
	<p>An exception was encountered trying to start the web application.
	Check the Tomcat 5 logs for the details.</p>
	</blockquote></li>
	<li><em>Invalid context path was specified</em>
	<blockquote>
	<p>The context path must start with a slash character, unless you are
	referencing the ROOT web application -- in which case the context path
	must be a zero-length string.</p>
	</blockquote></li>
	<li><em>No context exists for path /foo</em>
	<blockquote>
	<p>There is no deployed application on the context path
	that you specified.</p>
	</blockquote></li>
	<li><em>No context path was specified</em>
	<blockquote>
	The <code>path</code> parameter is required.
	</blockquote></li>
	</ul>
	</p>

	</subsection>

	<subsection name="Stop">

	<p>Signal an existing application to make itself unavailable, but leave it
	deployed. Any request that comes in while an application is
	stopped will see an HTTP error 404, and this application will show as
	"stopped" on a list applications command.</p>

	<p>If this command succeeds, you will see a Message like this:</p>
	<source>
	OK - Stopped application at context path /examples
	</source>

	<p>Otherwise, the Message will start with <code>FAIL</code> and include an
	error message. Possible causes for problems include:
	<ul>
	<li><em>Encountered exception</em>
	<blockquote>
	<p>An exception was encountered trying to stop the web application.
	Check the Tomcat 5 logs for the details.</p>
	</blockquote></li>
	<li><em>Invalid context path was specified</em>
	<blockquote>
	<p>The context path must start with a slash character, unless you are
	referencing the ROOT web application -- in which case the context path
	must be a zero-length string.</p>
	</blockquote></li>
	<li><em>No context exists for path /foo</em>
	<blockquote>
	<p>There is no deployed application on the context path
	that you specified.</p>
	</blockquote></li>
	<li><em>No context path was specified</em>
	<blockquote>
	The <code>path</code> parameter is required.
	</blockquote></li>
	</ul>
	</p>

	</subsection>

	<subsection name="Reload">

	<p>Signal an existing application to shut itself down and reload. This can
	be useful when the web application context is not reloadable and you have
	updated classes or property files in the <code>/WEB-INF/classes</code>
	directory or when you have added or updated jar files in the
	<code>/WEB-INF/lib</code> directory.
	</p>
	<p><strong>NOTE:</strong> The <code>/WEB-INF/web.xml</code>
	web application configuration file is not checked on a reload;
	the previous web.xml configuration is used.
	If you have made changes to your web.xml file you must stop
	then start the web application.
	</p>

	<p>If this command succeeds, you will see a Message like this:</p>
	<source>
	OK - Reloaded application at context path /examples
	</source>

	<p>Otherwise, the Message will start with <code>FAIL</code> and include an
	error message. Possible causes for problems include:
	<ul>
	<li><em>Encountered exception</em>
	<blockquote>
	<p>An exception was encountered trying to restart the web application.
	Check the Tomcat 5 logs for the details.</p>
	</blockquote></li>
	<li><em>Invalid context path was specified</em>
	<blockquote>
	<p>The context path must start with a slash character, unless you are
	referencing the ROOT web application -- in which case the context path
	must be a zero-length string.</p>
	</blockquote></li>
	<li><em>No context exists for path /foo</em>
	<blockquote>
	<p>There is no deployed application on the context path
	that you specified.</p>
	</blockquote></li>
	<li><em>No context path was specified</em>
	<blockquote>
	The <code>path</code> parameter is required.
	</blockquote></li>
	<li><em>Reload not supported on WAR deployed at path /foo</em>
	<blockquote>
	Currently, application reloading (to pick up changes to the classes or
	<code>web.xml</code> file) is not supported when a web application is
	installed directly from a WAR file, which happens when the host is
	configured to not unpack WAR files. As it only works when the web
	application is installed from an unpacked directory, if you are using
	a WAR file, you should <code>undeploy</code> and then <code>deploy</code>
	the application again to pick up your changes.
	</blockquote></li>
	</ul>
	</p>

	</subsection>

	<subsection name="Undeploy">

	<p><strong><font color="red">WARNING</font> - This command will delete the
	contents of the web application directory and/or ".war" file if it exists within
	the <code>appBase</code> directory (typically "webapps") for this virtual host
	</strong>. The web application temporary work directory is also deleted. If
	you simply want to take an application out of service, you should use the
	<code>/stop</code> command instead.</p>

	<p>Signal an existing application to gracefully shut itself down, and then
	remove it from Tomcat (which also makes this context path available for
	reuse later). This command is the logical opposite of the
	<code>/deploy</code> Ant command, and the related deploy features available
	in the HTML manager.</p>

	<p>If this command succeeds, you will see a Message like this:</p>
	<source>
	OK - Undeployed application at context path /examples
	</source>

	<p>Otherwise, the Message will start with <code>FAIL</code> and include an
	error message. Possible causes for problems include:
	<ul>
	<li><em>Encountered exception</em>
	<blockquote>
	<p>An exception was encountered trying to undeploy the web application.
	Check the Tomcat logs for the details.</p>
	</blockquote></li>
	<li><em>Invalid context path was specified</em>
	<blockquote>
	<p>The context path must start with a slash character, unless you are
	referencing the ROOT web application -- in which case the context path
	must be a zero-length string.</p>
	</blockquote></li>
	<li><em>No context exists for path /foo</em>
	<blockquote>
	<p>There is no deployed application on the context path
	that you specified.</p>
	</blockquote></li>
	<li><em>No context path was specified</em>
	<blockquote>
	The <code>path</code> parameter is required.
	</blockquote></li>
	</ul>
	</p>

	</subsection>

	</section>

	<section name="Deploy">

	<p>Web applications can be deployed using files or directories located
	on the Tomcat server or you can upload a web application archive (WAR)
	file to the server.</p>

	<p>To install an application, fill in the appropriate fields for the type
	of install you want to do and then submit it using the <i>Install</i>
	button.</p>

	<subsection name="Deploy directory or WAR file located on server">

	<p>Deploy and start a new web application, attached to the specified <i>Context
	Path:</i> (which must not be in use by any other web application).
	This command is the logical opposite of the <em>Undeploy</em> command.</p>

	<p>There are a number of different ways the deploy command can be used.</p>

	<h3>Deploy a Directory or WAR by URL</h3>

	<p>Install a web application directory or ".war" file located on the Tomcat
	server. If no <i>Context Path</i> is specified, the directory name or the
	war file name without the ".war" extension is used as the path. The
	<i>WAR or Directory URL</i> specifies a URL (including the <code>file:</code>
	scheme) for either a directory or a web application archive (WAR) file. The
	supported syntax for a URL referring to a WAR file is described on the Javadocs
	page for the <code>java.net.JarURLConnection</code> class. Use only URLs that
	refer to the entire WAR file.</p>

	<p>In this example the web application located in the directory
	<code>C:\path\to\foo</code> on the Tomcat server (running on Windows)
	is deployed as the web application context named <code>/footoo</code>.
	<source>
	Context Path: /footoo
	WAR or Directory URL: file:C:/path/to/foo
	</source>
	</p>

	<p>In this example the ".war" file <code>/path/to/bar.war</code> on the
	Tomcat server (running on Unix) is deployed as the web application
	context named <code>/bar</code>. Notice that there is no <code>path</code>
	parameter so the context path defaults to the name of the web application
	archive file without the ".war" extension.
	<source>
	WAR or Directory URL: jar:file:/path/to/bar.war!/
	</source>
	</p>

	<h3>Deploy a Directory or War from the Host appBase</h3>

	<p>Install a web application directory or ".war" file located in your Host
	appBase directory. If no <i>Context Path</i> is specified the directory name
	or the war file name without the ".war" extension is used as the path.</p>

	<p>In this example the web application located in a subdirectory named
	<code>foo</code> in the Host appBase directory of the Tomcat server is
	deployed as the web application context named <code>/foo</code>. Notice
	that there is no <code>path</code> parameter so the context path defaults
	to the name of the web application directory.
	<source>
	WAR or Directory URL: foo
	</source>
	</p>

	<p>In this example the ".war" file <code>bar.war</code> located in your
	Host appBase directory on the Tomcat server is deployed as the web
	application context named <code>/bartoo</code>.
	<source>
	Context Path: /bartoo
	WAR or Directory URL: bar.war
	</source>
	</p>

	<h3>Deploy using a Context configuration ".xml" file</h3>

	<p>If the Host deployXML flag is set to true, you can install a web
	application using a Context configuration ".xml" file and an optional
	".war" file or web application directory. The <i>Context Path</i>
	is not used when installing a web application using a context ".xml"
	configuration file.</p>

	<p>A Context configuration ".xml" file can contain valid XML for a
	web application Context just as if it were configured in your
	Tomcat <code>server.xml</code> configuration file. Here is an
	example for Tomcat running on Windows:
	<source>
	<Context path="/foobar" docBase="C:\path\to\application\foobar"
	debug="0">

	<!-- Link to the user database we will get roles from -->
	<ResourceLink name="users" global="UserDatabase"
	type="org.apache.catalina.UserDatabase"/>

	</Context>
	</source>
	</p>

	<p>Use of the <i>WAR or Directory URL</i> is optional. When used
	to select a web application ".war" file or directory it overrides any
	docBase configured in the context configuration ".xml" file.</p>

	<p>Here is an example of installing an application using a Context
	configuration ".xml" file for Tomcat running on Windows.
	<source>
	XML Configuration file URL: file:C:/path/to/context.xml
	</source>
	</p>

	<p>Here is an example of installing an application using a Context
	configuration ".xml" file and a web application ".war" file located
	on the server (Tomcat running on Unix).
	<source>
	XML Configuration file URL: file:/path/to/context.xml
	WAR or Directory URL: jar:file:/path/to/bar.war!/
	</source>
	</p>

	</subsection>

	<subsection name="Upload a WAR file to install">

	<p>Upload a WAR file from your local system and install it into the
	appBase for your Host. The name of the WAR file without the ".war"
	extension is used as the context path name.</p>

	<p>Use the <i>Browse</i> button to select a WAR file to upload to the
	server from your local desktop system.</p>

	<p>The .WAR file may include Tomcat specific deployment configuration, by
	including a Context configuration XML file in
	<code>/META-INF/context.xml</code>.</p>

	<p>Upload of a WAR file could fail for the following reasons:</p>
	<ul>
	<li><em>File uploaded must be a .war</em>
	<blockquote>
	<p>The upload install will only accept files which have the filename
	extension of ".war".</p>
	</blockquote></li>
	<li><em>War file already exists on server</em>
	<blockquote>
	<p>If a war file of the same name already exists in your Host's
	appBase the upload will fail. Either undeploy the existing war file
	from your Host's appBase or upload the new war file using a different
	name.</p>
	</blockquote></li>
	<li><em>File upload failed, no file</em>
	<blockquote>
	<p>The file upload failed, no file was received by the server.</p>
	</blockquote></li>
	<li><em>Install Upload Failed, Exception:</em>
	<blockquote>
	<p>The war file upload or install failed with a Java Exception.
	The exception message will be listed.</p>
	</blockquote></li>
	</ul>

	</subsection>

	<subsection name="Deployment Notes">

	<p>If the Host is configured with unpackWARs=true and you install a war
	file, the war will be unpacked into a directory in your Host appBase
	directory.</p>

	<p>If the application war or directory is deployed in your Host appBase
	directory and either the Host is configured with autoDeploy=true or
	liveDeploy=true, the Context path must match the directory name or
	war file name without the ".war" extension.</p>

	<p>For security when untrusted users can manage web applications, the
	Host deployXML flag can be set to false. This prevents untrusted users
	from installing web applications using a configuration XML file and
	also prevents them from installing application directories or ".war"
	files located outside of their Host appBase.</p>

	</subsection>

	<subsection name="Deploy Message">

	<p>If deployment and startup is successful, you will receive a Message
	like this:</p>
	<source>
	OK - Deployed application at context path /foo
	</source>

	<p>Otherwise, the Message will start with <code>FAIL</code> and include an
	error message. Possible causes for problems include:</p>
	<ul>
	<li><em>Application already exists at path /foo</em>
	<blockquote>
	<p>The context paths for all currently running web applications must be
	unique. Therefore, you must either undeploy the existing web
	application using this context path, or choose a different context path
	for the new one.</p>
	</blockquote></li>
	<li><em>Document base does not exist or is not a readable directory</em>
	<blockquote>
	<p>The URL specified by the <i>WAR or Directory URL:</i> field must
	identify a directory on this server that contains the "unpacked" version
	of a web application, or the absolute URL of a web application archive
	(WAR) file that contains this application. Correct the value entered for
	the <i>WAR or Directory URL:</i> field.</p>
	</blockquote></li>
	<li><em>Encountered exception</em>
	<blockquote>
	<p>An exception was encountered trying to start the new web application.
	Check the Tomcat 5 logs for the details, but likely explanations include
	problems parsing your <code>/WEB-INF/web.xml</code> file, or missing
	classes encountered when initializing application event listeners and
	filters.</p>
	</blockquote></li>
	<li><em>Invalid application URL was specified</em>
	<blockquote>
	<p>The URL for the <i>WAR or Directory URL:</i> field that you specified
	was not valid. Such URLs must start with <code>file:</code>, and URLs
	for a WAR file must end in ".war".</p>
	</blockquote></li>
	<li><em>Invalid context path was specified</em>
	<blockquote>
	<p>The context path must start with a slash character, unless you are
	referencing the ROOT web application -- in which case the context path
	must be a "/" string.</p>
	</blockquote></li>
	<li><em>Context path must match the directory or WAR file name:</em>
	<blockquote>
	If the application war or directory is deployed in your Host appBase
	directory and either the Host is configured with autoDeploy=true or
	liveDeploy=true, the Context path must match the directory name or
	war file name without the ".war" extension.
	</blockquote></li>
	<li><em>Only web applications in the Host web application directory can
	be deployed</em>
	<blockquote>
	If the Host deployXML flag is set to false this error will happen
	if an attempt is made to install a web application directory or
	".war" file outside of the Host appBase directory.
	</blockquote></li>
	</ul>

	</subsection>
	</section>

	<section name="Server Information">

	<p>This section displays information about Tomcat, the operating system of
	the server Tomcat is hosted on, and the Java Virtual Machine Tomcat is
	running in.</p>

	</section>

	</body>

	</document>