Context Navigation

← Previous Revision
Latest Revision
Next Revision →
Blame
Revision Log

deployer-howto.html @ 245

Last change on this file since 245 was 66, checked in by waue, 16 years ago
NutchEz - an easy way to nutch
File size: 20.5 KB

Line
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>

Note: See TracBrowser for help on using the repository browser.

Context Navigation

source: nutchez-0.1/tomcat/webapps/docs/deployer-howto.html @ 245

Download in other formats: