Remote Deployment of WAR files with Tomcat

This post will show you how to perform a remote deployment to Tomcat.

I am a big fan of remote deployment. During development, I normally have a remote dev server and remote QA server. At times, I need to deploy my web application to these remote servers.  I find it easier to deploy my web app by simply invoking an Ant task. There are other options for remote deployment such as using the Tomcat admin web app or an IDE. However, I like the idea of simply checking out my code from version control (cvs or svn) and running an Ant task. No requirement to have the IDE installed. Also, this works well if the deployment is part of an automated process such as nightly builds.


Tomcat provides a collection on Ant custom tasks for performing remote deployment. To get started you should follow these steps:

  1. Download the binary distribution of Ant from You must use version 1.4 or later.
  2. Install the Ant distribution. This directory is called ANT_HOME in the following steps.
  3. Copy the file $TOMCAT_HOME/server/lib/catalina-ant.jar into Ant’s library directory ($ANT_HOME/lib).
  4. Add the $ANT_HOME/bin directory to your PATH environment variable.
  5. Configure at least one username/password combination in your Tomcat user database that includes the manager role.

Ant Build File

Once your environment is setup, then you can use the following Ant build file.

<project name="remote_deployment_demo" default="create-war-file">

 <!-- ================================================================================== -->
 <!--                                                                                    -->
 <!-- NOTE: Be sure to copy ${tomcat.install}/lib/catalina-ant.jar to ${ant.install}/lib -->
 <!--                                                                                    -->
 <!-- ================================================================================== -->

 <!-- Configure the directory into which the web application is built -->
 <property name="dist"    value="dist" />

 <!-- Configure the name of the web content directory -->
 <property name="web.content"     value="WebContent" />

 <!-- Configure the name of the WAR filename -->
 <property name="war.filename"     value="delta.war" />

 <!-- Configure the context path for this application -->
 <property name="path"     value="/delta" />

 <!-- Configure properties to access the Manager application -->
 <property name="url"      value="http://localhost:8080/manager" />
 <property name="username" value="admin" />
 <property name="password" value="admin" />

 <!-- Configure the custom Ant tasks for the Manager application -->
 <taskdef name="deploy"    classname="org.apache.catalina.ant.DeployTask" />
 <taskdef name="list"      classname="org.apache.catalina.ant.ListTask" />
 <taskdef name="reload"    classname="org.apache.catalina.ant.ReloadTask" />
 <taskdef name="resources" classname="org.apache.catalina.ant.ResourcesTask" />
 <taskdef name="roles"     classname="org.apache.catalina.ant.RolesTask" />
 <taskdef name="start"     classname="org.apache.catalina.ant.StartTask" />
 <taskdef name="stop"      classname="org.apache.catalina.ant.StopTask" />
 <taskdef name="undeploy"  classname="org.apache.catalina.ant.UndeployTask" />

 <target name="setup" description="Setup supporting directories">
 <mkdir dir="${dist}" />

 <!-- Executable Targets -->
 <target name="create-war-file" description="Create the WAR file" depends="setup">
 <jar destfile="${dist}/${war.filename}" basedir="${web.content}" />

 <target name="deploy" description="Deploy web application"
 <deploy url="${url}" username="${username}" password="${password}"
 path="${path}" war="file:${dist}/${war.filename}" />

 <target name="undeploy" description="Remove web application">
 <undeploy url="${url}" username="${username}" password="${password}"
 path="${path}" />

 <target name="reload" description="Reload web application">
 <reload  url="${url}" username="${username}" password="${password}"
 path="${path}" />

 <target name="list" description="List deployed web applications">
 <list url="${url}" username="${username}" password="${password}" />


The following sections explains the contents of the build.xml file.

Lines 10-19 define parameters for the name of dist directories, web content directories and WAR filenames.

Lines 22-24 define the location of your remote server. Also defines the administrator user name and password. You should update these accordingly to match your environment.

Lines 26-34 define references to the Tomcat custom tasks. These custom tasks are defined in catalina-ant.jar from Step 3 above.

Lines 36-38 define the setup task. This task creates the directory: dist, if it doesn’t exist. This is the output directory for our WAR file.

Lines 41-43 define the task create-war-file. As you would expect, this task creates the WAR file. In this example, we only have we content stored in the directory WebContent. However, if you have servlets and supporting Java classes then you should add the appropriate Ant tasks for compiling code.

Lines 45-49 are the important lines for this example. We make use of the Tomcat custom task for deploying the WAR file to the remote server. The tag attributes provide the machine name, admin credentials, context path name and the WAR file. The context path name is the name of the application once it is deployed. In this example the context path is set to /delta. The WAR file is the one created in the earlier target and located in the dist directory.

Lines 51-54 defines a task for undeploying the application. This effectively removes/deletes the application from the Tomcat server.

Lines 56-59 reloads a web application. Reload is the same restarting the web application. It will not deploy a new version, it will simply restart the existing web application.

Lines 61-63 lists all of the web applications that are deployed on the server. This is a good sanity test to make sure your web application was deployed.

Ant Build File In Action

To deploy your application, type:

ant deploy

To verify your deployment, type:

ant list

This will list the applications deployed on the remote Tomcat server. You can view your application by visiting:  http://<server_name>:8080/delta

Finally, if you need to undeploy your application, type

ant undeploy

That’s it. We covered the steps for performing remote deployment of WAR files. This included setting up your environment, defining an Ant file and executing the desired targets. Hopefully this will help you on your development project.

Did you like my blog post?

Signup now and receive an email when I publish new luv2code content.

I agree to have my personal information transfered to AWeber ( more information )

I will never give away, trade or sell your email address. You can unsubscribe at any time.

Leave a Reply