The Apache Jakarta Tomcat 5.5 Servlet/JSP Container

Deployer HOW-TO

Introduction
Context XML descriptors
Deploying on Tomcat startup
Deploying on running Tomcat server
Deploying using the Client Deployer Package

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).

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 $CATALINA_HOME/conf/[enginename]/[hostname]/foo.xml. 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.

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.

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:

• The Context XML declarations will be deployed first
• 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
• .WAR files will be deployed

For each deployed web application, a matching Context XML descriptor will be created unless one exists already.

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.

This includes:

• Deployment of WARs which are copied to the host appBase.
• Deployment of expanded web applications which are copied to the host appBase.
• 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.
• Redeployment of the web application if the /WEB-INF/web.xml file is updated.
• Redeployment of the web application if the context XML file from which the web application has been deployed is updated.
• 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 $CATALINA_HOME/conf/[enginename]/[hostname]/ folder.
• 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).

Note: Web application reloading can also be configured in the loader, in which case loaded classes will be tracked for changes.

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.

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 org.apache.catalina.ant.ValidatorTask) allows only one parameter: the base path of an expanded web application.

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 /META-INF/context.xml.

The deployer package includes a ready to use Ant script, with the following targets:

• compile (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 /WEB-INF/classes folder of the web application.
• deploy: Deploy a web application (compiled or not) to a Tomcat server
• undeploy: Undeploy a web application
• start: Start web application
• reload: Reload web application
• stop: Stop web application

The following properties can be specified, either as system properties, or by using a deployer.properties file located in the root folder of the deployer package:

• build: The build folder used will be, by default, ${build}/webapp${path}. After the end of the execution of the compile target, the web application WAR will be located at ${build}/webapp${path}.war.
• webapp: Folder containing the expanded web application which will be compiled and validated. By default, the folder is myapp.
• path: Deployed context path of the web application, by default /myapp.
• url: 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 http://localhost:8080/manager.
• username: Username to be used to connect to the Tomcat manager.
• password: Password to be used to connect to the Tomcat manager.