Skip to content
Tutorials Center
My learning

Topics

Lesson 35 of 37 ยท Projects and Practice

Project: Zero-Downtime Deployment on Tomcat

Deploy new versions of a web app without dropping sessions using Tomcat parallel deployment, version numbers in WAR names, health checks and a rollback plan.

Redeploying a WAR the plain way has an ugly side effect: the old application stops, its sessions are lost, and for a few seconds or minutes users see errors. For a shop or an internal tool used all day that is not acceptable. Tomcat has a feature built for this, called parallel deployment, and you can combine it with a load balancer for rolling upgrades across nodes.

In this project you will design a zero-downtime release process: how parallel deployment works, how to script a release with a health check and a rollback, and how to model the routing of users between versions. Tomcat cannot run on this site, so the commands are read-only, and the runnable Java is a model of the behavior.

How parallel deployment works

Name the WAR with a version after two hash signs: shop##001.war, shop##002.war. Tomcat deploys both under the same context path /shop. Every request is routed as follows:

  • A request with no session, or a session that belongs to no version, goes to the highest version (the lexicographically largest, so use zero-padded numbers or date stamps such as shop##2026-03-14.1).
  • A request with a session is routed to the version that created that session, so existing users finish on the old version while new users start on the new one.

When the old version has no sessions left (they expire after the timeout), Tomcat's undeployOldVersions support, available through the manager and in the Host settings, removes it, or you delete the old WAR yourself. The lifecycle:

flowchart LR
  A["shop##001 live"] --> B["Copy shop##002.war"]
  B --> C["Both versions deployed"]
  C --> D["New sessions use 002"]
  D --> E["Old sessions drain from 001"]
  E --> F["Undeploy 001"]

Users with a session stay on version 001 until it expires; everyone else gets version 002.

Requirements and caveats:

  • Sessions must be created per version; a version change in the middle of a session is not attempted.
  • Both versions run at once, so the database schema must work for both (see below).
  • Cookies must use the same Path=/shop for the routing to see them.
  • The two versions use twice the memory, so budget heap and metaspace for the overlap.

Deploying with the manager's text interface

The manager can deploy and undeploy versions from a script. The version parameter names the version, and the update flag replaces an existing one:

Terminal
# upload and deploy version 002 under /shop
curl -u deployer:secret -T shop.war \
  "http://localhost:8080/manager/text/deploy?path=/shop&version=002"

# list contexts and their session counts
curl -u deployer:secret "http://localhost:8080/manager/text/list"

# after sessions on 001 have drained, remove it
curl -u deployer:secret "http://localhost:8080/manager/text/undeploy?path=/shop&version=001"

The deployer user needs the manager-script role, and the manager must be restricted to a trusted network (valves and access control). Alternatively drop the WAR into webapps (needs autoDeploy, or a copy into place from the deploy script). copy to a temporary name and mv to shop##002.war so Tomcat never sees a half-copied file.

The database rule: expand and contract

Two versions share one database during the overlap. Change the schema in steps that stay compatible:

  1. Expand: add new columns or tables as nullable or with defaults; deploy version 002 that writes both old and new shapes.
  2. Migrate the data in the background.
  3. Contract: once 001 is gone, drop the old columns in a later release.

A change that renames a column in one step breaks the running old version. This is the single most common cause of failed zero-downtime releases.

Model: routing during a parallel deployment

This stand-in models the routing rule and a release: two versions, users with or without sessions, and the drain of the old version. It is a model of the idea, not Tomcat code.

Java Stand-in: parallel deployment routing

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with IO.readln() or a Scanner), it gets the next line from this box.

An unknown session id (for example from before a restart) is treated like no session and goes to the newest version, which then creates a fresh session.

A release script with health check and rollback

A safe release does not trust that the new version works. It deploys, checks a health URL, and removes the new version if the check fails, which sends new users back to the old version automatically (the old one is still the highest remaining version). The stand-in below shows that decision logic with a pretend health check:

Java Stand-in: release with rollback

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with IO.readln() or a Scanner), it gets the next line from this box.

In a real script the predicate calls curl --fail http://localhost:8080/shop/health (a version-specific health endpoint, or an endpoint returning the build number you expect) and the rollback is an undeploy?version=003 call. Log the version and result for each release.

Rolling upgrades across several nodes

With a load balancer (load balancing) you can also upgrade node by node: drain node 1, deploy, check health, return it to rotation, then node 2. Combine this with session replication if sessions must survive, or accept that users on a drained node log in again. Prefer parallel deployment on a single node when you have no replication, and rolling upgrades when you have many nodes.

Release checklist

  • Database changes are backward compatible (expand now, contract later).
  • Version numbers sort correctly (001, 002, or a date stamp).
  • Memory headroom for two copies of the application.
  • Health endpoint that checks real dependencies.
  • Rollback command ready and tested.
  • Old versions undeployed after the session timeout plus a margin.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. How do you name WAR files for parallel deployment?

    Two hash signs separate the context path from the version, giving the same path /shop for both.
  2. 2. Which version serves a request that carries a session created on version 001?

    Tomcat routes existing sessions to the version that created them.
  3. 3. Why must database changes follow expand and contract?

    During the overlap the old version must still work, so changes must be backward compatible.
  4. 4. What should a safe release script do if the health check fails?

    Removing the failed version returns new users to the previous version without downtime.

Summary

  • app##version.war lets Tomcat run two versions at once: new sessions use the highest, existing sessions stay put.
  • Script the release: deploy, health check, rollback, then undeploy the old version after sessions expire.
  • Keep the database compatible with both versions, and budget memory for the overlap.
  • Use rolling upgrades with a load balancer for multi-node setups.

Next: Project: a mini servlet container