Zero-Downtime Web Application Upgrade in Tomcat With Parallel Deployment

1. Overview

Apache Tomcat, or Tomcat for short, is an open-source implementation of Jakarta Servlet specification. It functions as a web server that receives HTTP or WebSocket requests and invokes the responsible servlet to handle the request.

In this tutorial, we’ll learn how parallel deployment in Tomcat supports zero-downtime web application upgrades.

2. Tomcat Deployment Modes

We can use Apache Tomcat to serve our web application in two ways. The first option embeds the Tomcat program into our Java application itself. Alternatively, we can run Apache Tomcat as a dedicated web server process that serves one or more web applications. In this mode, the developer packages the web application into the web application archive (WAR) format. Then, the web server administrator will deploy the web application to the Tomcat web server.

Although not as popular, running a dedicated Tomcat process for multiple web applications can be beneficial. For instance, the compute resource usage will be much more efficient when we share the same web server process across different web applications.

When we run Tomcat as a dedicated web server process, we need to learn how to do zero-downtime redeployment of a running web application. Contrary to containerized web applications that usually delegate this task to external orchestrators like Kubernetes, deployments in Tomcat rely on the Tomcat server to minimize the downtime for web application upgrades.

3. Parallel Deployment for Zero Downtime Redeployment

Before Apache Tomcat version 7, redeployment of a running web application was disruptive. Concretely, we needed to restart the Tomcat server to redeploy an existing, running web application. This is undesirable as it introduces downtime while the web application is redeployed. Additionally, the restart also disrupts other web applications that are running in the same Tomcat instance.

Fortunately, Apache Tomcat has introduced a parallel deployment mechanism since version 7 to support zero-downtime redeployment of web applications.

3.1. Versioned Deployment

The parallel deployment feature in Apache Tomcat allows us to redeploy our web application without downtime. We version our deployment using the double hashes operator (##) to enable parallel deployment. Concretely, we need to version our WAR file by suffixing the filename with ##{version} before the extension. For example, let’s version our demo.war file deployment to version 1:

$ mv demo.war demo##1.war

Notably, the version information in the filename doesn’t affect the context path at which Tomcat serves the web application. In the example above, the demo##1.war deployment will still be served under the /demo context path.

Later, when we want to upgrade the web application, we’ll deploy another WAR file with a different version number, like demo##2.war.

3.2. Graceful Upgrade

With versioned deployment, any subsequent deployment of the same web application with a different version number will trigger the parallel deployment. Concretely, Tomcat starts the new version web application. Then, it gradually routes the traffic to the same context path as the latest version. Importantly, it still runs the old version during the process. This ensures that any existing traffic being served by the old version will not be disrupted.

Eventually, all the traffic will be routed to the new version of the web application. At that point, we can decommission the old deployment.

4. Demonstrating Parallel Deployment

To see Apache Tomcat’s parallel deployment in action, we’ll first set up a Tomcat web server. Then, we’ll deploy the first version of our web application, web-v1.war. Subsequently, we’ll perform an upgrade using the web-v2.war file and sees that both web applications are running simultaneously.

4.1. Installing and Running Apache Tomcat Server

First, we’ll need to install the Tomcat software. We’ll download the Apache Tomcat version 10 package from its official site and then install it by extracting the entire ZIP file into a working directory:

$ wget -qO apache-tomcat-10.zip https://dlcdn.apache.org/tomcat/tomcat-10/v10.1.24/bin/apache-tomcat-10.1.24.zip
$ unzip apache-tomcat-10.zip

Then, we can start the Tomcat server by running the start command in bin/catalina.sh:

$ ./apache-tomcat-10.1.24/bin/catalina.sh start
Using CATALINA_BASE:   /opt/tomcat-10/apache-tomcat-10.1.24
...
Tomcat started.

At this point, our Tomcat server will be up and running. We can verify it by sending an HTTP GET request to port 8080 of the localhost and see that we get the default Tomcat welcome page back:

$ curl http://localhost:8080

<!DOCTYPE html>
<html lang="en">
    <head>
        <meta charset="UTF-8" />
        <title>Apache Tomcat/10.1.24</title>
        ...

4.2. Building a Sample Web Application

For demonstration purposes, we’ll use two different versions of the same web application, demo-v1.war and demo-v2.war. It’s a Spring Boot application that serves as a single GET endpoint at /home. The endpoint returns a text message, Hello world – version N where the N corresponds to the version number. This helps us visualize the version of the web application we’re interacting with.

Building the WAR files is outside the scope of this application, but we have a separate article that talks in-depth about how to package our web application to a WAR file.

4.3. Initial Deployment

Let’s deploy our web application and version our first deployment as version 1:

$ cp target/demo-v1.war /opt/apache-tomcat-10.1.24/webapps/demo##1.war

In the command above, we deploy the web application demo-v1.war by copying the WAR file to the webapps directory of our Tomcat instance. Importantly, we rename the WAR file to demo##1 to version it. We can verify that the deployment is successful by issuing a curl command to the /home path:

$ curl http://localhost:8080/demo/home
Hello world - version 1

4.4. Introducing a New Version

Let’s upgrade our web application by deploying the demo-v2.war file to the Tomcat web server. We’ll use the same cp command to copy the file over to the webapps directory and add the version information to the name:

$ cp target/demo-v2.war /opt/apache-tomcat-10.1.24/webapps/demo##2.war

If we run the curl command repeatedly, we’ll see that the server continues to respond to our requests to GET /home while the upgrade is in progress:

$ curl http://localhost:8080/demo/home
Hello world - version 1
$ curl http://localhost:8080/demo/home
Hello world - version 1
...

After a short time, we’ll see that our requests are being served by the new version:

$ curl http://localhost:8080/demo/home
Hello world - version 2

5. Conclusion

In this tutorial, we’ve learned that Apache Tomcat is a web server that serves web applications packaged as WAR files. Then, we’ve highlighted that it’s important to minimize the downtime of the Tomcat server when there’s a redeployment. Subsequently, we’ve learned that Apache Tomcat version 7 and later has a parallel deployment mechanism that allows us to perform zero-downtime web application upgrades.

Finally, we’ve demonstrated how parallel deployment works using a working example. We’ve also seen that the parallel deployment ensures existing traffic to the service will not be disrupted.