Deployer HOW-TO

- -

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.

- -

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

+ 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 + jakarta-tomcat-5.5.x-deployer. +

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

Download the TCD distribution
+ The TCD package need not be extracted into any existing Tomcat + installation, it can be extracted to any location. +
Read Using the Tomcat Client Deployer

+ In talking about deployment of web applications, the concept of a + Context is required to be understood. A Context is what Tomcat + calls a web application. +

+ In order to configure a Context within Tomcat a Context Descriptor + 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 server.xml but this is now + discouraged (although it currently still works). +

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

+ The locations for Context Descriptors are; +

$CATALINA_HOME/conf/[enginename]/[hostname]/context.xml
$CATALINA_HOME/webapps/[webappname]/META-INF/context.xml

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

+ 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 + appBase which is specified per Host. You either copy a + so-called exploded web application, i.e non-compressed, to this + location, or a compressed web application resource .WAR file. +

+ The web applications present in the location specified by the Host's + (default Host is "localhost") appBase attribute (default + appBase is "$CATALINA_HOME/webapps") will be deployed on Tomcat startup + only if the Host's deployOnStartup attribute is "true". +

+ The following deployment sequence will occur on Tomcat startup in that + case: +

Any Context Descriptors will be deployed first.
+ 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 +
.WAR files will be deployed

+ Note again that for each deployed web application, a + Context Descriptor will be created unless one exists already. +

+ It is possible to deploy web applications to a running Tomcat server. +

+ If the Host autoDeploy 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 appBase. + For this to work, the Host needs to have background processing + enabled which is the default configuration. +

+ +

+ autoDeploy set to "true" and a running Tomcat allows for: +

Deployment of .WAR files copied into the Host appBase.
+ Deployment of exploded web applications which are + copied into the Host appBase. +
+ 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 unpackWARs + attribute set to "false", in which case the web application + will be simply redeployed as a compressed archive. +
+ Re-deployment of a web application if the /WEB-INF/web.xml file is + updated. +
+ Re-deployment of a web application if the Context Descriptor file from which + the web application has been deployed is updated. +
+ 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 + $CATALINA_HOME/conf/[enginename]/[hostname]/ + directory. +
+ 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). +

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

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

+ +

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

+ +

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

+ +

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

+ +

+ The TCD 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

+ +

+ In order for the deployment to be configured, create a file + called deployer.properties in the TCD installation + directory root. In this file, add the following name=value pairs per + line: +

+ +

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

+ +

+ 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: The directory containing the exploded 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 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 + http://localhost:8080/manager. +
+ username: Tomcat Manager username (user should have a role of + manager) +
password: Tomcat Manager password.