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

Last change on this file since 98 was 66, checked in by waue, 16 years ago

NutchEz - an easy way to nutch
File size: 18.1 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><!--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 &copy; 1999-2008, Apache Software Foundation
299        </em></font></div></td></tr></table></body></html>
Note: See TracBrowser for help on using the repository browser.