C2B2 logo icon

How to Run Hot Deployments on Tomcat

If restarting Tomcat is becoming a pain during application deployment, then take a look at our hot deployment walk-through, and make installs with the server up-and-running.

If you're making frequent application deployments on an Apache Tomcat environment, and are looking for a way to avoid full server restarts, this walk-through will explain the approach you need to take for hot deployments, allowing application deployment with Tomcat still up-and-running.

Because I'll be showing you how to create and write new targets using Apache ANT (Another Neat Tool - this automates the execution of commands in build and deployment) tasks to set up and deploy with Tomcat Application Manager - you'll need at least a basic understanding of how to work with Tomcat, as well as some knowledge of ANT's functionality and syntax.

So, let's set out the steps we're going to take for the deployment:

  1. Check Tomcat is up and old web application exists
  2. Remove the old web application version without stopping /restarting Tomcat
  3. Hot-Deploy the new web application on running Tomcat

Just a couple of notes on our software: Apache ANT (Another Neat Tool) is a program that automates the execution of commands in build and deployment. Tomcat Manager Application includes a set of ANT task definitions, which you should enable in your application's build.xml file, using <taskdef> elements (like the snippets shown in below sections).

Check Tomcat is up and old web application exists

To redeploy the application, the build process must first check that the web application is installed and exists prior to removal - otherwise Tomcat's Manager Application will fail when trying to remove it.

To make this work, you should create an “init target” (like the one shown in the snippet below) that checks if the web application is installed and exits on a given context path.

This new “init target” should set two properties:

  • is.tomcat.started
  • is.webapp.deployed

The condition task sets is.tomcat.started to "true" if the nested sub-task http returns a valid HTTP response code.

The condition task sets is.webapp.deployed to "true" if Tomcat is started and the nested http sub-task returns a valid response code. 

A valid response code means a success response when opening a connection to the URL - and if a failure occurs, the connection URL is assumed to be invalid.

Here's the code snippet needed to identify the web application as installed & existing on a particular context path:

<target name="init">
  <condition property="is.tomcat.started">
    <http url="${host}:${port}"/>
  </condition>

  <condition property="is.webapp.deployed">
    <and>
      <isset property="is.tomcat.started"/>
      <http url="${host}:${port}/${webapp.context.name}"/>
    </and>
  </condition>
</target>

Remove the old web application version without stopping / restarting Tomcat

For deploying a new version of a web application, you first have to remove the current version of the web application from the context path - as required by Tomcat. To do this using Tomcat Manager Application, you should use the ANT task called “Remove Task”, otherwise the deployment would fail as the application it is trying to deploy already exists.

The snippet below shows how to create an “undeploy target” and use Tomcat's “Remove Task”, to remove a web application from a given context path. This new “undeploy target” invokes the “Remove Task, and gets executed only if the property is.webapp.deployed is "true". 

The “init target” from the above sections sets this property to "true" if there is a web application installed on the context path.

<target name="undeploy" depends="init" if="is.webapp.deployed">
  <taskdef name="remove" classname="org.apache.catalina.ant.RemoveTask">
    <classpath>
      <path location="${env.CATALINA_HOME}/server/lib/catalina-ant.jar"/>
    </classpath>
  </taskdef>

  <remove
      url="${url.manager}"
      username="${username.manager}"
      password="${password.manager}"
      path="/${webapp.context.name}"/>
</target>

Next steps...

  • Create a task definition so that ANT knows about the remove task. The task is found at $CATALINA_HOME/server/lib/catalina-ant.jar, where $CATALINA_HOME is the base directory for Tomcat. 
     
  • This new “Remove Task” defines the following four attributes, and is executed to remove the web application from Tomcat on the specific context path.
     
    • The url attribute specifies the location of the Manager web application. By default, Tomcat installs this on the context path /manager. For example, the URL might be http://localhost:8080/manager.
       
    • The username attribute specifies the name of the user who wishes to use the Manager application.
       
    • The password attribute specifies a password for authenticating the username with the Manager application.
       
    • The path attribute specifies the context path of the web application to remove.

The “Remove Task” fails if there is no existing web application installed on the current context path - thus hampering the build process - so before trying to remove the web application, the "init task" shown in the first section should always be used.

Hot-Deploy the new web application on running Tomcat 

Deploying a new web application to a running server is critical for test-first development, because it takes too long to restart most servers.

The snippet below shows how to use Tomcat's "Install Task" to hot deploy. A new “deploy target” should be created that invokes the "Install Task".

You can name the task anything, for example "Install Task" like below.

Before deploying the web application, a new WAR file must be generated, the server must be confirmed as up-and-running using the “init target”, and the old web application (if installed and exists) must be removed using the “undeploy target” as  shown in the above sections. 

Here's the snippet to use "Install Task"

<target name="deploy" depends="war,start.tomcat,undeploy">
  <taskdef name="install" classname="org.apache.catalina.ant.InstallTask">
    <classpath>
      <path location="${env.CATALINA_HOME}/server/lib/catalina-ant.jar"/>
    </classpath>
  </taskdef>

  <pathconvert dirsep="/" property="fullWarDir">
    <path>
      <pathelement location="${dir.build}/${webapp.context.name}.war"/>
    </path>
  </pathconvert>

  <install
      url="${url.manager}"
      username="${username.manager}"
      password="${password.manager}"
      path="/${webapp.context.name}"
      war="jar:file:/${fullWarDir}!/"/>
</target>

Next Steps...

  • Create a task definition so that ANT knows about the "Install Task" - the task is found at $CATALINA_HOME/server/lib/catalina-ant.jar, where $CATALINA_HOME is the base directory for Tomcat.
     
  • The full path of the WAR file that is being deployed is stored in the “property fullWarDir" using Ant's "pathconvert task".
     
  • The "Install Task" defines the following five attributes and is then executed:
     
    • The url attribute specifies the location of the Manager application. By default, Tomcat installs the application on the context path /manager. For example, the URL might be http://localhost:8080/manager.
       
    • The username attribute specifies the name of the user who wishes to use the Manager application.
       
    • The password attribute specifies a password for authenticating the username with the Manager application.
       
    • The path attribute specifies the context path to install the web application.
       
    • The war attribute specifies an absolute path to the WAR file being deployed and takes on a URL that complies with the class java.net.JarURLConnection.

The "Install Task" fails if there is an existing web application installed on the current context path - hampering the deployment process. Hence, before deploying the new WAR file, you must ensure that Tomcat is up-and-running using the “init target” shown in above section and also that the old web application has been removed using the “undeploy target” (shown in the above sections).

Hot Deployment to Tomcat with an IDE

Integrated Development Environments can speed up many aspects of Java web application development, including deployment of changes to the server.

As we have seen above, Tomcat has native support for hot deployment - and getting Tomcat to update applications with your changes as you make them is a deceptively simple problem. 

Here are some quick steps to get your IDE talking to Tomcat:

  • Configure your IDE with Tomcat Plugin to recognise Tomcat as a server environment.  (Most IDEs offer plug-ins adding Tomcat support to their environment).
     
  • Give your IDE write-access to your application's "WEB-INF/classes" directory.
     
  • Configure Tomcat to reload classes when they are changed, by setting the "reloadable" attribute to "true" for the relevant Context and Web-App elements in your Tomcat configuration files.

And there you have it, the new version of the web application is now ready, without restarting Tomcat!