Blame - webapps/docs/deployer-howto.html - portal_platform/tomcat-cms

Cheng Tang

2014-04-27 16:37:18 +0800

<html><head><META http-equiv="Content-Type" content="text/html; charset=iso-8859-1"><title>Apache Tomcat 7 (7.0.42) - Tomcat Web Application Deployment</title><meta name="author" content="Allistair Crossley"><style type="text/css" media="print">

2

.noPrint {display: none;}

3

td#mainBody {width: 100%;}

4

</style><style type="text/css">

5

code {background-color:rgb(224,255,255);padding:0 0.1em;}

6

code.attributeName, code.propertyName {background-color:transparent;}

7

</style><style type="text/css">

8

.wrapped-source code { display: block; background-color: transparent; }

9

.wrapped-source div { margin: 0 0 0 1.25em; }

10

.wrapped-source p { margin: 0 0 0 1.25em; text-indent: -1.25em; }

11

</style><style type="text/css">

12

p.notice {

13

border: 1px solid rgb(255, 0, 0);

14

background-color: rgb(238, 238, 238);

15

color: rgb(0, 51, 102);

16

padding: 0.5em;

17

margin: 1em 2em 1em 1em;

18

}

19

</style></head><body bgcolor="#ffffff" text="#000000" link="#525D76" alink="#525D76" vlink="#525D76"><table border="0" width="100%" cellspacing="0"><tr><td><a href="http://tomcat.apache.org/"><img src="./images/tomcat.gif" align="right" alt="

20

The Apache Tomcat Servlet/JSP Container

21

" border="0"></a></td><td><h1><font face="arial,helvetica,sanserif">Apache Tomcat 7</font></h1><font face="arial,helvetica,sanserif">Version 7.0.42, Jul 2 2013</font></td><td><a href="http://www.apache.org/"><img src="./images/asf-logo.gif" align="right" alt="Apache Logo" border="0"></a></td></tr></table><table border="0" width="100%" cellspacing="4"><tr><td colspan="2"><hr noshade size="1"></td></tr><tr><td width="20%" valign="top" nowrap class="noPrint"><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><li><a href="#comments_section">User Comments</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><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></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">Tomcat Javadocs</a></li><li><a href="servletapi/index.html">Servlet Javadocs</a></li><li><a href="jspapi/index.html">JSP 2.2 Javadocs</a></li><li><a href="elapi/index.html">EL 2.2 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><li><a href="tribes/introduction.html">Tribes</a></li></ul></td><td width="80%" valign="top" align="left" id="mainBody"><h1>Tomcat Web Application Deployment</h1><table border="0" cellspacing="0" cellpadding="2"><tr><td bgcolor="#525D76"><font color="#ffffff" face="arial,helvetica.sanserif"><a name="Table of Contents"></a><a name="Table_of_Contents"><strong>Table of Contents</strong></a></font></td></tr><tr><td><blockquote>

22

<ul><li><a href="#Introduction">Introduction</a></li><li><a href="#Installation">Installation</a></li><li><a href="#A_word_on_Contexts">A word on Contexts</a></li><li><a href="#Deployment_on_Tomcat_startup">Deployment on Tomcat startup</a></li><li><a href="#Deploying_on_a_running_Tomcat_server">Deploying on a running Tomcat server</a></li><li><a href="#Deploying_using_the_Tomcat_Manager">Deploying using the Tomcat Manager</a></li><li><a href="#Deploying_using_the_Client_Deployer_Package">Deploying using the Client Deployer Package</a></li></ul>

23

</blockquote></td></tr></table><table border="0" cellspacing="0" cellpadding="2"><tr><td bgcolor="#525D76"><font color="#ffffff" face="arial,helvetica.sanserif"><a name="Introduction"><strong>Introduction</strong></a></font></td></tr><tr><td><blockquote>

24

<p>

25

Deployment is the term used for the process of installing a web

26

application (either a 3rd party WAR or your own custom web application)

27

into the Tomcat server.

28

</p>

29

<p>

30

Web application deployment may be accomplished in a number of ways

31

within the Tomcat server.</p>

32

<ul>

33

<li>Statically; the web application is setup before Tomcat is started</li>

34

<li>

35

Dynamically; by directly manipulating already deployed web

36

applications (relying on <em>auto-deployment</em>

37

feature) or remotely by using the Tomcat Manager web

application

</li>

</ul>

<p>

The <a href="manager-howto.html">Tomcat Manager</a> is a web

43

application that can be used interactively (via HTML GUI) or

44

programmatically (via URL-based API) to deploy and manage web

applications.

</p>

<p>

There are a number of ways to perform deployment that rely on

49

the Manager web application. Apache Tomcat provides tasks

50

for Apache Ant build tool.

51

<a href="http://tomcat.apache.org/maven-plugin.html">Apache Tomcat Maven Plugin</a>

52

project provides integration with Apache Maven.

53

There is also a tool called the Client Deployer, which can be

54

used from a command line and provides additional functionality

55

such as compiling and validating web applications as well as

56

packaging web application into web application resource (WAR)

57

files.

58

</p>

59

</blockquote></td></tr></table><table border="0" cellspacing="0" cellpadding="2"><tr><td bgcolor="#525D76"><font color="#ffffff" face="arial,helvetica.sanserif"><a name="Installation"><strong>Installation</strong></a></font></td></tr><tr><td><blockquote>

60

<p>

61

There is no installation required for static deployment of web

62

applications as this is provided out of the box by Tomcat. Nor is any

63

installation required for deployment functions with the Tomcat Manager,

64

although some configuration is required as detailed in the

65

<a href="manager-howto.html">Tomcat Manager manual</a>.

66

An installation is however required if you wish

67

to use the Tomcat Client Deployer (TCD).

68

</p>

69

<p>

70

The TCD is not packaged with the Tomcat core

71

distribution, and must therefore be downloaded separately from

72

the Downloads area. The download is usually labelled

73

<i>apache-tomcat-7.0.x-deployer</i>.

74

</p>

75

<p>

76

TCD has prerequisites of Apache Ant 1.6.2+ and a Java installation.

77

Your environment should define an ANT_HOME environment value pointing to

78

the root of your Ant installation, and a JAVA_HOME value pointing to

79

your Java installation. Additionally, you should ensure Ant's ant

80

command, and the Java javac compiler command run from the command shell

81

that your operating system provides.

82

</p>

83

<ol>

84

<li>Download the TCD distribution</li>

85

<li>

86

The TCD package need not be extracted into any existing Tomcat

87

installation, it can be extracted to any location.

88

</li>

89

<li>Read Using the <a href="#Deploying_using_the_Client_Deployer_Package">

90

Tomcat Client Deployer</a></li>

91

</ol>

92

</blockquote></td></tr></table><table border="0" cellspacing="0" cellpadding="2"><tr><td bgcolor="#525D76"><font color="#ffffff" face="arial,helvetica.sanserif"><a name="A word on Contexts"></a><a name="A_word_on_Contexts"><strong>A word on Contexts</strong></a></font></td></tr><tr><td><blockquote>

93

<p>

94

In talking about deployment of web applications, the concept of a

95

<i>Context</i> is required to be understood. A Context is what Tomcat

96

calls a web application.

97

</p>

98

<p>

99

In order to configure a Context within Tomcat a <i>Context Descriptor</i>

100

is required. A Context Descriptor is simply an XML file that contains

101

Tomcat related configuration for a Context, e.g naming resources or

102

session manager configuration. In earlier versions of

103

Tomcat the content of a Context Descriptor configuration was often stored within

104

Tomcat's primary configuration file <i>server.xml</i> but this is now

105

discouraged (although it currently still works).

106

</p>

107

<p>

108

Context Descriptors not only help Tomcat to know how to configure

109

Contexts but other tools such as the Tomcat Manager and TCD often use

110

these Context Descriptors to perform their roles properly.

111

</p>

112

<p>

113

The locations for Context Descriptors are:

114

</p>

115

<ol>

116

<li>$CATALINA_BASE/conf/[enginename]/[hostname]/[webappname].xml</li>

117

<li>$CATALINA_BASE/webapps/[webappname]/META-INF/context.xml</li>

118

</ol>

119

<p>

120

Files in (1) are named [webappname].xml but files in (2) are named

121

context.xml. If a Context Descriptor is not provided for a Context,

122

Tomcat configures the Context using default values.

123

</p>

124

</blockquote></td></tr></table><table border="0" cellspacing="0" cellpadding="2"><tr><td bgcolor="#525D76"><font color="#ffffff" face="arial,helvetica.sanserif"><a name="Deployment on Tomcat startup"></a><a name="Deployment_on_Tomcat_startup"><strong>Deployment on Tomcat startup</strong></a></font></td></tr><tr><td><blockquote>

125

<p>

126

If you are not interested in using the Tomcat Manager, or TCD,

127

then you'll need to deploy your web applications

128

statically to Tomcat, followed by a Tomcat startup. The location you

129

deploy web applications to for this type of deployment is called the

130

<code>appBase</code> which is specified per Host. You either copy a

131

so-called <i>exploded web application</i>, i.e non-compressed, to this

132

location, or a compressed web application resource .WAR file.

133

</p>

134

<p>

135

The web applications present in the location specified by the Host's

136

(default Host is "localhost") <code>appBase</code> attribute (default

137

appBase is "$CATALINA_BASE/webapps") will be deployed on Tomcat startup

138

only if the Host's <code>deployOnStartup</code> attribute is "true".

139

</p>

140

<p>

141

The following deployment sequence will occur on Tomcat startup in that

case:

</p>

<ol>

<li>Any Context Descriptors will be deployed first.</li>

146

<li>

147

Exploded web applications not referenced by any Context

148

Descriptor will then be deployed. If they have an associated

149

.WAR file in the appBase and it is newer than the exploded web application,

150

the exploded directory will be removed and the webapp will be

151

redeployed from the .WAR

152

</li>

153

<li>.WAR files will be deployed</li>

154

</ol>

155

</blockquote></td></tr></table><table border="0" cellspacing="0" cellpadding="2"><tr><td bgcolor="#525D76"><font color="#ffffff" face="arial,helvetica.sanserif"><a name="Deploying on a running Tomcat server"></a><a name="Deploying_on_a_running_Tomcat_server"><strong>Deploying on a running Tomcat server</strong></a></font></td></tr><tr><td><blockquote>

156

<p>

157

It is possible to deploy web applications to a running Tomcat server.

158

</p>

159

<p>

160

If the Host <code>autoDeploy</code> attribute is "true", the Host will

161

attempt to deploy and update web applications dynamically, as needed,

162

for example if a new .WAR is dropped into the <code>appBase</code>.

163

For this to work, the Host needs to have background processing

164

enabled which is the default configuration.

</p>

<p>

<code>autoDeploy</code> set to "true" and a running Tomcat allows for:

169

</p>

170

<ul>

171

<li>Deployment of .WAR files copied into the Host <code>appBase</code>.</li>

172

<li>

173

Deployment of exploded web applications which are

174

copied into the Host <code>appBase</code>.

175

</li>

176

<li>

177

Re-deployment of a web application which has already been deployed from

178

a .WAR when the new .WAR is provided. In this case the exploded

179

web application is removed, and the .WAR is expanded again.

180

Note that the explosion will not occur if the Host is configured

181

so that .WARs are not exploded with a <code>unpackWARs</code>

182

attribute set to "false", in which case the web application

183

will be simply redeployed as a compressed archive.

184

</li>

185

<li>

186

Re-loading of a web application if the /WEB-INF/web.xml file (or

187

any other resource defined as a WatchedResource) is updated.

188

</li>

189

<li>

190

Re-deployment of a web application if the Context Descriptor

191

file from which the web application has been deployed is

updated.

</li>

<li>

Re-deployment of dependent web applications if the global or

196

per-host Context Descriptor file used by the web application is

updated.

</li>

<li>

Re-deployment of a web application if a Context Descriptor file (with a

201

filename corresponding to the Context path of the previously deployed

202

web application) is added to the

203

<code>$CATALINA_BASE/conf/[enginename]/[hostname]/</code>

directory.

</li>

<li>

Undeployment of a web application if its document base (docBase)

208

is deleted. Note that on Windows, this assumes that anti-locking

209

features (see Context configuration) are enabled, otherwise it is not

210

possible to delete the resources of a running web application.

</li>

</ul>

<p>

Note that web application reloading can also be configured in the loader, in which

215

case loaded classes will be tracked for changes.

216

</p>

217

</blockquote></td></tr></table><table border="0" cellspacing="0" cellpadding="2"><tr><td bgcolor="#525D76"><font color="#ffffff" face="arial,helvetica.sanserif"><a name="Deploying using the Tomcat Manager"></a><a name="Deploying_using_the_Tomcat_Manager"><strong>Deploying using the Tomcat Manager</strong></a></font></td></tr><tr><td><blockquote>

218

<p>

219

The Tomcat Manager is covered in its <a href="manager-howto.html">own manual page</a>.

220

</p>

221

</blockquote></td></tr></table><table border="0" cellspacing="0" cellpadding="2"><tr><td bgcolor="#525D76"><font color="#ffffff" face="arial,helvetica.sanserif"><a name="Deploying using the Client Deployer Package"></a><a name="Deploying_using_the_Client_Deployer_Package"><strong>Deploying using the Client Deployer Package</strong></a></font></td></tr><tr><td><blockquote>

222

<p>

223

Finally, deployment of web application may be achieved using the

224

Tomcat Client Deployer. This is a package which can be used to

225

validate, compile, compress to .WAR, and deploy web applications to

226

production or development Tomcat servers. It should be noted that this feature

227

uses the Tomcat Manager and as such the target Tomcat server should be

running.

</p>

<p>

It is assumed the user will be familiar with Apache Ant for using the TCD.

233

Apache Ant is a scripted build tool. The TCD comes pre-packaged with a

234

build script to use. Only a modest understanding of Apache Ant is

235

required (installation as listed earlier in this page, and familiarity

236

with using the operating system command shell and configuring

237

environment variables).

</p>

<p>

The TCD includes Ant tasks, the Jasper page compiler for JSP compilation

242

before deployment, as well as a task which

243

validates the web application Context Descriptor. The validator task (class

244

<code>org.apache.catalina.ant.ValidatorTask</code>) allows only one parameter:

245

the base path of an exploded web application.

</p>

<p>

The TCD uses an exploded web application as input (see the list of the

250

properties used below). A web application that is programmatically

251

deployed with the deployer may include a Context Descriptor in

252

<code>/META-INF/context.xml</code>.

</p>

<p>

The TCD includes a ready-to-use Ant script, with the following targets:

</p>

<ul>

<li>

<code>compile</code> (default): Compile and validate the web

261

application. This can be used standalone, and does not need a running

262

Tomcat server. The compiled application will only run on the associated

263

<em>Tomcat X.Y.Z</em> server release, and is not guaranteed to work

264

on another Tomcat release, as the code generated by Jasper depends on its runtime

265

component. It should also be noted that this target will also compile

266

automatically any Java source file located in the

267

<code>/WEB-INF/classes</code> folder of the web application.</li>

268

<li>

269

<code>deploy</code>: Deploy a web application (compiled or not) to

270

a Tomcat server.

271

</li>

272

<li><code>undeploy</code>: Undeploy a web application</li>

273

<li><code>start</code>: Start web application</li>

274

<li><code>reload</code>: Reload web application</li>

275

<li><code>stop</code>: Stop web application</li>

</ul>

<p>

In order for the deployment to be configured, create a file

280

called <code>deployer.properties</code> in the TCD installation

281

directory root. In this file, add the following name=value pairs per

line:

</p>

<p>

Additionally, you will need to ensure that a user has been

287

setup for the target Tomcat Manager (which TCD uses) otherwise the TCD

288

will not authenticate with the Tomcat Manager and the deployment will

289

fail. To do this, see the Tomcat Manager page.

</p>

<ul>

<li>

<code>build</code>: The build folder used will be, by default,

295

<code>${build}/webapp/${path}</code>. After the end of the execution

296

of the <code>compile</code> target, the web application .WAR will be

297

located at <code>${build}/webapp/${path}.war</code>.

298

</li>

299

<li>

300

<code>webapp</code>: The directory containing the exploded web application

301

which will be compiled and validated. By default, the folder is

<code>myapp</code>.

</li>

<li>

<code>path</code>: Deployed context path of the web application,

306

by default <code>/myapp</code>.

307

</li>

308

<li>

309

<code>url</code>: Absolute URL to the Tomcat Manager web application of a

310

running Tomcat server, which will be used to deploy and undeploy the

311

web application. By default, the deployer will attempt to access

312

a Tomcat instance running on localhost, at

313

<code>http://localhost:8080/manager/text</code>.

314

</li>

315

<li>

316

<code>username</code>: Tomcat Manager username (user should have a role of

317

manager-script)

318

</li>

319

<li><code>password</code>: Tomcat Manager password.</li>

320

</ul>

321

</blockquote></td></tr></table></td></tr><tr class="noPrint"><td width="20%" valign="top" nowrap class="noPrint"></td><td width="80%" valign="top" align="left"><table border="0" cellspacing="0" cellpadding="2"><tr><td bgcolor="#525D76"><font color="#ffffff" face="arial,helvetica.sanserif"><a name="comments_section" id="comments_section"><strong>Comments</strong></a></font></td></tr><tr><td><blockquote><p class="notice"><strong>Notice: </strong>This comments section collects your suggestions

322

on improving documentation for Apache Tomcat.<br><br>

323

If you have trouble and need help, read

324

<a href="http://tomcat.apache.org/findhelp.html">Find Help</a> page

325

and ask your question on the tomcat-users

326

<a href="http://tomcat.apache.org/lists.html">mailing list</a>.

327

Do not ask such questions here. This is not a Q&A section.<br><br>

328

The Apache Comments System is explained <a href="/tomcat-7.0-doc/comments.html">here</a>.

329

Comments may be removed by our moderators if they are either

330

implemented or considered invalid/off-topic.</p><script type="text/javascript"><![CDATA[//><!--

331

var comments_shortname = 'tomcat';

332

var comments_identifier = 'http://tomcat.apache.org/tomcat-7.0-doc/deployer-howto.html';

333

(function(w, d) {

334

if (w.location.hostname.toLowerCase() == "tomcat.apache.org") {

335

d.write('<div id="comments_thread"><\/div>');

336

var s = d.createElement('script');

337

s.type = 'text/javascript';

338

s.async = true;

339

s.src = 'https://comments.apache.org/show_comments.lua?site=' + comments_shortname + '&page=' + comments_identifier;

340

(d.getElementsByTagName('head')[0] || d.getElementsByTagName('body')[0]).appendChild(s);

341

}

342

else {

343

d.write('<div id="comments_thread"><strong>Comments are disabled for this page at the moment.<\/strong><\/div>');

344

}

345

})(window, document);

346

//--><!]]></script></blockquote></td></tr></table></td></tr><tr><td colspan="2"><hr noshade size="1"></td></tr><tr><td colspan="2"><div align="center"><font color="#525D76" size="-1"><em>

347

348

</em></font></div></td></tr></table></body></html>