remm 2005/08/26 05:30:11
Modified: webapps/docs deployer-howto.xml
Log:
- Brand new deployer specs.
- Submitted by Allistair Crossley.
Revision Changes Path
1.8 +313 -164 jakarta-tomcat-catalina/webapps/docs/deployer-howto.xml
Index: deployer-howto.xml
===================================================================
RCS file: /home/cvs/jakarta-tomcat-catalina/webapps/docs/deployer-howto.xml,v
retrieving revision 1.7
retrieving revision 1.8
diff -u -r1.7 -r1.8
--- deployer-howto.xml 1 Sep 2004 22:04:28 -0000 1.7
+++ deployer-howto.xml 26 Aug 2005 12:30:11 -0000 1.8
@@ -7,174 +7,323 @@
&project;
<properties>
- <author email="[EMAIL PROTECTED]">Remy Maucherat</author>
- <title>Deployer HOW-TO</title>
+ <author>Allistair Crossley</author>
+ <title>Tomcat Web Application Deployment</title>
</properties>
<body>
-<section name="Table of Contents">
-
-<p>
-<a href="#Introduction">Introduction</a><br />
-<a href="#Context descriptors">Context XML descriptors</a><br />
-<a href="#Deploying on Tomcat startup">Deploying on Tomcat startup</a><br />
-<a href="#Deploying on a running Tomcat server">Deploying on running Tomcat
server</a><br />
-<a href="#Deploying using the Client Deployer Package">Deploying using the
Client Deployer Package</a><br />
-<blockquote>
-</blockquote>
-</p>
-
-</section>
-
-<section name="Introduction">
-
-<p>The deployer, as its name implies, allows deploying and undeploying web
-applications to the Tomcat server, either statically (the application is
-setup before the server is started), or dynamically (in conjunction with the
-Tomcat Manager web application or manipulating already deployed
applications).
-</p>
-
-</section>
-
-<section name="Context descriptors">
-
-<p>A Context XML descriptor is a fragment of XML data which contains a valid
-Context element which would normally be found in the main server
configuration
-file (conf/server.xml), and allows easy and automated manipulation
-of web applications by the various management tools available in Tomcat.
-For a given host, the Context descriptors are located in
-<code>$CATALINA_HOME/conf/[enginename]/[hostname]/foo.xml</code>. Note that
-while the name of the file is not tied to the webapp name, Tomcat will create
-Context descriptors which match the webapp name whenever it will generate a
-Context descriptor.
-</p>
-
-<p>Context descriptors allow defining all aspects and configuration
parameters
-of a Context, such as naming resources and session manager configuration.
-It should be noted that the docBase specified in the Context element can
-refer to either the .WAR or the directory which will be created when the
-.WAR is expanded or the .WAR itself.</p>
-
-</section>
-
-<section name="Deploying on Tomcat startup">
-
-<p>The webapps which are present in the host appBase will be deployed if the
-host "deployOnStartup" property is true. The deployment process is
-the following:
-<ul>
- <li>The Context XML declarations will be deployed first</li>
- <li>Expanded web applications not referenced by Context XML declarations
- will then be deployed; if they have an associated .WAR file and it is
- newer than the expanded web application, the expanded directory will
- be removed and the webapp will be redeployed from the .WAR</li>
- <li>.WAR files will be deployed</li>
-</ul>
-For each deployed web application, a matching Context XML descriptor will be
-created unless one exists already.
-</p>
-
-</section>
-
-<section name="Deploying on a running Tomcat server">
-
-<p>If the host "autoDeploy" property is true, the host will attempt to
deploy
-and update web applications dynamically, as needed. The host will need to
-have background processing enabled for automatic reloading to work, which
-is the default.</p>
-
-<p>This includes:
-<ul>
- <li>Deployment of WARs which are copied to the host appBase.</li>
- <li>Deployment of expanded web applications which are copied to the host
- appBase.</li>
- <li>Redeployment of a web application which has been deployed from a WAR
- when the WAR is updated: the expanded web application is removed,
- and the WAR is expanded again. This will not happen if the host is
- configured so that WARs are not expanded, in which case the webapp
- will be simply redeployed.</li>
- <li>Redeployment of the web application if the /WEB-INF/web.xml file is
- updated.</li>
- <li>Redeployment of the web application if the context XML file from
which
- the web application has been deployed is updated.</li>
- <li>Redeployment of the web application if a context XML file (with a
- name corresponding to the context path of the previously deployed
- application) is added in the
- <code>$CATALINA_HOME/conf/[enginename]/[hostname]/</code>
folder.</li>
- <li>Undeployment of the web application if its document base is deleted
- (on Windows, this assumes that anti locking features are enabled,
otherwise
- it is not possible to delete the resources of a running web
application).</li>
-</ul>
-Note: Web application reloading can also be configured in the loader, in
which
-case loaded classes will be tracked for changes.
-</p>
-
-</section>
-
-<section name="Deploying using the Client Deployer Package">
-
-<p>The client deployer is a package which can be used to validate, compile,
-and deploy a web application to a production or development server. It
should
-be noted that this feature uses the Tomcat manager for automatic deployment.
-</p>
-
-<p>The deployer includes the Catalina manager Ant tasks, the Jasper page
-compiler for JSP compilation before deployment, as well as a task which
-validates the webapp's deployment descriptor. The validator task (class
-<code>org.apache.catalina.ant.ValidatorTask</code>) allows only one
parameter:
-the base path of an expanded web application.</p>
-
-<p>The deployer uses an unpacked web application as input (see the list of
the
-properties used by the deployer below). A web application which
-is programatically deployed with the deployer may include Tomcat specific
-deployment configuration, by including a Context configuration XML file in
-<code>/META-INF/context.xml</code>.</p>
-
-<p>The deployer package includes a ready to use Ant script, with the
following
-targets:
-<ul>
- <li><code>compile</code> (default): Compile and validate the web
- application. This can be used standalone, and does not need a running
- Tomcat server. The compiled application will only run on the
associated
- Tomcat 5.5.x server release, and is not guaranteed to work on another
- Tomcat release, as the code generated by Jasper depends on its
runtime
- component. It should also be noted that this target will also compile
- automatically any Java source file located in the
- <code>/WEB-INF/classes</code> folder of the web application.</li>
- <li><code>deploy</code>: Deploy a web application (compiled or not) to
- a Tomcat server</li>
- <li><code>undeploy</code>: Undeploy a web application</li>
- <li><code>start</code>: Start web application</li>
- <li><code>reload</code>: Reload web application</li>
- <li><code>stop</code>: Stop web application</li>
-</ul>
-The following properties can be specified, either as system properties, or by
-using a <code>deployer.properties</code> file located in the root folder of
the
-deployer package:
-<ul>
- <li><code>build</code>: The build folder used will be, by default,
- <code>${build}/webapp${path}</code>. After the end of the execution
- of the <code>compile</code> target, the web application WAR will be
- located at <code>${build}/webapp${path}.war</code>.</li>
- <li><code>webapp</code>: Folder containing the expanded web application
- 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,
- by default <code>/myapp</code>.</li>
- <li><code>url</code>: Absolute URL to the manager web application of a
- running Tomcat server, which will be used to deploy and undeploy the
- web application. By default, the deployer will attempt to access
- a Tomcat instance running on localhost, at
- <code>http://localhost:8080/manager</code>.</li>
- <li><code>username</code>: Username to be used to connect to the Tomcat
- manager.</li>
- <li><code>password</code>: Password to be used to connect to the Tomcat
- manager.</li>
-</ul>
-</p>
-
-</section>
+ <section name="Table of Contents">
+ <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 Tomcat Client Deployer</a></li>
+ </ul>
+
+ </section>
+
+ <section name="Introduction">
+ <p>
+ Deployment is the term used for the process of installing a web
+ application (either a 3rd party WAR or your own custom web
application)
+ into the Tomcat server.
+ </p>
+ <p>
+ Web application deployment may be accomplished in a number of
ways
+ within the Tomcat server.
+ <ul>
+ <li>Statically; the web application is setup before Tomcat
is started</li>
+ <li>
+ Dynamically; in conjunction with the Tomcat Manager web
application or
+ manipulating already deployed web applications
+ </li>
+ </ul>
+ </p>
+ <p>
+ The Tomcat Manager is a tool that allows URL-based web
application
+ deployment features. There is also a tool called the Client
Deployer,
+ which is a command shell based script that interacts with the
Tomcat
+ Manager but provides additional functionality such as compiling
and
+ validating web applications as well as packaging web application
into
+ web application resource (WAR) files.
+ </p>
+ </section>
+
+ <section name="Installation">
+ <p>
+ There is no installation required for static deployment of web
+ applications as this is provided out of the box by Tomcat. Nor
is any
+ installation required for deployment functions with the Tomcat
Manager,
+ although some configuration is required as detailed in the
+ Tomcat Manager manual. An installation is however required if
you wish
+ to use the Tomcat Client Deployer (TCD).
+ </p>
+ <p>
+ The TCD is not packaged with the Tomcat core
+ distribution, and must therefore be downloaded separately from
+ the Downloads area. The download is usually labelled
+ <i>jakarta-tomcat-5.5.x-deployer</i>.
+ </p>
+ <p>
+ TCD has prerequisites of Apache Ant 1.6.2+ and a Java
installation.
+ Your environment should define an ANT_HOME environment value
pointing to
+ the root of your Ant installation, and a JAVA_HOME value
pointing to
+ your Java installation. Additionally, you should ensure Ant's ant
+ command, and the Java javac compiler command run from the
command shell
+ that your operating system provides.
+ </p>
+ <ol>
+ <li>Download the TCD distribution</li>
+ <li>
+ The TCD package need not be extracted into any existing
Tomcat
+ installation, it can be extracted to any location.
+ </li>
+ <li>Read Using the <a href="#Deploying using the Client Deployer
Package">
+ Tomcat Client Deployer</a></li>
+ </ol>
+ </section>
+
+ <section name="A word on Contexts">
+ <p>
+ In talking about deployment of web applications, the concept of a
+ <i>Context</i> is required to be understood. A Context is what
Tomcat
+ calls a web application.
+ </p>
+ <p>
+ In order to configure a Context within Tomcat a <i>Context
Descriptor</i>
+ is required. A Context Descriptor is simply an XML file that
contains
+ Tomcat related configuration for a Context, e.g naming resources
or
+ session manager configuration. In earlier versions of
+ Tomcat the content of a Context Descriptor configuration was
often stored within
+ Tomcat's primary configuration file <i>server.xml</i> but this
is now
+ discouraged (although it currently still works).
+ </p>
+ <p>
+ Context Descriptors not only help Tomcat to know how to
configure
+ Contexts but other tools such as the Tomcat Manager and TDC
often use
+ these Context Descriptors to perform their roles properly.
+ </p>
+ <p>
+ The locations for Context Descriptors are;
+ <ol>
+
<li>$CATALINA_HOME/conf/[enginename]/[hostname]/context.xml</li>
+
<li>$CATALINA_HOME/webapps/[webappname]/META-INF/context.xml</li>
+ </ol>
+ If a Context Descriptor is not provided for a Context, Tomcat
+ automatically creates one and places it in (1) with a filename of
+ [webappname].xml although if manually created, the filename need
not
+ match the web application name as Tomcat is concerned only with
the
+ Context configuration contained within the Context Descriptor
file(s).
+ </p>
+ </section>
+
+ <section name="Deployment on Tomcat startup">
+ <p>
+ If you are not interested in using the Tomcat Manager, or TCD,
+ then you'll need to deploy your web applications
+ statically to Tomcat, followed by a Tomcat startup. The location
you
+ deploy web applications to for this type of deployment is called
the
+ <code>appBase</code> which is specified per Host. You either
copy a
+ so-called <i>exploded web application</i>, i.e non-compressed,
to this
+ location, or a compressed web application resource .WAR file.
+ </p>
+ <p>
+ The web applications present in the location specified by the
Host's
+ (default Host is "localhost") <code>appBase</code> attribute
(default
+ appBase is "$CATALINA_HOME/webapps") will be deployed on Tomcat
startup
+ only if the Host's <code>deployOnStartup</code> attribute is
"true".
+ </p>
+ <p>
+ The following deployment sequence will occur on Tomcat startup
in that
+ case:
+ </p>
+ <ol>
+ <li>Any Context Descriptors will be deployed first.</li>
+ <li>
+ Exploded web applications not referenced by any Context
+ Descriptor will then be deployed. If they have an associated
+ .WAR file in the appBase and it is newer than the exploded
web application,
+ the exploded directory will be removed and the webapp will
be
+ redeployed from the .WAR
+ </li>
+ <li>.WAR files will be deployed</li>
+ </ol>
+ <p>
+ Note again that for each deployed web application, a
+ Context Descriptor will be created <i>unless one exists
already</i>.
+ </p>
+ </section>
+
+ <section name="Deploying on a running Tomcat server">
+ <p>
+ It is possible to deploy web applications to a running Tomcat
server.
+ </p>
+ <p>
+ If the Host <code>autoDeploy</code> attribute is "true", the
Host will
+ attempt to deploy and update web applications dynamically, as
needed,
+ for example if a new .WAR is dropped into the
<code>appBase</code>.
+ For this to work, the Host needs to have background processing
+ enabled which is the default configuration.
+ </p>
+
+ <p>
+ <code>autoDeploy</code> set to "true" and a running Tomcat
allows for:
+ </p>
+ <ul>
+ <li>Deployment of .WAR files copied into the Host
<code>appBase</code>.</li>
+ <li>
+ Deployment of exploded web applications which are
+ copied into the Host <code>appBase</code>.
+ </li>
+ <li>
+ Re-deployment of a web application which has already been
deployed from
+ a .WAR when the new .WAR is provided. In this case the
exploded
+ web application is removed, and the .WAR is expanded again.
+ Note that the explosion will not occur if the Host is
configured
+ so that .WARs are not exploded with a <code>unpackWARs</code>
+ attribute set to "false", in which case the web application
+ will be simply redeployed as a compressed archive.
+ </li>
+ <li>
+ Re-deployment of a web application if the /WEB-INF/web.xml
file (or any
+ other resource defined as a WatchedResource) is updated.
+ </li>
+ <li>
+ Re-deployment of a web application if the Context Descriptor
file from which
+ the web application has been deployed is updated.
+ </li>
+ <li>
+ Re-deployment of a web application if a Context Descriptor
file (with a
+ filename corresponding to the Context path of the previously
deployed
+ web application) is added to the
+ <code>$CATALINA_HOME/conf/[enginename]/[hostname]/</code>
+ directory.
+ </li>
+ <li>
+ Undeployment of a web application if its document base
(docBase)
+ is deleted. Note that on Windows, this assumes that
anti-locking
+ features (see Context configuration) are enabled, otherwise
it is not
+ 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
+ case loaded classes will be tracked for changes.
+ </p>
+ </section>
+
+ <section name="Deploying using the Tomcat Manager">
+ <p>
+ The Tomcat Manager is covered in its <a
href="manager-howto.html">own manual page</a>.
+ </p>
+ </section>
+
+ <section name="Deploying using the Client Deployer Package">
+ <p>
+ Finally, deployment of web application may be achieved using the
+ Tomcat Client Deployer. This is a package which can be used to
+ validate, compile, compress to .WAR, and deploy web applications
to
+ production or development Tomcat servers. It should be noted
that this feature
+ uses the Tomcat Manager and as such the target Tomcat server
should be
+ running.
+ </p>
+
+ <p>
+ It is assumed the user will be familar with Apache Ant for using
the TCD.
+ Apache Ant is a scripted build tool. The TCD comes pre-packaged
with a
+ build script to use. Only a modest understanding of Apache Ant is
+ required (installation as listed earlier in this page, and
familiarity
+ with using the operating system command shell and configuring
+ environment variables).
+ </p>
+
+ <p>
+ The TCD includes Ant tasks, the Jasper page compiler for JSP
compilation
+ before deployment, as well as a task which
+ validates the web application Context Descriptor. The validator
task (class
+ <code>org.apache.catalina.ant.ValidatorTask</code>) allows only
one parameter:
+ the base path of an exploded web application.
+ </p>
+
+ <p>
+ The TCD uses an exploded web application as input (see the list
of the
+ properties used below). A web application that is
programatically
+ deployed with the deployer may include a Context Desciptor in
+ <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
+ application. This can be used standalone, and does not need
a running
+ Tomcat server. The compiled application will only run on the
associated
+ Tomcat 5.5.x server release, and is not guaranteed to work
on another
+ Tomcat release, as the code generated by Jasper depends on
its runtime
+ component. It should also be noted that this target will
also compile
+ automatically any Java source file located in the
+ <code>/WEB-INF/classes</code> folder of the web
application.</li>
+ <li>
+ <code>deploy</code>: Deploy a web application (compiled or
not) to
+ a Tomcat server.
+ </li>
+ <li><code>undeploy</code>: Undeploy a web application</li>
+ <li><code>start</code>: Start web application</li>
+ <li><code>reload</code>: Reload web application</li>
+ <li><code>stop</code>: Stop web application</li>
+ </ul>
+
+ <p>
+ In order for the deployment to be configured, create a file
+ called <code>deployer.properties</code> in the TCD installation
+ 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
+ setup for the target Tomcat Manager (which TCD uses) otherwise
the TCD
+ will not authenticate with the Tomcat Manager and the deployment
will
+ fail. To do this, see the Tomcat Manager page.
+ </p>
+
+ <ul>
+ <li>
+ <code>build</code>: The build folder used will be, by
default,
+ <code>${build}/webapp/${path}</code>. After the end of the
execution
+ of the <code>compile</code> target, the web application .WAR
will be
+ located at <code>${build}/webapp/${path}.war</code>.
+ </li>
+ <li>
+ <code>webapp</code>: The directory containing the exploded
web application
+ 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,
+ by default <code>/myapp</code>.
+ </li>
+ <li>
+ <code>url</code>: Absolute URL to the Tomcat Manager web
application of a
+ running Tomcat server, which will be used to deploy and
undeploy the
+ web application. By default, the deployer will attempt to
access
+ a Tomcat instance running on localhost, at
+ <code>http://localhost:8080/manager</code>.
+ </li>
+ <li>
+ <code>username</code>: Tomcat Manager username (user should
have a role of
+ manager)
+ </li>
+ <li><code>password</code>: Tomcat Manager password.</li>
+ </ul>
+ </section>
</body>
---------------------------------------------------------------------
To unsubscribe, e-mail: [EMAIL PROTECTED]
For additional commands, e-mail: [EMAIL PROTECTED]
