Skip to content
Tutorials Center
My learning

Topics

Lesson 11 of 37 ยท Deployment and Contexts

WAR Files and the webapps Folder

Learn how Tomcat deploys WAR files and folders from webapps: context path rules, ROOT.war, versioned names, unpackWARs, autoDeploy, deployOnStartup and common deployment mistakes.

Deployment means "make Tomcat run this web application". The simplest method has been the same for decades: put a .war file or an unpacked folder into the webapps directory of the host. Tomcat's HostConfig component watches that directory and decides which context path each entry gets, whether to unpack the archive and when to reload.

This lesson explains the naming rules, the host attributes that control deployment, what happens when you replace a WAR and the traps that cause "my change did not appear". The shell commands are read-only; the file-name rules are implemented in a runnable stand-in.

From file name to context path

Tomcat derives the context path from the entry name in appBase (usually webapps):

Entry in webapps Context path Notes
shop.war or folder shop/ /shop The normal case.
ROOT.war or folder ROOT/ / (empty path) The site's root application. Case matters on Linux: write it ROOT.
admin#reports.war /admin/reports A # stands for / in a nested path.
shop##2.war /shop, version 2 Parallel deployment (later lesson).
shop#v1##3.war /shop/v1, version 3 Both rules combined.

The context path is not read from inside the WAR. It comes from the file name (or from a context descriptor, next lesson). Renaming app-1.4.2.war to app.war is therefore a typical build-script step; otherwise your URL contains the version number.

Name decides the URL

shop.war Served at /shop
ROOT.war Served at /
a#b.war Served at /a/b
shop##2.war Version 2 of /shop

The version inside the file name never reaches the URL.

1 / 2

The stand-in implements these rules so you can test names before you deploy:

Java File name to context path and version (stand-in)

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.

The last line shows the build-name trap: app-1.4.2.war deploys at /app-1.4.2. In Maven set <finalName>app</finalName>.

What the Host does

The relevant Host attributes in server.xml (defaults shown):

XML
<Host name="localhost" appBase="webapps"
      unpackWARs="true"
      autoDeploy="true"
      deployOnStartup="true"
      deployXML="true"
      copyXML="false">
  • appBase: the directory scanned for applications; relative to CATALINA_BASE.
  • deployOnStartup: when true, everything in appBase is deployed during startup. (The webapps entries also apply if a context descriptor mentions them.)
  • autoDeploy: when true, a background thread checks every few seconds (the engine's backgroundProcessorDelay, default 10 s) for new, changed or deleted entries and acts. Convenient for development; in production many teams set it to false and redeploy with a restart or the manager API so changes are deliberate.
  • unpackWARs: when true, a WAR is extracted into a folder next to it and served from there. When false, Tomcat reads straight from the archive (slightly slower, no extracted files to clean up).

With unpackWARs="true" and autoDeploy="true" the WAR is the master: Tomcat compares timestamps and, if the WAR is newer, deletes the old unpacked folder and extracts again. Any file you edited inside the folder is lost. Edit sources and rebuild instead.

What happens when you drop a WAR in

  1. HostConfig notices shop.war.
  2. It unpacks it into webapps/shop/ (if unpackWARs).
  3. It creates a StandardContext with docBase=webapps/shop.
  4. The context starts: class loader created, listeners and filters initialized, servlets with load-on-startup initialized.
  5. The log shows Deployment of web application archive [...shop.war] has finished in [N] ms.

If step 4 fails (a ServletContextListener throws, the Servlet API version does not match), the context is marked unavailable and requests return 404 or 503 while the other applications keep running. Look in logs/localhost.<date>.log.

Redeploying

To update a running application:

  • Copy a newer WAR over the old one. With autoDeploy Tomcat undeploys the old context, removes the folder and deploys the new. There is a short window during which the app is unavailable, and sessions are lost unless persisted.
  • Touch WEB-INF/web.xml (or change a watched resource) to trigger a reload instead of a full redeploy.
  • Parallel deployment keeps the old version serving existing sessions while new sessions use the new one.
  • Manager application lets you deploy from a remote machine with curl.

This stand-in simulates a host's deployment scan: it compares what is in webapps now with what is deployed and decides whether each entry needs deploy, redeploy or undeploy, using timestamps like HostConfig does.

Java A deployment scan (stand-in for HostConfig)

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.

Deploying from the command line

Terminal
# Build, copy, watch the log
mvn -q package
cp target/shop.war /opt/tomcat/webapps/
tail -f /opt/tomcat/logs/catalina.out | grep -m1 "shop.war"

# Remove an application completely
rm /opt/tomcat/webapps/shop.war
rm -rf /opt/tomcat/webapps/shop /opt/tomcat/work/Catalina/localhost/shop

Copy files atomically where possible: copy to a temporary name outside webapps and mv into place, otherwise Tomcat may see a half-copied WAR and try to deploy it.

Common mistakes

  • Expecting the context path from the WAR's contents; it comes from the name.
  • Deploying Root.war on Linux: the name must be exactly ROOT.
  • Leaving the old unpacked folder when replacing a WAR with autoDeploy="false": the stale folder wins.
  • Hot copying a large WAR slowly, causing a failed partial deploy.
  • Forgetting to remove sample webapps in production.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. Which file name deploys an application at the server root path /?

    ROOT (exact case on Linux) is the special name for the empty context path.
  2. 2. A WAR called orders#v2.war is deployed. What is its context path?

    The # in a file name is replaced with / to build a multi-segment context path.
  3. 3. What does unpackWARs="false" do?

    The WAR stays packed; no extracted folder appears in webapps.
  4. 4. What is a risk of autoDeploy="true" in production?

    Background scanning means any new or modified WAR or descriptor is deployed immediately, so many teams make deployments explicit.

Summary

  • The context path comes from the entry name: shop.war is /shop, ROOT.war is /, a#b.war is /a/b, ##N adds a version.
  • Host attributes appBase, unpackWARs, autoDeploy and deployOnStartup control deployment.
  • With unpacking, the WAR is the master: edit sources, not the extracted folder.
  • Updates are a redeploy (short downtime), a reload, or a parallel deployment.
  • Copy atomically and clean up old folders and work entries when removing apps.

Next: Context descriptors