tomcat-users mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Lionel Farbos <>
Subject Validation of HowTo Deploy
Date Mon, 23 May 2005 17:12:07 GMT
2nd test with the doc HTML inside...


Because there is a lot of informations on several documents for deploying a webapp in Tomcat,
it is difficult to define a simple and standard way to do it on a production server.
Moreover, the deployment is different with Tomcat 3, 4, 5.0 or 5.5

So I decided to initialize a document which would be available for all Tomcat versions >=

If you have a well knowledge of Tomcat in a production environment,
Can you help me to validate (correct and/or complete) a simple document like the one attach

Notes : 
- The goal of this document is only to be a "as simple as possible" starting point for this
- I'm not sure the "re-deployment" paragraph when Automatic deployment is disabled is correct

In advance, thank you.

<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
  <meta content="text/html; charset=ISO-8859-1"
  <title>Howto deploy</title>
<div style="text-align: center;">
<p><big style="text-decoration: underline;">HOWTO deploy a webapp on a
Tomcat production server</big></p>
Currently, when you want to deploy your webapp as a standard way on a
Tomcat production server, you have to take informations in several
documents (even threads in mailing list).<br>
The goal of this document is to describe a way that is as simple and
standard as
possible to do this, in a single document and with a concrete example
(to avoid misunderstanding).<br>
For more details, you'll have to follow some links (at the end of this
<a href="#I_The_context">I) The context</a><br>
<a href="#II_The_furnitures">II) The furnitures</a><br>
&nbsp;&nbsp;&nbsp; <a href="#II.1_the_war">II.1) the .war file</a><br>
&nbsp;&nbsp;&nbsp; <a href="#II.2_an_external_config_File">II.2) an
external config file</a><br>
<a href="#III_The_deployment">III) The deployment</a><br>
&nbsp;&nbsp;&nbsp; <a href="#III.1_on_the_localhost_HOST">III.1) on
the localhost HOST</a><br>
&nbsp;&nbsp;&nbsp; <a href="#III.2_on_a_custom_Virtual_Host">III.2)
on a custom Virtual Host</a><br>
&nbsp;&nbsp;&nbsp; <a href="#III.3_on_a_custom_Virtual_Host">III.3)
on a custom Virtual Host as Context ROOT</a><br>
&nbsp;&nbsp;&nbsp; <a href="#III.4_The_re-deployment">III.4) The
<a href="#IV_The_static_files">IV) The static files</a><br>
&nbsp;&nbsp;&nbsp; <a href="#IV.1_delivered_by_Tomcat">IV.1) delivered
by Tomcat</a><br>
&nbsp;&nbsp;&nbsp; <a href="#IV.2_delivered_by_Apache">IV.2) delivered
by Apache</a><br>
<a href="#V_Some_links">V) Some links</a><br>
<h1><a name="I_The_context"></a><span
 style="font-weight: bold; text-decoration: underline;"></span><span
 style="font-weight: normal;">I) The context</span></h1>
- You are in a development team. You produce a webapp and have to
provide it to an exploitation team. So, you don't have access to the
pre-production and production servers.<br>
- A production server is a machine that must work all the time
- This document supposes you are using Tomcat Servers &gt;= 5.5.7<br>
Because there is only one set of documentations for all Tomcat 5.x
versions but it can be bugs on certain versions, this document try to
indicate the correct way for each Tomcat version.<br>
- As in Tomcat documentations, <span style="font-style: italic;">the
descriptions below uses the variable name $CATALINA_HOME to refer to
the directory into which you have installed Tomcat5</span>.<br>
<h1><a name="II_The_furnitures"></a><span
 style="font-weight: bold; text-decoration: underline;"></span><span
 style="font-weight: normal;">II) The furnitures</span></h1>
<h2><a name="II.1_the_war"></a><span style="font-weight: bold;"></span><span
 style="font-weight: normal;">II.1) the .war file<br>
You must package your web application in a single piece :
The content of this package is :<br>
META-INF/MANIFEST.MF&nbsp;&nbsp; #The manifest file<br>
WEB-INF/lib/&nbsp;&nbsp; &nbsp;&nbsp; &nbsp;&nbsp; &nbsp;&nbsp;
&nbsp;&nbsp; &nbsp;&nbsp; &nbsp;&nbsp; &nbsp;&nbsp; &nbsp;&nbsp;
the libraries needed for your webapp that are not present in the tomcat
commons directories <br>
WEB-INF/classes&nbsp;&nbsp; &nbsp;&nbsp; &nbsp;&nbsp; &nbsp;&nbsp;
&nbsp;&nbsp; &nbsp;&nbsp; &nbsp;&nbsp;&nbsp; #All your personal
for the dynamic of the site<br>
WEB-INF/web.xml&nbsp;&nbsp; &nbsp;&nbsp; &nbsp;&nbsp; &nbsp;&nbsp;
&nbsp;&nbsp; &nbsp;&nbsp; #The config file for your webapp<br>
&lt;static and/or JSP files&gt;&nbsp;&nbsp; &nbsp;&nbsp; &nbsp;&nbsp;
&nbsp; #All your static files (.html, .js, .css, .jpg, .gif, .png,
.ico, ...)<br>
This file concerns only development needs and can be the same for test,
pre-production or production servers.<br>
Note :<br>
For more details on libraries to be present in the war file and the
ones in
tomcat commons directories, see the <a
<h2><a name="II.2_an_external_config_File"></a><span
 style="font-weight: bold;"></span><span style="font-weight: normal;">II.2)
an external config File</span></h2>
All your webapp properties can be put in the WEB-INF/web.xml file. But,
if some properties are handled by the Tomcat context administrators,
they must be set in an external properties file named, in the
documentations, the context.xml file. <br>
Moreover, this file provides the complete setup for your Tomcat Context.<br>
The syntax for the context.xml is documented within :<a
This file can be inserted in the war (under META-INF/context.xml) but, <br>
if you have to describe some properties which can be modified by the
exploitation team, it is easier (for administrators) to use it as an
external file.<br>
A simple example :<br>
I want to define a dataSource and a Home directory for my webapp (these
properties can be modified by the exploitation team on exploitation
needs (change of BDD password,...), different values on pre-production
or production servers), so my context file is :<br>
&lt;Context path="/myWebApp" docBase="myWebApp.war" debug="1"&gt;<br>
&nbsp; &lt;Resource auth="Container" name="jdbc/myBaseDB"
type="javax.sql.DataSource" driverClassName=""<br>
&nbsp;&nbsp;&nbsp; &nbsp;&nbsp; &nbsp;&nbsp; &nbsp;&nbsp;
&nbsp;&nbsp;&nbsp; &nbsp;&nbsp;&nbsp; maxIdle="30" maxWait="10000"
&nbsp; &lt;Parameter name="BASE_DIR" value="/usr/web/myWebApp"
Note :<br>
The Context.docBase you define is an absolute path or relatif path
under Host.appBase. <br>
When you deploy a war, you must define the name of
this war.<br>
If Host.unpackWARs="true", this war will be expanded.<br>
So, the exploitation team can modify everything here without touching
<h1><a name="III_The_deployment"></a><span style="font-weight: normal;">III)
The deployment</span></h1>
Thanks to the <a
you can deploy your webapp in the Tomcat server without restarting it :
the server and other services will not be interrupted.<br>
Note : The manager has "memory leaks" (see <a
so, sometimes, you'll have to restart the entire Tomcat Server.<br>
In the default Tomcat installation (inside server.xml), there is <br>
- one
Engine (Catalina), <br>
- with one Host inside (localhost) <br>
The manager
webapp is deployed thanks to
but you have to add a manager role and manager user in
Then, you can access the localhost HTML Manager within
With the default installation, Tomcat is configured with <a
Application Deployment</a>. <br>
Because of deployOnStartup="true", autoDeploy="true" and
deployXML="true", this is good for development needs but not for
production servers. More details below.<br>
<h2 style="font-weight: normal;"><a name="III.1_on_the_localhost_HOST"></a>III.1)
on the localhost HOST</h2>
You have to deploy your webapp named myWebApp.war with the config file
named myWebApp.xml under the Virtual Host localhost.<br>
So, consider your webapp in /tmp/myWebApp.xml and /tmp/myWebApp.war<br>
Then, with the localhost manager, you deploy :<br>
Context Path (Optional) = /myWebApp<br>
XML Configuration file URL =
&nbsp;&nbsp; (or http://&lt;a
remote host&gt;/myWebApp.xml)<br>
WAR or directory URL =
&nbsp;&nbsp; &nbsp;&nbsp;
&nbsp;&nbsp; &nbsp;&nbsp; (or http://&lt;a remote host&gt;/myWebApp.war)<br>
- In the example above&nbsp; :<br>
/tmp/myWebApp.xml is copied in
$CATALINA_HOME/conf/&lt;Engine&gt;/localhost/ with default value of
/tmp/myWebApp.war is copied in &lt;Host.appBase&gt; with default value
and, because of unpackWARs="true" in Host localhost, myWebApp.war is
expanded in $CATALINA_HOME/webapps/myWebApp/<br>
- the name of the war and the name of the Context file must be the
- the Context Path declared in the Manager and the Context path
attribute (in myWebApp.xml) must be the same.<br>
If these 2 conditions are not verified, the manager will fail to deploy
the webapp. <br>
In certain cases, the Context can be accessible but the Context
parameters (from the context file) are
- If you want to deploy from a command script, you can do :<br>
use the ant tasks (see <a
or, if ant is not installed, <br>
wget -q
(see <a
Manager Commands</a>)<br>
<h2 style="font-weight: normal;"><a
 name="III.2_on_a_custom_Virtual_Host"></a>III.2) on a
custom Virtual Host</h2>
For example, you want your webapp to be accessed via
1) You have to declare a new Host in $CATALINA_HOME/conf/server.xml
a custom Application Base Directory.<br>
More details here : <a
For example :<br>
&lt;Host name="myVHost" appBase="/usr/web/myVHost" unpackWARs="true"&gt;<br>
Notes :<br>
- it is better to declare a new appBase for your Host (rather than
webapps), because your webapps will be partitioned in each Virtual Host
and you will have better control on the webapps deployed on vhosts.<br>
- Because of Automatic Application Deployment (and the values
deployOnStartup="true", autoDeploy="true", deployXML="true"), your
application will be automatically re-deployed when updated (see <a
details</a>). This is good for development needs but not on a
production server. On a production server, it is better to deploy the
webapp when the administrator decide it; so, prefer Host with
deployOnStartup="false", and autoDeploy="false". Moreover, the
administrator wants its Context values to be THE reference, so prefer
So, the Host on production server become :<br>
&lt;Host name="myVHost" appBase="/usr/web/myVHost" unpackWARs="true"<br>
autoDeploy="false" deployOnStartup="false" deployXML="false"&gt;<br>
2) You have to configure a Manager in this Host.<br>
copy $CATALINA_HOME/conf/Catalina/localhost/manager.xml in
Notes : <br>
- After the declaration of the Host and the 1st Tomcat restart,
the directory $CATALINA_HOME/conf/Catalina/myVHost/ is automatically
- You can also configure the manager Context within the Host
configuration in your Tomcat server.xml. You can also restrict the
access to this manager by IP address (see Remote*Valves <a
and <a
3) Now, you can access your virtual host manager :
and deploy your Context with it.<br>
You deploy like detailed <a href="#III.1_in_the_localhost_HOST">above</a>,
then you can access your webapp within virtual host :
<h2 style="font-weight: normal;"><a
 name="III.3_on_a_custom_Virtual_Host"></a>III.3) on a
custom Virtual Host as Context Root</h2>
For example, you want your webapp to be accessed via
1) rename myWebApp.war in ROOT.war<br>
2) rename myWebApp.xml in ROOT.xml<br>
3) in ROOT.xml, replace path="/myWebApp" with path=""<br>
4) when deploy with Manager, precise :<br>
<h2 style="font-weight: normal;"><a name="III.4_The_re-deployment"></a>III.4)
The re-deployment</h2>
For example, when you have deployed your webapp for the first time and
you want to upgrade it.<br>
Automatic deployment is disabled, so, even if you update the war in <span
 style="font-style: italic;">Host.appBase</span> <br>
or the context.xml file in
$CATALINA_HOME/conf/&lt;Engine&gt;/&lt;Host&gt;/, <br>
the webapp need a undeploy/deploy to be upgraded.<br>
As undeploy delete <br>
the context.xml copy<br>
the .war file copy<br>
the expanded directory<br>
you need to take your upgraded version in the reference directory (/tmp
in the example above)<br>
If Automatic deployment is not disabled, see <a
deployer documentation</a> for more details.<br>
<h1 style="font-weight: normal;"><a name="IV_The_static_files"></a>IV)
The static files</h1>
As described <a href="#II.1_the_war">above</a>, all the static files
are packaged in the war file.<br>
When deployed with the manager, these statics files can be deployed in
&lt;Host.appBase&gt;/&lt;name of the war&gt;/ if the unpackWARs Host
attribute is set to true.<br>
<h2 style="font-weight: normal;"><a name="IV.1_delivered_by_Tomcat"></a>IV.1)
delivered by Tomcat</h2>
As Tomcat 5.5 is better than older Tomcat versions and near to
apache server for delivering static files (see <a
<a href=""></a>),
the simplest solution is to decide that Tomcat will handle all the
requests :
static files (+ servlets + JSP)<br>
That way, you only need a Tomcat server to have your webapp online
and you can deploy with Manager as explained above.<br>
Note :<br>
If you want to cluster your tomcat servers, you can choose apache
servers and mod_jk for load-balancing and failover,<br>
but, in this case, not for delivering static files.<br>
<h2 style="font-weight: normal;"><a name="IV.2_delivered_by_Apache"></a>IV.2)
delivered by Apache</h2>
If you have, in front end, apache servers for load-balancing/failover,
SSL, some apache features, security reasons, ...<br>
and you want to use them to deliver static files (to reduce the Tomcat
Servers' load)<br>
you can't deploy/undeploy only with the manager.<br>
In this case, your Apache HTTP servers and your Tomcat servers are
probably located on different hosts.<br>
So, you must put your static files :<br>
- on a shared directory like an NFS mount<br>
- or in Apache local directory (but not necessarily in Tomcat local
1) If you choose NFS mount, you can't deploy/undeploy with Tomcat
Manager because when you undeploy with Manager, the "war unpacked
directory" is deleted. So, your static files will be displayed as "404
Not Found" even
by the Tomcat clusters...<br>
So, this approach can't be a good one with Tomcat5.5 and Manager.<br>
2) If you choose Apache local directory, your deployments have to be
set in 2 phases :<br>
war re-deployed in Apache server (for static files)<br>
war re-deployed in Tomcat server (for dynamic behavior)<br>
But, in this approach, your static files will be desynchronized during
the redeployment on each cluster ...<br>
<span style="font-weight: bold; text-decoration: underline;">Conclusion</span>
I think that, with Tomcat5.5, there is no other good solution that
delivering static files with Tomcat.<br>
<h1 style="font-weight: normal;"><a name="V_Some_links"></a>V) Some
For more details on the points described here, see the more complete
documentations :<br>
<a href=""></a><br>
<a href=""></a><br>

To unsubscribe, e-mail:
For additional commands, e-mail:

View raw message