How to Gracefully Shut Down a Spring Boot Application with Embedded Tomcat

Preface

As Spring Boot becomes the default way to build online applications, many services run with an embedded Tomcat container. Using a plain kill command to stop the application discards in‑flight requests, which is unacceptable for critical business logic. This article explores a graceful shutdown approach for Spring Boot applications that embed Tomcat.

Example code can be obtained from the repository: springboot-shutdown: https://github.com/wrcj12138aaa/springboot-shutdown Supported environment: JDK 8 Spring Boot 2.1.4 Maven 3.6.0

Customize Tomcat Connector Behavior

Graceful shutdown starts with stopping the embedded web container so it no longer accepts new external requests. By implementing TomcatConnectorCustomizer, we can control when Tomcat’s thread pool is closed after processing current requests.

The Connector is Tomcat’s abstraction for handling incoming HTTP/AJP requests. By customizing its behavior we can allow Tomcat’s thread pool to shut down only after all requests finish. The following code defines a timeout for the thread‑pool shutdown and implements ApplicationListener to listen for Spring’s context close event.

Add Connector Callback to Embedded Tomcat

After defining the customizer, we need to register it with the embedded Tomcat factory during startup. This is done via TomcatServletWebServerFactory, which is the factory class for Spring Boot’s embedded Tomcat (similar factories exist for Jetty and Undertow).

We add the customizer using the addConnectorCustomizers method:

addConnectorCustomizers

Enable Shutdown Endpoint

Beyond stopping the Tomcat container, we also need to close the Spring context. Spring Boot Actuator provides a remote shutdown endpoint. First, add the Actuator starter dependency: spring-boot-starter-actuator Then enable the shutdown endpoint in application.properties:

The first line turns on the shutdown endpoint; the second line exposes all endpoints over HTTP.

Simulation Test

To verify graceful shutdown, we create a controller that simulates a 10‑second business operation using Thread.sleep. While this request is processing, we send a POST to http://host:port/actuator/shutdown. The logs show that the application does not stop immediately; it waits until the 10‑second request finishes, then exits, confirming that new requests are rejected while in‑flight requests complete.

Automation

Because Spring Boot applications are typically packaged as executable JARs, we can automate start‑up and graceful shutdown with shell scripts. The script adds the custom shutdown logic, starts the JAR, and triggers the Actuator shutdown endpoint when needed, reducing manual errors and streamlining deployment.

Summary

This article demonstrated how to achieve a graceful shutdown for Spring Boot applications that embed Tomcat by customizing the connector, enabling the Actuator shutdown endpoint, testing the behavior with simulated long‑running requests, and automating the process with scripts. The same principles apply to other embedded containers.