How to undeploy a WAR file with Tomcat Manager

An old or failed WAR deployment should be removed through Tomcat Manager when its context path must be released for a replacement. The Manager undeploy command stops the web application, removes the deployed context, and clears the web application artifacts that Manager owns instead of relying on manual file deletion.

The text Manager interface fits repeatable removal because it returns a plain OK or FAIL response. A restricted user with the manager-script role can list deployed contexts, undeploy one path, and leave a transcript that deployment tools or change tickets can keep.

Undeploy is different from stop or reload. Use stop when the application only needs to be taken offline temporarily, use reload when an unpacked application should restart in place, and use undeploy when the deployed WAR, expanded directory, and context entry should be removed from Tomcat for that virtual host.

Related: How to create a Tomcat Manager user
Related: How to list deployed applications in Tomcat Manager
Related: How to reload a Tomcat application with Manager
Related: How to deploy a WAR file to Tomcat on Ubuntu

Steps to undeploy a WAR file with Tomcat Manager:

  1. Confirm that the Manager account can use the text interface. 
    $ curl --silent --show-error --user deployer:change-this-password http://localhost:8080/manager/text/list
OK - Listed applications for virtual host [localhost]
/inventory:running:0:inventory
/manager:running:0:manager

    The account needs the manager-script role. Use a restricted deployment account for text Manager commands, and avoid sharing that account with the manager-gui role.

  2. Identify the exact context path to remove. 
    Context path: /inventory
Current state: running

    The Manager path parameter must include the leading /. Use / only when the ROOT web application is the target.

  3. Confirm that undeploy is the right action for the application.

    Undeploy removes Manager-owned application artifacts under the Host appBase, such as the WAR file, expanded directory, and context XML. Use Manager stop instead when the application should only be unavailable for a short time.

  4. Undeploy the application through the Manager text endpoint. 
    $ curl --silent --show-error --user deployer:change-this-password 'http://localhost:8080/manager/text/undeploy?path=/inventory'
OK - Undeployed application at context path [/inventory]
  5. List applications again and confirm that the context is gone. 
    $ curl --silent --show-error --user deployer:change-this-password http://localhost:8080/manager/text/list
OK - Listed applications for virtual host [localhost]
/manager:running:0:manager
  6. Request the removed application URL and confirm that it no longer serves the old WAR. 
    $ curl --silent --show-error --output /dev/null --write-out '%{http_code}\n' http://localhost:8080/inventory/
404

    A 404 is the common direct Tomcat result for a removed context. Behind a proxy, use the status code or health-check response that proves the old application is no longer reachable.

  7. Check the appBase artifacts when shell access is available. 
    $ ls -ld /opt/tomcat/webapps/inventory /opt/tomcat/webapps/inventory.war
ls: cannot access '/opt/tomcat/webapps/inventory': No such file or directory
ls: cannot access '/opt/tomcat/webapps/inventory.war': No such file or directory

    Replace /opt/tomcat/webapps with the Host appBase for the instance. Package-managed installs often use a path under /var/lib/tomcat*, while archive installs often use $CATALINA_BASE/webapps.