Return-Path: Delivered-To: apmail-jakarta-tomcat-user-archive@www.apache.org Received: (qmail 35440 invoked from network); 23 May 2005 17:44:47 -0000 Received: from hermes.apache.org (HELO mail.apache.org) (209.237.227.199) by minotaur.apache.org with SMTP; 23 May 2005 17:44:47 -0000 Received: (qmail 94543 invoked by uid 500); 23 May 2005 17:12:31 -0000 Delivered-To: apmail-jakarta-tomcat-user-archive@jakarta.apache.org Received: (qmail 94523 invoked by uid 500); 23 May 2005 17:12:30 -0000 Mailing-List: contact tomcat-user-help@jakarta.apache.org; run by ezmlm Precedence: bulk List-Unsubscribe: List-Help: List-Post: List-Id: "Tomcat Users List" Reply-To: "Tomcat Users List" Delivered-To: mailing list tomcat-user@jakarta.apache.org Received: (qmail 94504 invoked by uid 99); 23 May 2005 17:12:30 -0000 X-ASF-Spam-Status: No, hits=0.6 required=10.0 tests=USERPASS X-Spam-Check-By: apache.org Received-SPF: neutral (hermes.apache.org: local policy) Received: from mh2.cvf.fr (HELO mh2.cvf.fr) (213.56.76.234) by apache.org (qpsmtpd/0.28) with ESMTP; Mon, 23 May 2005 10:12:28 -0700 Received: from [10.33.99.113] (helo=ms.int33.cvf) by mh2.cvf.fr with esmtp for id 1DaGTZ-000437-00; Mon, 23 May 2005 19:12:25 +0200 Received: from [127.0.0.1] (helo=cocarde2.dev33.cvf) by ms.int33.cvf with smtp id 1DaGTZ-0007qK-00 for ; Mon, 23 May 2005 19:12:25 +0200 Date: Mon, 23 May 2005 19:12:07 +0200 From: Lionel Farbos To: tomcat-user@jakarta.apache.org Subject: Validation of HowTo Deploy Message-Id: <20050523191207.69d53b05.lionel.farbos@free.fr> Organization: free X-Mailer: Sylpheed version 1.0.3 (GTK+ 1.2.10; i686-pc-linux-gnu) Mime-Version: 1.0 Content-Type: text/plain; charset=US-ASCII Content-Transfer-Encoding: 7bit X-complaints-to: abuse@cvf.fr X-Virus-Checked: Checked X-Spam-Rating: minotaur.apache.org 1.6.2 0/1000/N 2nd test with the doc HTML inside... Hi, 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 >= 5.5.7 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 theme. - I'm not sure the "re-deployment" paragraph when Automatic deployment is disabled is correct ... In advance, thank you. Regards. Howto deploy

HOWTO deploy a webapp on a Tomcat production server

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).
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).
For more details, you'll have to follow some links (at the end of this document).

I) The context
II) The furnitures
    II.1) the .war file
    II.2) an external config file
III) The deployment
    III.1) on the localhost HOST
    III.2) on a custom Virtual Host
    III.3) on a custom Virtual Host as Context ROOT
    III.4) The re-deployment
IV) The static files
    IV.1) delivered by Tomcat
    IV.2) delivered by Apache
V) Some links

I) The context

- 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.
- A production server is a machine that must work all the time (24x7).
- This document supposes you are using Tomcat Servers >= 5.5.7
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.
- As in Tomcat documentations, the descriptions below uses the variable name $CATALINA_HOME to refer to the directory into which you have installed Tomcat5.

II) The furnitures

II.1) the .war file

You must package your web application in a single piece : myWebApp.war.

The content of this package is :
META-INF/
META-INF/MANIFEST.MF   #The manifest file
WEB-INF/
WEB-INF/lib/                           #All the libraries needed for your webapp that are not present in the tomcat commons directories
WEB-INF/classes                      #All your personal classes for the dynamic of the site
WEB-INF/web.xml                  #The config file for your webapp
<static and/or JSP files>         #All your static files (.html, .js, .css, .jpg, .gif, .png, .ico, ...)

This file concerns only development needs and can be the same for test, pre-production or production servers.
Note :
For more details on libraries to be present in the war file and the ones in tomcat commons directories, see the ClassLoader Howto

II.2) an external config File

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.
Moreover, this file provides the complete setup for your Tomcat Context.

The syntax for the context.xml is documented within : http://jakarta.apache.org/tomcat/tomcat-5.5-doc/config/context.html

This file can be inserted in the war (under META-INF/context.xml) but,
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.

A simple example :
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 :

<Context path="/myWebApp" docBase="myWebApp.war" debug="1">
<Resource auth="Container" name="jdbc/myBaseDB" type="javax.sql.DataSource" driverClassName="org.gjt.mm.mysql.Driver"
url="jdbc:mysql://mySQLServer:3306/myBase?autoReconnect=true"username="myUser" password="secret"
maxIdle="30" maxWait="10000" maxActive="4"/>
<Parameter name="BASE_DIR" value="/usr/web/myWebApp" override="false"/>
</Context>

Note :
The Context.docBase you define is an absolute path or relatif path under Host.appBase.
When you deploy a war, you must define the name of this war.
If Host.unpackWARs="true", this war will be expanded.

So, the exploitation team can modify everything here without touching myWebApp.war.

III) The deployment

Thanks to the manager, you can deploy your webapp in the Tomcat server without restarting it : the server and other services will not be interrupted.
Note : The manager has "memory leaks" (see http://jakarta.apache.org/tomcat/faq/deployment.html#deployMemIncrease),
so, sometimes, you'll have to restart the entire Tomcat Server.

In the default Tomcat installation (inside server.xml), there is
- one Engine (Catalina),
- with one Host inside (localhost)
The manager webapp is deployed thanks to $TOMCAT_HOME/conf/Catalina/localhost/manager.xml
but you have to add a manager role and manager user in $TOMCAT_HOME/conf/tomcat-users.xml
Then, you can access the localhost HTML Manager within http://localhost:8080/manager/html

With the default installation, Tomcat is configured with Automatic Application Deployment.
Because of deployOnStartup="true", autoDeploy="true" and deployXML="true", this is good for development needs but not for production servers. More details below.

III.1) on the localhost HOST

You have to deploy your webapp named myWebApp.war with the config file named myWebApp.xml under the Virtual Host localhost.

So, consider your webapp in /tmp/myWebApp.xml and /tmp/myWebApp.war
Then, with the localhost manager, you deploy :
Context Path (Optional) = /myWebApp
XML Configuration file URL = file:///tmp/myWebApp.xml (or http://<a remote host>/myWebApp.xml)
WAR or directory URL = file:///tmp/myWebApp.war (or http://<a remote host>/myWebApp.war)

Notes:
- In the example above :
/tmp/myWebApp.xml is copied in $CATALINA_HOME/conf/<Engine>/localhost/ with default value of <Engine>=Catalina
/tmp/myWebApp.war is copied in <Host.appBase> with default value of <Host.appBase>=$CATALINA_HOME/webapps
and, because of unpackWARs="true" in Host localhost, myWebApp.war is expanded in $CATALINA_HOME/webapps/myWebApp/
- the name of the war and the name of the Context file must be the same,
- the Context Path declared in the Manager and the Context path attribute (in myWebApp.xml) must be the same.
If these 2 conditions are not verified, the manager will fail to deploy the webapp.
In certain cases, the Context can be accessible but the Context parameters (from the context file) are not.
- If you want to deploy from a command script, you can do :
use the ant tasks (see http://jakarta.apache.org/tomcat/tomcat-5.5-doc/manager-howto.html#Executing%20Manager%20Commands%20With%20Ant)
or, if ant is not installed,
wget -q http://tomcat:tomcat@localhost:8080/manager/deploy?config=file:///tmp/myWebApp.xml&war=file:///tmp/myWebApp.war&path=/myWebApp (see Supported Manager Commands)

III.2) on a custom Virtual Host

For example, you want your webapp to be accessed via http://myVHost:8080/myWebApp/servlet/init

1) You have to declare a new Host in $CATALINA_HOME/conf/server.xml with a custom Application Base Directory.
More details here : http://jakarta.apache.org/tomcat/tomcat-5.5-doc/config/host.html
For example :
<Host name="myVHost" appBase="/usr/web/myVHost" unpackWARs="true">
</Host>

Notes :
- 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.
- Because of Automatic Application Deployment (and the values deployOnStartup="true", autoDeploy="true", deployXML="true"), your application will be automatically re-deployed when updated (see more details). 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 deployXML="false".
So, the Host on production server become :
<Host name="myVHost" appBase="/usr/web/myVHost" unpackWARs="true"
autoDeploy="false" deployOnStartup="false" deployXML="false">
</Host>

2) You have to configure a Manager in this Host.
copy $CATALINA_HOME/conf/Catalina/localhost/manager.xml in $CATALINA_HOME/conf/Catalina/myVHost/

Notes :
- After the declaration of the Host and the 1st Tomcat restart, the directory $CATALINA_HOME/conf/Catalina/myVHost/ is automatically created.
- 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 here and there)

3) Now, you can access your virtual host manager : http://myVHost:8080/manager/html
and deploy your Context with it.
You deploy like detailed above, then you can access your webapp within virtual host : http://myVHost:8080/myWebApp/servlet/init

III.3) on a custom Virtual Host as Context Root

For example, you want your webapp to be accessed via http://myVHost:8080/servlet/init

1) rename myWebApp.war in ROOT.war
2) rename myWebApp.xml in ROOT.xml
3) in ROOT.xml, replace path="/myWebApp" with path=""
4) when deploy with Manager, precise :
config=file:///tmp/ROOT.xml
war=file:///tmp/ROOT.war
path=/

III.4) The re-deployment

For example, when you have deployed your webapp for the first time and you want to upgrade it.

Automatic deployment is disabled, so, even if you update the war in Host.appBase
or the context.xml file in $CATALINA_HOME/conf/<Engine>/<Host>/,
the webapp need a undeploy/deploy to be upgraded.

As undeploy delete
the context.xml copy
the .war file copy
the expanded directory
you need to take your upgraded version in the reference directory (/tmp in the example above)

If Automatic deployment is not disabled, see the deployer documentation for more details.

IV) The static files

As described above, all the static files are packaged in the war file.
When deployed with the manager, these statics files can be deployed in <Host.appBase>/<name of the war>/ if the unpackWARs Host attribute is set to true.

IV.1) delivered by Tomcat

As Tomcat 5.5 is better than older Tomcat versions and near to apache server for delivering static files (see http://jakarta.apache.org/tomcat/faq/performance.html#faster, http://cvs.apache.org/~woolfel/benchmark_summary.pdf),
the simplest solution is to decide that Tomcat will handle all the requests : static files (+ servlets + JSP)

That way, you only need a Tomcat server to have your webapp online and you can deploy with Manager as explained above.

Note :
If you want to cluster your tomcat servers, you can choose apache servers and mod_jk for load-balancing and failover,
but, in this case, not for delivering static files.

IV.2) delivered by Apache

If you have, in front end, apache servers for load-balancing/failover, SSL, some apache features, security reasons, ...
and you want to use them to deliver static files (to reduce the Tomcat Servers' load)
you can't deploy/undeploy only with the manager.

In this case, your Apache HTTP servers and your Tomcat servers are probably located on different hosts.
So, you must put your static files :
- on a shared directory like an NFS mount
- or in Apache local directory (but not necessarily in Tomcat local directory)

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...
So, this approach can't be a good one with Tomcat5.5 and Manager.

2) If you choose Apache local directory, your deployments have to be set in 2 phases :
war re-deployed in Apache server (for static files)
war re-deployed in Tomcat server (for dynamic behavior)
But, in this approach, your static files will be desynchronized during the redeployment on each cluster ...

Conclusion :
I think that, with Tomcat5.5, there is no other good solution that delivering static files with Tomcat.

V) Some links

For more details on the points described here, see the more complete documentations :
http://jakarta.apache.org/tomcat/tomcat-5.5-doc/deployer-howto.html
http://jakarta.apache.org/tomcat/tomcat-5.5-doc/manager-howto.html
http://jakarta.apache.org/tomcat/tomcat-5.5-doc/class-loader-howto.html
http://jakarta.apache.org/tomcat/tomcat-5.5-doc/config/host.html
http://jakarta.apache.org/tomcat/tomcat-5.5-doc/config/context.html
http://jakarta.apache.org/tomcat/faq/deployment.html
http://jakarta.apache.org/tomcat/faq/performance.html
http://marc.theaimsgroup.com/?l=tomcat-user&m=111284993902294&w=2

--------------------------------------------------------------------- To unsubscribe, e-mail: tomcat-user-unsubscribe@jakarta.apache.org For additional commands, e-mail: tomcat-user-help@jakarta.apache.org