Details | Last modification | View Log | RSS feed
| Rev | Author | Line No. | Line |
|---|---|---|---|
| 771 | blopes | 1 | <!DOCTYPE html SYSTEM "about:legacy-compat"> |
| 2 | <html lang="en"><head><META http-equiv="Content-Type" content="text/html; charset=UTF-8"><link href="./images/docs-stylesheet.css" rel="stylesheet" type="text/css"><title>Apache Tomcat 9 (9.0.112) - Tomcat Web Application Manager How To</title></head><body><div id="wrapper"><header><div id="header"><div><div><div class="logo noPrint"><a href="https://tomcat.apache.org/"><img alt="Tomcat Home" src="./images/tomcat.png"></a></div><div style="height: 1px;"></div><div class="asfLogo noPrint"><a href="https://www.apache.org/" target="_blank"><img src="./images/asf-logo.svg" alt="The Apache Software Foundation" style="width: 266px; height: 83px;"></a></div><h1>Apache Tomcat 9</h1><div class="versionInfo"> |
||
| 3 | Version 9.0.112, |
||
| 4 | <time datetime="2025-11-06">Nov 6 2025</time></div><div style="height: 1px;"></div><div style="clear: left;"></div></div></div></div></header><div id="middle"><div><div id="mainLeft" class="noprint"><div><nav><div><h2>Links</h2><ul><li><a href="index.html">Docs Home</a></li><li><a href="https://cwiki.apache.org/confluence/display/TOMCAT/FAQ">FAQ</a></li></ul></div><div><h2>User Guide</h2><ul><li><a href="introduction.html">1) Introduction</a></li><li><a href="setup.html">2) Setup</a></li><li><a href="appdev/index.html">3) First webapp</a></li><li><a href="deployer-howto.html">4) Deployer</a></li><li><a href="manager-howto.html">5) Manager</a></li><li><a href="host-manager-howto.html">6) Host Manager</a></li><li><a href="realm-howto.html">7) Realms and AAA</a></li><li><a href="security-manager-howto.html">8) Security Manager</a></li><li><a href="jndi-resources-howto.html">9) JNDI Resources</a></li><li><a href="jndi-datasource-examples-howto.html">10) JDBC DataSources</a></li><li><a href="class-loader-howto.html">11) Classloading</a></li><li><a href="jasper-howto.html">12) JSPs</a></li><li><a href="ssl-howto.html">13) SSL/TLS</a></li><li><a href="ssi-howto.html">14) SSI</a></li><li><a href="cgi-howto.html">15) CGI</a></li><li><a href="proxy-howto.html">16) Proxy Support</a></li><li><a href="mbeans-descriptors-howto.html">17) MBeans Descriptors</a></li><li><a href="default-servlet.html">18) Default Servlet</a></li><li><a href="cluster-howto.html">19) Clustering</a></li><li><a href="balancer-howto.html">20) Load Balancer</a></li><li><a href="connectors.html">21) Connectors</a></li><li><a href="monitoring.html">22) Monitoring and Management</a></li><li><a href="logging.html">23) Logging</a></li><li><a href="apr.html">24) APR/Native</a></li><li><a href="virtual-hosting-howto.html">25) Virtual Hosting</a></li><li><a href="aio.html">26) Advanced IO</a></li><li><a href="maven-jars.html">27) Mavenized</a></li><li><a href="security-howto.html">28) Security Considerations</a></li><li><a href="windows-service-howto.html">29) Windows Service</a></li><li><a href="windows-auth-howto.html">30) Windows Authentication</a></li><li><a href="jdbc-pool.html">31) Tomcat's JDBC Pool</a></li><li><a href="web-socket-howto.html">32) WebSocket</a></li><li><a href="rewrite.html">33) Rewrite</a></li><li><a href="cdi.html">34) CDI 2 and JAX-RS</a></li><li><a href="graal.html">35) AOT/GraalVM Support</a></li></ul></div><div><h2>Reference</h2><ul><li><a href="RELEASE-NOTES.txt">Release Notes</a></li><li><a href="config/index.html">Configuration</a></li><li><a href="api/index.html">Tomcat Javadocs</a></li><li><a href="servletapi/index.html">Servlet 4.0 Javadocs</a></li><li><a href="jspapi/index.html">JSP 2.3 Javadocs</a></li><li><a href="elapi/index.html">EL 3.0 Javadocs</a></li><li><a href="websocketapi/index.html">WebSocket 1.1 Javadocs</a></li><li><a href="jaspicapi/index.html">JASPIC 1.1 Javadocs</a></li><li><a href="annotationapi/index.html">Common Annotations 1.3 Javadocs</a></li><li><a href="https://tomcat.apache.org/connectors-doc/">JK 1.2 Documentation</a></li></ul></div><div><h2>Apache Tomcat Development</h2><ul><li><a href="building.html">Building</a></li><li><a href="changelog.html">Changelog</a></li><li><a href="https://cwiki.apache.org/confluence/display/TOMCAT/Tomcat+Versions">Status</a></li><li><a href="developers.html">Developers</a></li><li><a href="architecture/index.html">Architecture</a></li><li><a href="tribes/introduction.html">Tribes</a></li></ul></div></nav></div></div><div id="mainRight"><div id="content"><h2>Tomcat Web Application Manager How To</h2><h3 id="Table_of_Contents">Table of Contents</h3><div class="text"> |
||
| 5 | <ul><li><a href="#Introduction">Introduction</a></li><li><a href="#Message">Message</a></li><li><a href="#Manager">Manager</a></li><li><a href="#Applications">Applications</a><ol><li><a href="#Start">Start</a></li><li><a href="#Stop">Stop</a></li><li><a href="#Reload">Reload</a></li><li><a href="#Undeploy">Undeploy</a></li></ol></li><li><a href="#Deploy">Deploy</a><ol><li><a href="#Deploy_directory_or_WAR_file_located_on_server">Deploy directory or WAR file located on server</a><ol><li><a href="#Deploy_a_Directory_or_WAR_by_URL">Deploy a Directory or WAR by URL</a></li><li><a href="#Deploy_a_Directory_or_War_from_the_Host_appBase">Deploy a Directory or War from the Host appBase</a></li><li><a href="#Deploy_using_a_Context_configuration_%22.xml%22_file">Deploy using a Context configuration ".xml" file</a></li></ol></li><li><a href="#Upload_a_WAR_file_to_install">Upload a WAR file to install</a></li><li><a href="#Deployment_Notes">Deployment Notes</a></li><li><a href="#Deploy_Message">Deploy Message</a></li></ol></li><li><a href="#Diagnostics">Diagnostics</a><ol><li><a href="#Finding_memory_leaks">Finding memory leaks</a></li></ol></li><li><a href="#Server_Information">Server Information</a></li></ul> |
||
| 6 | </div><h3 id="Introduction">Introduction</h3><div class="text"> |
||
| 7 | |||
| 8 | <p>In many production environments it is very useful to have the capability |
||
| 9 | to manage your web applications without having to shut down and restart |
||
| 10 | Tomcat. This document is for the HTML web interface to the web application |
||
| 11 | <a href="manager-howto.html">manager</a>.</p> |
||
| 12 | |||
| 13 | <p>The interface is divided into six sections:</p> |
||
| 14 | <ul> |
||
| 15 | <li><strong>Message</strong> - Displays success and failure messages.</li> |
||
| 16 | <li><strong>Manager</strong> - General manager operations like list and |
||
| 17 | help.</li> |
||
| 18 | <li><strong>Applications</strong> - List of web applications and |
||
| 19 | commands.</li> |
||
| 20 | <li><strong>Deploy</strong> - Deploying web applications.</li> |
||
| 21 | <li><strong>Diagnostics</strong> - Identifying potential problems.</li> |
||
| 22 | <li><strong>Server Information</strong> - Information about the Tomcat |
||
| 23 | server.</li> |
||
| 24 | </ul> |
||
| 25 | |||
| 26 | </div><h3 id="Message">Message</h3><div class="text"> |
||
| 27 | |||
| 28 | <p> |
||
| 29 | Displays information about the success or failure of the last web application |
||
| 30 | manager command you performed. If it succeeded <strong>OK</strong> is displayed |
||
| 31 | and may be followed by a success message. If it failed <strong>FAIL</strong> |
||
| 32 | is displayed followed by an error message. Common failure messages are |
||
| 33 | documented below for each command. The complete list of failure messages for |
||
| 34 | each command can be found in the <a href="manager-howto.html">manager</a> web |
||
| 35 | application documentation. |
||
| 36 | </p> |
||
| 37 | |||
| 38 | </div><h3 id="Manager">Manager</h3><div class="text"> |
||
| 39 | |||
| 40 | <p>The Manager section has three links:</p> |
||
| 41 | <ul> |
||
| 42 | <li><strong>List Applications</strong> - Redisplay a list of web |
||
| 43 | applications.</li> |
||
| 44 | <li><strong>HTML Manager Help</strong> - A link to this document.</li> |
||
| 45 | <li><strong>Manager Help</strong> - A link to the comprehensive Manager |
||
| 46 | App HOW TO.</li> |
||
| 47 | </ul> |
||
| 48 | |||
| 49 | </div><h3 id="Applications">Applications</h3><div class="text"> |
||
| 50 | |||
| 51 | <p>The Applications section lists information about all the installed web |
||
| 52 | applications and provides links for managing them. For each web application |
||
| 53 | the following is displayed:</p> |
||
| 54 | <ul> |
||
| 55 | <li><strong>Path</strong> - The web application context path.</li> |
||
| 56 | <li><strong>Display Name</strong> - The display name for the web application |
||
| 57 | if it has one configured in its "web.xml" file.</li> |
||
| 58 | <li><strong>Running</strong> - Whether the web application is running and |
||
| 59 | available (true), or not running and unavailable (false).</li> |
||
| 60 | <li><strong>Sessions</strong> - The number of active sessions for remote |
||
| 61 | users of this web application. The number of sessions is a link which |
||
| 62 | when submitted displays more details about session usage by the web |
||
| 63 | application in the Message box.</li> |
||
| 64 | <li><strong>Commands</strong> - Lists all commands which can be performed on |
||
| 65 | the web application. Only those commands which can be performed will be |
||
| 66 | listed as a link which can be submitted. No commands can be performed on |
||
| 67 | the manager web application itself. The following commands can be |
||
| 68 | performed: |
||
| 69 | <ul> |
||
| 70 | <li><strong>Start</strong> - Start a web application which had been |
||
| 71 | stopped.</li> |
||
| 72 | <li><strong>Stop</strong> - Stop a web application which is currently |
||
| 73 | running and make it unavailable.</li> |
||
| 74 | <li><strong>Reload</strong> - Reload the web application so that new |
||
| 75 | ".jar" files in <code>/WEB-INF/lib/</code> or new classes in |
||
| 76 | <code>/WEB-INF/classes/</code> can be used.</li> |
||
| 77 | <li><strong>Undeploy</strong> - Stop and then remove this web |
||
| 78 | application from the server.</li> |
||
| 79 | </ul> |
||
| 80 | </li> |
||
| 81 | </ul> |
||
| 82 | |||
| 83 | <div class="subsection"><h4 id="Start">Start</h4><div class="text"> |
||
| 84 | |||
| 85 | <p>Signal a stopped application to restart, and make itself available again. |
||
| 86 | Stopping and starting is useful, for example, if the database required by |
||
| 87 | your application becomes temporarily unavailable. It is usually better to |
||
| 88 | stop the web application that relies on this database rather than letting |
||
| 89 | users continuously encounter database exceptions.</p> |
||
| 90 | |||
| 91 | <p>If this command succeeds, you will see a Message like this:</p> |
||
| 92 | <div class="codeBox"><pre><code>OK - Started application at context path /examples</code></pre></div> |
||
| 93 | |||
| 94 | <p>Otherwise, the Message will start with <code>FAIL</code> and include an |
||
| 95 | error message. Possible causes for problems include:</p> |
||
| 96 | <ul> |
||
| 97 | <li><em>Encountered exception</em> |
||
| 98 | <p>An exception was encountered trying to start the web application. |
||
| 99 | Check the Tomcat logs for the details.</p> |
||
| 100 | </li> |
||
| 101 | <li><em>Invalid context path was specified</em> |
||
| 102 | <p>The context path must start with a slash character, unless you are |
||
| 103 | referencing the ROOT web application -- in which case the context path |
||
| 104 | must be a zero-length string.</p> |
||
| 105 | </li> |
||
| 106 | <li><em>No context exists for path /foo</em> |
||
| 107 | <p>There is no deployed application on the context path |
||
| 108 | that you specified.</p> |
||
| 109 | </li> |
||
| 110 | <li><em>No context path was specified</em> |
||
| 111 | <p> |
||
| 112 | The <code>path</code> parameter is required. |
||
| 113 | </p> |
||
| 114 | </li> |
||
| 115 | </ul> |
||
| 116 | |||
| 117 | </div></div> |
||
| 118 | |||
| 119 | <div class="subsection"><h4 id="Stop">Stop</h4><div class="text"> |
||
| 120 | |||
| 121 | <p>Signal an existing application to make itself unavailable, but leave it |
||
| 122 | deployed. Any request that comes in while an application is |
||
| 123 | stopped will see an HTTP error 404, and this application will show as |
||
| 124 | "stopped" on a list applications command.</p> |
||
| 125 | |||
| 126 | <p>If this command succeeds, you will see a Message like this:</p> |
||
| 127 | <div class="codeBox"><pre><code>OK - Stopped application at context path /examples</code></pre></div> |
||
| 128 | |||
| 129 | <p>Otherwise, the Message will start with <code>FAIL</code> and include an |
||
| 130 | error message. Possible causes for problems include:</p> |
||
| 131 | <ul> |
||
| 132 | <li><em>Encountered exception</em> |
||
| 133 | <p>An exception was encountered trying to stop the web application. |
||
| 134 | Check the Tomcat logs for the details.</p> |
||
| 135 | </li> |
||
| 136 | <li><em>Invalid context path was specified</em> |
||
| 137 | <p>The context path must start with a slash character, unless you are |
||
| 138 | referencing the ROOT web application -- in which case the context path |
||
| 139 | must be a zero-length string.</p> |
||
| 140 | </li> |
||
| 141 | <li><em>No context exists for path /foo</em> |
||
| 142 | <p>There is no deployed application on the context path |
||
| 143 | that you specified.</p> |
||
| 144 | </li> |
||
| 145 | <li><em>No context path was specified</em> |
||
| 146 | <p> |
||
| 147 | The <code>path</code> parameter is required. |
||
| 148 | </p> |
||
| 149 | </li> |
||
| 150 | </ul> |
||
| 151 | |||
| 152 | </div></div> |
||
| 153 | |||
| 154 | <div class="subsection"><h4 id="Reload">Reload</h4><div class="text"> |
||
| 155 | |||
| 156 | <p>Signal an existing application to shut itself down and reload. This can |
||
| 157 | be useful when the web application context is not reloadable and you have |
||
| 158 | updated classes or property files in the <code>/WEB-INF/classes</code> |
||
| 159 | directory or when you have added or updated jar files in the |
||
| 160 | <code>/WEB-INF/lib</code> directory. |
||
| 161 | </p> |
||
| 162 | <p><strong>NOTE:</strong> The <code>/WEB-INF/web.xml</code> |
||
| 163 | web application configuration file is not checked on a reload; |
||
| 164 | the previous web.xml configuration is used. |
||
| 165 | If you have made changes to your web.xml file you must stop |
||
| 166 | then start the web application. |
||
| 167 | </p> |
||
| 168 | |||
| 169 | <p>If this command succeeds, you will see a Message like this:</p> |
||
| 170 | <div class="codeBox"><pre><code> |
||
| 171 | OK - Reloaded application at context path /examples |
||
| 172 | </code></pre></div> |
||
| 173 | |||
| 174 | <p>Otherwise, the Message will start with <code>FAIL</code> and include an |
||
| 175 | error message. Possible causes for problems include:</p> |
||
| 176 | <ul> |
||
| 177 | <li><em>Encountered exception</em> |
||
| 178 | <p>An exception was encountered trying to restart the web application. |
||
| 179 | Check the Tomcat logs for the details.</p> |
||
| 180 | </li> |
||
| 181 | <li><em>Invalid context path was specified</em> |
||
| 182 | <p>The context path must start with a slash character, unless you are |
||
| 183 | referencing the ROOT web application -- in which case the context path |
||
| 184 | must be a zero-length string.</p> |
||
| 185 | </li> |
||
| 186 | <li><em>No context exists for path /foo</em> |
||
| 187 | <p>There is no deployed application on the context path |
||
| 188 | that you specified.</p> |
||
| 189 | </li> |
||
| 190 | <li><em>No context path was specified</em> |
||
| 191 | <p>The <code>path</code> parameter is required.</p> |
||
| 192 | </li> |
||
| 193 | <li><em>Reload not supported on WAR deployed at path /foo</em> |
||
| 194 | <p>Currently, application reloading (to pick up changes to the classes or |
||
| 195 | <code>web.xml</code> file) is not supported when a web application is |
||
| 196 | installed directly from a WAR file, which happens when the host is |
||
| 197 | configured to not unpack WAR files. As it only works when the web |
||
| 198 | application is installed from an unpacked directory, if you are using |
||
| 199 | a WAR file, you should <code>undeploy</code> and then <code>deploy</code> |
||
| 200 | the application again to pick up your changes.</p> |
||
| 201 | </li> |
||
| 202 | </ul> |
||
| 203 | |||
| 204 | </div></div> |
||
| 205 | |||
| 206 | <div class="subsection"><h4 id="Undeploy">Undeploy</h4><div class="text"> |
||
| 207 | |||
| 208 | <p><strong><span style="color: red;">WARNING</span> - This command will delete the |
||
| 209 | contents of the web application directory and/or ".war" file if it exists within |
||
| 210 | the <code>appBase</code> directory (typically "webapps") for this virtual host |
||
| 211 | </strong>. The web application temporary work directory is also deleted. If |
||
| 212 | you simply want to take an application out of service, you should use the |
||
| 213 | <code>/stop</code> command instead.</p> |
||
| 214 | |||
| 215 | <p>Signal an existing application to gracefully shut itself down, and then |
||
| 216 | remove it from Tomcat (which also makes this context path available for |
||
| 217 | reuse later). This command is the logical opposite of the |
||
| 218 | <code>/deploy</code> Ant command, and the related deploy features available |
||
| 219 | in the HTML manager.</p> |
||
| 220 | |||
| 221 | <p>If this command succeeds, you will see a Message like this:</p> |
||
| 222 | <div class="codeBox"><pre><code>OK - Undeployed application at context path /examples</code></pre></div> |
||
| 223 | |||
| 224 | <p>Otherwise, the Message will start with <code>FAIL</code> and include an |
||
| 225 | error message. Possible causes for problems include:</p> |
||
| 226 | <ul> |
||
| 227 | <li><em>Encountered exception</em> |
||
| 228 | <p>An exception was encountered trying to undeploy the web application. |
||
| 229 | Check the Tomcat logs for the details.</p> |
||
| 230 | </li> |
||
| 231 | <li><em>Invalid context path was specified</em> |
||
| 232 | <p>The context path must start with a slash character, unless you are |
||
| 233 | referencing the ROOT web application -- in which case the context path |
||
| 234 | must be a zero-length string.</p> |
||
| 235 | </li> |
||
| 236 | <li><em>No context exists for path /foo</em> |
||
| 237 | <p>There is no deployed application on the context path |
||
| 238 | that you specified.</p> |
||
| 239 | </li> |
||
| 240 | <li><em>No context path was specified</em> |
||
| 241 | The <code>path</code> parameter is required. |
||
| 242 | </li> |
||
| 243 | </ul> |
||
| 244 | |||
| 245 | </div></div> |
||
| 246 | |||
| 247 | </div><h3 id="Deploy">Deploy</h3><div class="text"> |
||
| 248 | |||
| 249 | <p>Web applications can be deployed using files or directories located |
||
| 250 | on the Tomcat server or you can upload a web application archive (WAR) |
||
| 251 | file to the server.</p> |
||
| 252 | |||
| 253 | <p>To install an application, fill in the appropriate fields for the type |
||
| 254 | of install you want to do and then submit it using the <i>Install</i> |
||
| 255 | button.</p> |
||
| 256 | |||
| 257 | <div class="subsection"><h4 id="Deploy_directory_or_WAR_file_located_on_server">Deploy directory or WAR file located on server</h4><div class="text"> |
||
| 258 | |||
| 259 | <p>Deploy and start a new web application, attached to the specified <i>Context |
||
| 260 | Path:</i> (which must not be in use by any other web application). |
||
| 261 | This command is the logical opposite of the <em>Undeploy</em> command.</p> |
||
| 262 | |||
| 263 | <p>There are a number of different ways the deploy command can be used.</p> |
||
| 264 | |||
| 265 | <div class="subsection"><h4 id="Deploy_a_Directory_or_WAR_by_URL">Deploy a Directory or WAR by URL</h4><div class="text"> |
||
| 266 | |||
| 267 | <p>Install a web application directory or ".war" file located on the Tomcat |
||
| 268 | server. If no <i>Context Path</i> is specified, the directory name or the |
||
| 269 | war file name without the ".war" extension is used as the path. The |
||
| 270 | <i>WAR or Directory URL</i> specifies a URL (including the <code>file:</code> |
||
| 271 | scheme) for either a directory or a web application archive (WAR) file. The |
||
| 272 | supported syntax for a URL referring to a WAR file is described on the Javadocs |
||
| 273 | page for the <code>java.net.JarURLConnection</code> class. Use only URLs that |
||
| 274 | refer to the entire WAR file.</p> |
||
| 275 | |||
| 276 | <p>In this example the web application located in the directory |
||
| 277 | <code>C:\path\to\foo</code> on the Tomcat server (running on Windows) |
||
| 278 | is deployed as the web application context named <code>/footoo</code>.</p> |
||
| 279 | <div class="codeBox"><pre><code>Context Path: /footoo |
||
| 280 | WAR or Directory URL: file:C:/path/to/foo |
||
| 281 | </code></pre></div> |
||
| 282 | |||
| 283 | |||
| 284 | <p>In this example the ".war" file <code>/path/to/bar.war</code> on the |
||
| 285 | Tomcat server (running on Unix) is deployed as the web application |
||
| 286 | context named <code>/bar</code>. Notice that there is no <code>path</code> |
||
| 287 | parameter so the context path defaults to the name of the web application |
||
| 288 | archive file without the ".war" extension.</p> |
||
| 289 | <div class="codeBox"><pre><code>WAR or Directory URL: jar:file:/path/to/bar.war!/</code></pre></div> |
||
| 290 | |||
| 291 | </div></div> |
||
| 292 | |||
| 293 | <div class="subsection"><h4 id="Deploy_a_Directory_or_War_from_the_Host_appBase">Deploy a Directory or War from the Host appBase</h4><div class="text"> |
||
| 294 | |||
| 295 | <p>Install a web application directory or ".war" file located in your Host |
||
| 296 | appBase directory. If no <i>Context Path</i> is specified the directory name |
||
| 297 | or the war file name without the ".war" extension is used as the path.</p> |
||
| 298 | |||
| 299 | <p>In this example the web application located in a subdirectory named |
||
| 300 | <code>foo</code> in the Host appBase directory of the Tomcat server is |
||
| 301 | deployed as the web application context named <code>/foo</code>. Notice |
||
| 302 | that there is no <code>path</code> parameter so the context path defaults |
||
| 303 | to the name of the web application directory.</p> |
||
| 304 | <div class="codeBox"><pre><code>WAR or Directory URL: foo</code></pre></div> |
||
| 305 | |||
| 306 | |||
| 307 | <p>In this example the ".war" file <code>bar.war</code> located in your |
||
| 308 | Host appBase directory on the Tomcat server is deployed as the web |
||
| 309 | application context named <code>/bartoo</code>.</p> |
||
| 310 | <div class="codeBox"><pre><code>Context Path: /bartoo |
||
| 311 | WAR or Directory URL: bar.war</code></pre></div> |
||
| 312 | |||
| 313 | </div></div> |
||
| 314 | |||
| 315 | <div class="subsection"><h4 id="Deploy_using_a_Context_configuration_".xml"_file">Deploy using a Context configuration ".xml" file</h4><div class="text"> |
||
| 316 | |||
| 317 | <p>If the Host deployXML flag is set to true, you can install a web |
||
| 318 | application using a Context configuration ".xml" file and an optional |
||
| 319 | ".war" file or web application directory. The <i>Context Path</i> |
||
| 320 | is not used when installing a web application using a context ".xml" |
||
| 321 | configuration file.</p> |
||
| 322 | |||
| 323 | <p>A Context configuration ".xml" file can contain valid XML for a |
||
| 324 | web application Context just as if it were configured in your |
||
| 325 | Tomcat <code>server.xml</code> configuration file. Here is an |
||
| 326 | example for Tomcat running on Windows:</p> |
||
| 327 | <div class="codeBox"><pre><code><Context path="/foobar" docBase="C:\path\to\application\foobar"> |
||
| 328 | </Context></code></pre></div> |
||
| 329 | |||
| 330 | |||
| 331 | <p>Use of the <i>WAR or Directory URL</i> is optional. When used |
||
| 332 | to select a web application ".war" file or directory it overrides any |
||
| 333 | docBase configured in the context configuration ".xml" file.</p> |
||
| 334 | |||
| 335 | <p>Here is an example of installing an application using a Context |
||
| 336 | configuration ".xml" file for Tomcat running on Windows.</p> |
||
| 337 | <div class="codeBox"><pre><code>XML Configuration file URL: file:C:/path/to/context.xml</code></pre></div> |
||
| 338 | |||
| 339 | |||
| 340 | <p>Here is an example of installing an application using a Context |
||
| 341 | configuration ".xml" file and a web application ".war" file located |
||
| 342 | on the server (Tomcat running on Unix).</p> |
||
| 343 | <div class="codeBox"><pre><code>XML Configuration file URL: file:/path/to/context.xml |
||
| 344 | WAR or Directory URL: jar:file:/path/to/bar.war!/</code></pre></div> |
||
| 345 | |||
| 346 | </div></div> |
||
| 347 | </div></div> |
||
| 348 | |||
| 349 | <div class="subsection"><h4 id="Upload_a_WAR_file_to_install">Upload a WAR file to install</h4><div class="text"> |
||
| 350 | |||
| 351 | <p>Upload a WAR file from your local system and install it into the |
||
| 352 | appBase for your Host. The name of the WAR file without the ".war" |
||
| 353 | extension is used as the context path name.</p> |
||
| 354 | |||
| 355 | <p>Use the <i>Browse</i> button to select a WAR file to upload to the |
||
| 356 | server from your local desktop system.</p> |
||
| 357 | |||
| 358 | <p>The .WAR file may include Tomcat specific deployment configuration, by |
||
| 359 | including a Context configuration XML file in |
||
| 360 | <code>/META-INF/context.xml</code>.</p> |
||
| 361 | |||
| 362 | <p>Upload of a WAR file could fail for the following reasons:</p> |
||
| 363 | <ul> |
||
| 364 | <li><em>File uploaded must be a .war</em> |
||
| 365 | <p>The upload install will only accept files which have the filename |
||
| 366 | extension of ".war".</p> |
||
| 367 | </li> |
||
| 368 | <li><em>War file already exists on server</em> |
||
| 369 | <p>If a war file of the same name already exists in your Host's |
||
| 370 | appBase the upload will fail. Either undeploy the existing war file |
||
| 371 | from your Host's appBase or upload the new war file using a different |
||
| 372 | name.</p> |
||
| 373 | </li> |
||
| 374 | <li><em>File upload failed, no file</em> |
||
| 375 | <p>The file upload failed, no file was received by the server.</p> |
||
| 376 | </li> |
||
| 377 | <li><em>Install Upload Failed, Exception:</em> |
||
| 378 | <p>The war file upload or install failed with a Java Exception. |
||
| 379 | The exception message will be listed.</p> |
||
| 380 | </li> |
||
| 381 | </ul> |
||
| 382 | |||
| 383 | </div></div> |
||
| 384 | |||
| 385 | <div class="subsection"><h4 id="Deployment_Notes">Deployment Notes</h4><div class="text"> |
||
| 386 | |||
| 387 | <p>If the Host is configured with unpackWARs=true and you install a war |
||
| 388 | file, the war will be unpacked into a directory in your Host appBase |
||
| 389 | directory.</p> |
||
| 390 | |||
| 391 | <p>If the application war or directory is deployed in your Host appBase |
||
| 392 | directory and either the Host is configured with autoDeploy=true the Context |
||
| 393 | path must match the directory name or war file name without the ".war" |
||
| 394 | extension.</p> |
||
| 395 | |||
| 396 | <p>For security when untrusted users can manage web applications, the |
||
| 397 | Host deployXML flag can be set to false. This prevents untrusted users |
||
| 398 | from installing web applications using a configuration XML file and |
||
| 399 | also prevents them from installing application directories or ".war" |
||
| 400 | files located outside of their Host appBase.</p> |
||
| 401 | |||
| 402 | </div></div> |
||
| 403 | |||
| 404 | <div class="subsection"><h4 id="Deploy_Message">Deploy Message</h4><div class="text"> |
||
| 405 | |||
| 406 | <p>If deployment and startup is successful, you will receive a Message |
||
| 407 | like this:</p> |
||
| 408 | <div class="codeBox"><pre><code>OK - Deployed application at context path /foo</code></pre></div> |
||
| 409 | |||
| 410 | <p>Otherwise, the Message will start with <code>FAIL</code> and include an |
||
| 411 | error message. Possible causes for problems include:</p> |
||
| 412 | <ul> |
||
| 413 | <li><em>Application already exists at path /foo</em> |
||
| 414 | <p>The context paths for all currently running web applications must be |
||
| 415 | unique. Therefore, you must either undeploy the existing web |
||
| 416 | application using this context path, or choose a different context path |
||
| 417 | for the new one.</p> |
||
| 418 | </li> |
||
| 419 | <li><em>Document base does not exist or is not a readable directory</em> |
||
| 420 | <p>The URL specified by the <i>WAR or Directory URL:</i> field must |
||
| 421 | identify a directory on this server that contains the "unpacked" version |
||
| 422 | of a web application, or the absolute URL of a web application archive |
||
| 423 | (WAR) file that contains this application. Correct the value entered for |
||
| 424 | the <i>WAR or Directory URL:</i> field.</p> |
||
| 425 | </li> |
||
| 426 | <li><em>Encountered exception</em> |
||
| 427 | <p>An exception was encountered trying to start the new web application. |
||
| 428 | Check the Tomcat logs for the details, but likely explanations include |
||
| 429 | problems parsing your <code>/WEB-INF/web.xml</code> file, or missing |
||
| 430 | classes encountered when initializing application event listeners and |
||
| 431 | filters.</p> |
||
| 432 | </li> |
||
| 433 | <li><em>Invalid application URL was specified</em> |
||
| 434 | <p>The URL for the <i>WAR or Directory URL:</i> field that you specified |
||
| 435 | was not valid. Such URLs must start with <code>file:</code>, and URLs |
||
| 436 | for a WAR file must end in ".war".</p> |
||
| 437 | </li> |
||
| 438 | <li><em>Invalid context path was specified</em> |
||
| 439 | <p>The context path must start with a slash character, unless you are |
||
| 440 | referencing the ROOT web application -- in which case the context path |
||
| 441 | must be a "/" string.</p> |
||
| 442 | </li> |
||
| 443 | <li><em>Context path must match the directory or WAR file name:</em> |
||
| 444 | <p>If the application war or directory is deployed in your Host appBase |
||
| 445 | directory and either the Host is configured with autoDeploy=true the Context |
||
| 446 | path must match the directory name or war file name without the ".war" |
||
| 447 | extension.</p> |
||
| 448 | </li> |
||
| 449 | <li><em>Only web applications in the Host web application directory can |
||
| 450 | be deployed</em> |
||
| 451 | <p> |
||
| 452 | If the Host deployXML flag is set to false this error will happen |
||
| 453 | if an attempt is made to install a web application directory or |
||
| 454 | ".war" file outside of the Host appBase directory. |
||
| 455 | </p></li> |
||
| 456 | </ul> |
||
| 457 | |||
| 458 | </div></div> |
||
| 459 | </div><h3 id="Diagnostics">Diagnostics</h3><div class="text"> |
||
| 460 | |||
| 461 | <div class="subsection"><h4 id="Finding_memory_leaks">Finding memory leaks</h4><div class="text"> |
||
| 462 | |||
| 463 | <p><strong>The find leaks diagnostic triggers a full garbage collection. It |
||
| 464 | should be used with extreme caution on production systems.</strong></p> |
||
| 465 | |||
| 466 | <p>The find leaks diagnostic attempts to identify web applications that have |
||
| 467 | caused memory leaks when they were stopped, reloaded or undeployed. Results |
||
| 468 | should always be confirmed |
||
| 469 | with a profiler. The diagnostic uses additional functionality provided by the |
||
| 470 | StandardHost implementation. It will not work if a custom host is used that |
||
| 471 | does not extend StandardHost.</p> |
||
| 472 | |||
| 473 | <p>This diagnostic will list context paths for the web applications that were |
||
| 474 | stopped, reloaded or undeployed, but which classes from the previous runs |
||
| 475 | are still present in memory, thus being a memory leak. If an application |
||
| 476 | has been reloaded several times, it may be listed several times.</p> |
||
| 477 | |||
| 478 | <p>Explicitly triggering a full garbage collection from Java code is documented |
||
| 479 | to be unreliable. Furthermore, depending on the JVM used, there are options to |
||
| 480 | disable explicit GC triggering, like <code>-XX:+DisableExplicitGC</code>. |
||
| 481 | If you want to make sure, that the diagnostics were successfully running a full GC, |
||
| 482 | you will need to check using tools like GC logging, JConsole or similar.</p> |
||
| 483 | |||
| 484 | </div></div> |
||
| 485 | </div><h3 id="Server_Information">Server Information</h3><div class="text"> |
||
| 486 | |||
| 487 | <p>This section displays information about Tomcat, the operating system of the |
||
| 488 | server Tomcat is hosted on, the Java Virtual Machine Tomcat is running in, the |
||
| 489 | primary host name of the server (may not be the host name used to access Tomcat) |
||
| 490 | and the primary IP address of the server (may not be the IP address used to |
||
| 491 | access Tomcat).</p> |
||
| 492 | |||
| 493 | </div></div></div></div></div><footer><div id="footer"> |
||
| 494 | Copyright © 1999-2025, The Apache Software Foundation |
||
| 495 | <br> |
||
| 496 | Apache Tomcat, Tomcat, Apache, the Apache Tomcat logo and the Apache logo |
||
| 497 | are either registered trademarks or trademarks of the Apache Software |
||
| 498 | Foundation. |
||
| 499 | </div></footer></div></body></html> |