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