| [66] | 1 | <html><head><META http-equiv="Content-Type" content="text/html; charset=iso-8859-1"><title>Apache Tomcat 6.0 - Tomcat Web Application Deployment</title><meta value="Allistair Crossley" name="author"><meta value="" 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><!--LEFT SIDE NAVIGATION--><td nowrap="true" valign="top" width="20%"><p><strong>Links</strong></p><ul><li><a href="index.html">Docs Home</a></li><li><a href="http://wiki.apache.org/tomcat/FAQ">FAQ</a></li></ul><p><strong>User Guide</strong></p><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="realm-howto.html">6) Realms and AAA</a></li><li><a href="security-manager-howto.html">7) Security Manager</a></li><li><a href="jndi-resources-howto.html">8) JNDI Resources</a></li><li><a href="jndi-datasource-examples-howto.html">9) JDBC DataSources</a></li><li><a href="class-loader-howto.html">10) Classloading</a></li><li><a href="jasper-howto.html">11) JSPs</a></li><li><a href="ssl-howto.html">12) SSL</a></li><li><a href="ssi-howto.html">13) SSI</a></li><li><a href="cgi-howto.html">14) CGI</a></li><li><a href="proxy-howto.html">15) Proxy Support</a></li><li><a href="mbeans-descriptor-howto.html">16) MBean Descriptor</a></li><li><a href="default-servlet.html">17) Default Servlet</a></li><li><a href="cluster-howto.html">18) Clustering</a></li><li><a href="balancer-howto.html">19) Load Balancer</a></li><li><a href="connectors.html">20) Connectors</a></li><li><a href="monitoring.html">21) Monitoring and Management</a></li><li><a href="logging.html">22) Logging</a></li><li><a href="apr.html">23) APR/Native</a></li><li><a href="virtual-hosting-howto.html">24) Virtual Hosting</a></li><li><a href="aio.html">25) Advanced IO</a></li><li><a href="extras.html">26) Additional Components</a></li><li><a href="maven-jars.html">27) Mavenized</a></li></ul><p><strong>Reference</strong></p><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">Javadocs</a></li><li><a href="http://tomcat.apache.org/connectors-doc/">JK 1.2 Documentation</a></li></ul><p><strong>Apache Tomcat Development</strong></p><ul><li><a href="building.html">Building</a></li><li><a href="changelog.html">Changelog</a></li><li><a href="http://wiki.apache.org/tomcat/TomcatVersions">Status</a></li><li><a href="developers.html">Developers</a></li><li><a href="architecture/index.html">Architecture</a></li><li><a href="funcspecs/index.html">Functional Specs.</a></li></ul></td><!--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 Deployment</h2></td><td nowrap="true" valign="top" align="right"><small><a href="printer/deployer-howto.html"><img alt="Printer Friendly Version" border="0" src="./images/printer.gif"><br>print-friendly<br>version |
|---|
| 4 | </a></small></td></tr></table><table cellpadding="2" cellspacing="0" border="0"><tr><td bgcolor="#525D76"><font face="arial,helvetica.sanserif" color="#ffffff"><a name="Table of Contents"><strong>Table of Contents</strong></a></font></td></tr><tr><td><blockquote> |
|---|
| 5 | <ul> |
|---|
| 6 | <li><a href="#Introduction">Introduction</a></li> |
|---|
| 7 | <li><a href="#Installation">Installation</a></li> |
|---|
| 8 | <li><a href="#A word on Contexts">A word on Contexts</a></li> |
|---|
| 9 | <li><a href="#Deployment on Tomcat startup">Deployment on Tomcat startup</a></li> |
|---|
| 10 | <li><a href="#Deploying on a running Tomcat server">Deploying on a running Tomcat server</a></li> |
|---|
| 11 | <li><a href="#Deploying using the Tomcat Manager">Deploying using the Tomcat Manager</a></li> |
|---|
| 12 | <li><a href="#Deploying using the Client Deployer Package">Deploying using |
|---|
| 13 | the Tomcat Client Deployer</a></li> |
|---|
| 14 | </ul> |
|---|
| 15 | |
|---|
| 16 | </blockquote></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> |
|---|
| 17 | <p> |
|---|
| 18 | Deployment is the term used for the process of installing a web |
|---|
| 19 | application (either a 3rd party WAR or your own custom web application) |
|---|
| 20 | into the Tomcat server. |
|---|
| 21 | </p> |
|---|
| 22 | <p> |
|---|
| 23 | Web application deployment may be accomplished in a number of ways |
|---|
| 24 | within the Tomcat server. |
|---|
| 25 | <ul> |
|---|
| 26 | <li>Statically; the web application is setup before Tomcat is started</li> |
|---|
| 27 | <li> |
|---|
| 28 | Dynamically; in conjunction with the Tomcat Manager web application or |
|---|
| 29 | manipulating already deployed web applications |
|---|
| 30 | </li> |
|---|
| 31 | </ul> |
|---|
| 32 | </p> |
|---|
| 33 | <p> |
|---|
| 34 | The Tomcat Manager is a tool that allows URL-based web application |
|---|
| 35 | deployment features. There is also a tool called the Client Deployer, |
|---|
| 36 | which is a command shell based script that interacts with the Tomcat |
|---|
| 37 | Manager but provides additional functionality such as compiling and |
|---|
| 38 | validating web applications as well as packaging web application into |
|---|
| 39 | web application resource (WAR) files. |
|---|
| 40 | </p> |
|---|
| 41 | </blockquote></td></tr></table><table cellpadding="2" cellspacing="0" border="0"><tr><td bgcolor="#525D76"><font face="arial,helvetica.sanserif" color="#ffffff"><a name="Installation"><strong>Installation</strong></a></font></td></tr><tr><td><blockquote> |
|---|
| 42 | <p> |
|---|
| 43 | There is no installation required for static deployment of web |
|---|
| 44 | applications as this is provided out of the box by Tomcat. Nor is any |
|---|
| 45 | installation required for deployment functions with the Tomcat Manager, |
|---|
| 46 | although some configuration is required as detailed in the |
|---|
| 47 | Tomcat Manager manual. An installation is however required if you wish |
|---|
| 48 | to use the Tomcat Client Deployer (TCD). |
|---|
| 49 | </p> |
|---|
| 50 | <p> |
|---|
| 51 | The TCD is not packaged with the Tomcat core |
|---|
| 52 | distribution, and must therefore be downloaded separately from |
|---|
| 53 | the Downloads area. The download is usually labelled |
|---|
| 54 | <i>apache-tomcat-6.0.x-deployer</i>. |
|---|
| 55 | </p> |
|---|
| 56 | <p> |
|---|
| 57 | TCD has prerequisites of Apache Ant 1.6.2+ and a Java installation. |
|---|
| 58 | Your environment should define an ANT_HOME environment value pointing to |
|---|
| 59 | the root of your Ant installation, and a JAVA_HOME value pointing to |
|---|
| 60 | your Java installation. Additionally, you should ensure Ant's ant |
|---|
| 61 | command, and the Java javac compiler command run from the command shell |
|---|
| 62 | that your operating system provides. |
|---|
| 63 | </p> |
|---|
| 64 | <ol> |
|---|
| 65 | <li>Download the TCD distribution</li> |
|---|
| 66 | <li> |
|---|
| 67 | The TCD package need not be extracted into any existing Tomcat |
|---|
| 68 | installation, it can be extracted to any location. |
|---|
| 69 | </li> |
|---|
| 70 | <li>Read Using the <a href="#Deploying using the Client Deployer Package"> |
|---|
| 71 | Tomcat Client Deployer</a></li> |
|---|
| 72 | </ol> |
|---|
| 73 | </blockquote></td></tr></table><table cellpadding="2" cellspacing="0" border="0"><tr><td bgcolor="#525D76"><font face="arial,helvetica.sanserif" color="#ffffff"><a name="A word on Contexts"><strong>A word on Contexts</strong></a></font></td></tr><tr><td><blockquote> |
|---|
| 74 | <p> |
|---|
| 75 | In talking about deployment of web applications, the concept of a |
|---|
| 76 | <i>Context</i> is required to be understood. A Context is what Tomcat |
|---|
| 77 | calls a web application. |
|---|
| 78 | </p> |
|---|
| 79 | <p> |
|---|
| 80 | In order to configure a Context within Tomcat a <i>Context Descriptor</i> |
|---|
| 81 | is required. A Context Descriptor is simply an XML file that contains |
|---|
| 82 | Tomcat related configuration for a Context, e.g naming resources or |
|---|
| 83 | session manager configuration. In earlier versions of |
|---|
| 84 | Tomcat the content of a Context Descriptor configuration was often stored within |
|---|
| 85 | Tomcat's primary configuration file <i>server.xml</i> but this is now |
|---|
| 86 | discouraged (although it currently still works). |
|---|
| 87 | </p> |
|---|
| 88 | <p> |
|---|
| 89 | Context Descriptors not only help Tomcat to know how to configure |
|---|
| 90 | Contexts but other tools such as the Tomcat Manager and TCD often use |
|---|
| 91 | these Context Descriptors to perform their roles properly. |
|---|
| 92 | </p> |
|---|
| 93 | <p> |
|---|
| 94 | The locations for Context Descriptors are; |
|---|
| 95 | <ol> |
|---|
| 96 | <li>$CATALINA_BASE/conf/[enginename]/[hostname]/context.xml</li> |
|---|
| 97 | <li>$CATALINA_BASE/webapps/[webappname]/META-INF/context.xml</li> |
|---|
| 98 | </ol> |
|---|
| 99 | Files in (1) are named [webappname].xml but files in (2) are named |
|---|
| 100 | context.xml. If a Context Descriptor is not provided for a Context, |
|---|
| 101 | Tomcat configures the Context using default values. |
|---|
| 102 | </p> |
|---|
| 103 | </blockquote></td></tr></table><table cellpadding="2" cellspacing="0" border="0"><tr><td bgcolor="#525D76"><font face="arial,helvetica.sanserif" color="#ffffff"><a name="Deployment on Tomcat startup"><strong>Deployment on Tomcat startup</strong></a></font></td></tr><tr><td><blockquote> |
|---|
| 104 | <p> |
|---|
| 105 | If you are not interested in using the Tomcat Manager, or TCD, |
|---|
| 106 | then you'll need to deploy your web applications |
|---|
| 107 | statically to Tomcat, followed by a Tomcat startup. The location you |
|---|
| 108 | deploy web applications to for this type of deployment is called the |
|---|
| 109 | <code>appBase</code> which is specified per Host. You either copy a |
|---|
| 110 | so-called <i>exploded web application</i>, i.e non-compressed, to this |
|---|
| 111 | location, or a compressed web application resource .WAR file. |
|---|
| 112 | </p> |
|---|
| 113 | <p> |
|---|
| 114 | The web applications present in the location specified by the Host's |
|---|
| 115 | (default Host is "localhost") <code>appBase</code> attribute (default |
|---|
| 116 | appBase is "$CATALINA_BASE/webapps") will be deployed on Tomcat startup |
|---|
| 117 | only if the Host's <code>deployOnStartup</code> attribute is "true". |
|---|
| 118 | </p> |
|---|
| 119 | <p> |
|---|
| 120 | The following deployment sequence will occur on Tomcat startup in that |
|---|
| 121 | case: |
|---|
| 122 | </p> |
|---|
| 123 | <ol> |
|---|
| 124 | <li>Any Context Descriptors will be deployed first.</li> |
|---|
| 125 | <li> |
|---|
| 126 | Exploded web applications not referenced by any Context |
|---|
| 127 | Descriptor will then be deployed. If they have an associated |
|---|
| 128 | .WAR file in the appBase and it is newer than the exploded web application, |
|---|
| 129 | the exploded directory will be removed and the webapp will be |
|---|
| 130 | redeployed from the .WAR |
|---|
| 131 | </li> |
|---|
| 132 | <li>.WAR files will be deployed</li> |
|---|
| 133 | </ol> |
|---|
| 134 | <p> |
|---|
| 135 | Note again that for each deployed web application, a |
|---|
| 136 | Context Descriptor will be created <i>unless one exists already</i>. |
|---|
| 137 | </p> |
|---|
| 138 | </blockquote></td></tr></table><table cellpadding="2" cellspacing="0" border="0"><tr><td bgcolor="#525D76"><font face="arial,helvetica.sanserif" color="#ffffff"><a name="Deploying on a running Tomcat server"><strong>Deploying on a running Tomcat server</strong></a></font></td></tr><tr><td><blockquote> |
|---|
| 139 | <p> |
|---|
| 140 | It is possible to deploy web applications to a running Tomcat server. |
|---|
| 141 | </p> |
|---|
| 142 | <p> |
|---|
| 143 | If the Host <code>autoDeploy</code> attribute is "true", the Host will |
|---|
| 144 | attempt to deploy and update web applications dynamically, as needed, |
|---|
| 145 | for example if a new .WAR is dropped into the <code>appBase</code>. |
|---|
| 146 | For this to work, the Host needs to have background processing |
|---|
| 147 | enabled which is the default configuration. |
|---|
| 148 | </p> |
|---|
| 149 | |
|---|
| 150 | <p> |
|---|
| 151 | <code>autoDeploy</code> set to "true" and a running Tomcat allows for: |
|---|
| 152 | </p> |
|---|
| 153 | <ul> |
|---|
| 154 | <li>Deployment of .WAR files copied into the Host <code>appBase</code>.</li> |
|---|
| 155 | <li> |
|---|
| 156 | Deployment of exploded web applications which are |
|---|
| 157 | copied into the Host <code>appBase</code>. |
|---|
| 158 | </li> |
|---|
| 159 | <li> |
|---|
| 160 | Re-deployment of a web application which has already been deployed from |
|---|
| 161 | a .WAR when the new .WAR is provided. In this case the exploded |
|---|
| 162 | web application is removed, and the .WAR is expanded again. |
|---|
| 163 | Note that the explosion will not occur if the Host is configured |
|---|
| 164 | so that .WARs are not exploded with a <code>unpackWARs</code> |
|---|
| 165 | attribute set to "false", in which case the web application |
|---|
| 166 | will be simply redeployed as a compressed archive. |
|---|
| 167 | </li> |
|---|
| 168 | <li> |
|---|
| 169 | Re-deployment of a web application if the /WEB-INF/web.xml file (or any |
|---|
| 170 | other resource defined as a WatchedResource) is updated. |
|---|
| 171 | </li> |
|---|
| 172 | <li> |
|---|
| 173 | Re-deployment of a web application if the Context Descriptor file from which |
|---|
| 174 | the web application has been deployed is updated. |
|---|
| 175 | </li> |
|---|
| 176 | <li> |
|---|
| 177 | Re-deployment of a web application if a Context Descriptor file (with a |
|---|
| 178 | filename corresponding to the Context path of the previously deployed |
|---|
| 179 | web application) is added to the |
|---|
| 180 | <code>$CATALINA_BASE/conf/[enginename]/[hostname]/</code> |
|---|
| 181 | directory. |
|---|
| 182 | </li> |
|---|
| 183 | <li> |
|---|
| 184 | Undeployment of a web application if its document base (docBase) |
|---|
| 185 | is deleted. Note that on Windows, this assumes that anti-locking |
|---|
| 186 | features (see Context configuration) are enabled, otherwise it is not |
|---|
| 187 | possible to delete the resources of a running web application. |
|---|
| 188 | </li> |
|---|
| 189 | </ul> |
|---|
| 190 | <p> |
|---|
| 191 | Note that web application reloading can also be configured in the loader, in which |
|---|
| 192 | case loaded classes will be tracked for changes. |
|---|
| 193 | </p> |
|---|
| 194 | </blockquote></td></tr></table><table cellpadding="2" cellspacing="0" border="0"><tr><td bgcolor="#525D76"><font face="arial,helvetica.sanserif" color="#ffffff"><a name="Deploying using the Tomcat Manager"><strong>Deploying using the Tomcat Manager</strong></a></font></td></tr><tr><td><blockquote> |
|---|
| 195 | <p> |
|---|
| 196 | The Tomcat Manager is covered in its <a href="manager-howto.html">own manual page</a>. |
|---|
| 197 | </p> |
|---|
| 198 | </blockquote></td></tr></table><table cellpadding="2" cellspacing="0" border="0"><tr><td bgcolor="#525D76"><font face="arial,helvetica.sanserif" color="#ffffff"><a name="Deploying using the Client Deployer Package"><strong>Deploying using the Client Deployer Package</strong></a></font></td></tr><tr><td><blockquote> |
|---|
| 199 | <p> |
|---|
| 200 | Finally, deployment of web application may be achieved using the |
|---|
| 201 | Tomcat Client Deployer. This is a package which can be used to |
|---|
| 202 | validate, compile, compress to .WAR, and deploy web applications to |
|---|
| 203 | production or development Tomcat servers. It should be noted that this feature |
|---|
| 204 | uses the Tomcat Manager and as such the target Tomcat server should be |
|---|
| 205 | running. |
|---|
| 206 | </p> |
|---|
| 207 | |
|---|
| 208 | <p> |
|---|
| 209 | It is assumed the user will be familar with Apache Ant for using the TCD. |
|---|
| 210 | Apache Ant is a scripted build tool. The TCD comes pre-packaged with a |
|---|
| 211 | build script to use. Only a modest understanding of Apache Ant is |
|---|
| 212 | required (installation as listed earlier in this page, and familiarity |
|---|
| 213 | with using the operating system command shell and configuring |
|---|
| 214 | environment variables). |
|---|
| 215 | </p> |
|---|
| 216 | |
|---|
| 217 | <p> |
|---|
| 218 | The TCD includes Ant tasks, the Jasper page compiler for JSP compilation |
|---|
| 219 | before deployment, as well as a task which |
|---|
| 220 | validates the web application Context Descriptor. The validator task (class |
|---|
| 221 | <code>org.apache.catalina.ant.ValidatorTask</code>) allows only one parameter: |
|---|
| 222 | the base path of an exploded web application. |
|---|
| 223 | </p> |
|---|
| 224 | |
|---|
| 225 | <p> |
|---|
| 226 | The TCD uses an exploded web application as input (see the list of the |
|---|
| 227 | properties used below). A web application that is programatically |
|---|
| 228 | deployed with the deployer may include a Context Desciptor in |
|---|
| 229 | <code>/META-INF/context.xml</code>. |
|---|
| 230 | </p> |
|---|
| 231 | |
|---|
| 232 | <p> |
|---|
| 233 | The TCD includes a ready-to-use Ant script, with the following targets: |
|---|
| 234 | </p> |
|---|
| 235 | <ul> |
|---|
| 236 | <li> |
|---|
| 237 | <code>compile</code> (default): Compile and validate the web |
|---|
| 238 | application. This can be used standalone, and does not need a running |
|---|
| 239 | Tomcat server. The compiled application will only run on the associated |
|---|
| 240 | Tomcat 6.0.x server release, and is not guaranteed to work on another |
|---|
| 241 | Tomcat release, as the code generated by Jasper depends on its runtime |
|---|
| 242 | component. It should also be noted that this target will also compile |
|---|
| 243 | automatically any Java source file located in the |
|---|
| 244 | <code>/WEB-INF/classes</code> folder of the web application.</li> |
|---|
| 245 | <li> |
|---|
| 246 | <code>deploy</code>: Deploy a web application (compiled or not) to |
|---|
| 247 | a Tomcat server. |
|---|
| 248 | </li> |
|---|
| 249 | <li><code>undeploy</code>: Undeploy a web application</li> |
|---|
| 250 | <li><code>start</code>: Start web application</li> |
|---|
| 251 | <li><code>reload</code>: Reload web application</li> |
|---|
| 252 | <li><code>stop</code>: Stop web application</li> |
|---|
| 253 | </ul> |
|---|
| 254 | |
|---|
| 255 | <p> |
|---|
| 256 | In order for the deployment to be configured, create a file |
|---|
| 257 | called <code>deployer.properties</code> in the TCD installation |
|---|
| 258 | directory root. In this file, add the following name=value pairs per |
|---|
| 259 | line: |
|---|
| 260 | </p> |
|---|
| 261 | |
|---|
| 262 | <p> |
|---|
| 263 | Additionally, you will need to ensure that a user has been |
|---|
| 264 | setup for the target Tomcat Manager (which TCD uses) otherwise the TCD |
|---|
| 265 | will not authenticate with the Tomcat Manager and the deployment will |
|---|
| 266 | fail. To do this, see the Tomcat Manager page. |
|---|
| 267 | </p> |
|---|
| 268 | |
|---|
| 269 | <ul> |
|---|
| 270 | <li> |
|---|
| 271 | <code>build</code>: The build folder used will be, by default, |
|---|
| 272 | <code>${build}/webapp/${path}</code>. After the end of the execution |
|---|
| 273 | of the <code>compile</code> target, the web application .WAR will be |
|---|
| 274 | located at <code>${build}/webapp/${path}.war</code>. |
|---|
| 275 | </li> |
|---|
| 276 | <li> |
|---|
| 277 | <code>webapp</code>: The directory containing the exploded web application |
|---|
| 278 | which will be compiled and validated. By default, the folder is |
|---|
| 279 | <code>myapp</code>. |
|---|
| 280 | </li> |
|---|
| 281 | <li> |
|---|
| 282 | <code>path</code>: Deployed context path of the web application, |
|---|
| 283 | by default <code>/myapp</code>. |
|---|
| 284 | </li> |
|---|
| 285 | <li> |
|---|
| 286 | <code>url</code>: Absolute URL to the Tomcat Manager web application of a |
|---|
| 287 | running Tomcat server, which will be used to deploy and undeploy the |
|---|
| 288 | web application. By default, the deployer will attempt to access |
|---|
| 289 | a Tomcat instance running on localhost, at |
|---|
| 290 | <code>http://localhost:8080/manager</code>. |
|---|
| 291 | </li> |
|---|
| 292 | <li> |
|---|
| 293 | <code>username</code>: Tomcat Manager username (user should have a role of |
|---|
| 294 | manager) |
|---|
| 295 | </li> |
|---|
| 296 | <li><code>password</code>: Tomcat Manager password.</li> |
|---|
| 297 | </ul> |
|---|
| 298 | </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> |
|---|
| 299 | Copyright © 1999-2008, Apache Software Foundation |
|---|
| 300 | </em></font></div></td></tr></table></body></html> |
|---|
