Embedded Server Startup Lifecycle

One of Spring Boot’s biggest innovations is the embedded web server (Tomcat, Jetty, or Undertow). Instead of deploying WAR files to an external server, Spring Boot starts the web server inside the JVM during application startup.

Understanding this lifecycle is essential for:

• Debugging startup issues
• Customizing ports, connectors, SSL, threads
• Mastering Spring Boot internals

---

What Is an Embedded Server?

An embedded server is a web server packaged inside the Spring Boot application, removing the need for external deployment (WAR, standalone Tomcat).

Common embedded servers:

• Tomcat (default)
• Jetty
• Undertow

---

Where Embedded Server Startup Fits in Spring Boot Lifecycle

Embedded server startup happens after the ApplicationContext is refreshed, but before the application is fully ready.

High-level flow:

SpringApplication.run()
   ├──prepareEnvironment()
   ├──createApplicationContext()
   ├──refreshContext()
   │     ├── BeanDefinition loading
   │     ├── Bean instantiation
   │     ├── Embedded server creation & start  ← HERE
   └── ApplicationReadyEvent

---

Core Abstractions Involved

Component	Responsibility
ServletWebServerApplicationContext	Web-aware ApplicationContext
ServletWebServerFactory	Creates web server
TomcatServletWebServerFactory	Tomcat-specific factory
WebServer	Unified server abstraction
DispatcherServlet	Central request dispatcher

---

Embedded Server Startup – Step by Step

1. Detect Web Application Type

During SpringApplication.run():

WebApplicationType.deduceFromClasspath()

Possible values:

• SERVLET → Tomcat / Jetty
• REACTIVE → Netty
• NONE → No web server

If SERVLET is detected:

➡️ Spring creates ServletWebServerApplicationContext.

---

2. Create WebServerFactory Bean

Spring Boot auto-configures a ServletWebServerFactory bean:

Examples:

TomcatServletWebServerFactory
JettyServletWebServerFactory
UndertowServletWebServerFactory

Auto-configured by:

ServletWebServerFactoryAutoConfiguration

Conditional checks:

• Classpath availability
• User overrides
• Properties (server.port, server.ssl.*)

---

3. ApplicationContext Refresh Begins

During:

AbstractApplicationContext.refresh()

Spring performs:

• Bean instantiation
• Dependency injection
• Lifecycle callbacks

Embedded server is not started yet.

---

4. onRefresh() – Web Server Creation

Inside:

ServletWebServerApplicationContext.onRefresh()

Spring calls:

createWebServer()

What happens:

• Retrieves ServletWebServerFactory
• Calls getWebServer(...)
• Creates server instance (Tomcat/Jetty)

➡️ Server is created but not yet serving requests

---

5. Register DispatcherServlet

Before server starts:

• DispatcherServlet bean is created
• Servlet mappings are registered
• Filters (FilterRegistrationBean)
• Servlet listeners are added

Default mapping:

DispatcherServlet →"/"

---

6. Embedded Server Startup (Critical Step)

Spring calls:

webServer.start()

For Tomcat:

• Connector initialized
• Port binding (server.port)
• Thread pools created
• Servlet container initialized

At this moment:

• Port is opened
• Server starts listening for requests

---

7. WebServerInitializedEvent Published

After successful startup:

WebServerInitializedEvent

Contains:

• Actual port
• Server instance

Useful for:

• Dynamic port detection
• Logging
• Test environments

---

8. ApplicationReadyEvent Fired

Final lifecycle event:

ApplicationReadyEvent

Meaning:

• ApplicationContext fully initialized
• Embedded server running
• App is ready to accept traffic

---

Complete Embedded Server Startup Flow

SpringApplication.run()
   ↓
Detect WebApplicationType
   ↓
Create ServletWebServerApplicationContext
   ↓
Auto-configure ServletWebServerFactory
   ↓
refreshContext()
   ↓
onRefresh()
   ↓
createWebServer()
   ↓
Register DispatcherServlet & filters
   ↓
webServer.start()
   ↓
WebServerInitializedEvent
   ↓
ApplicationReadyEvent

---

Tomcat-Specific Internal Flow (Example)

TomcatServletWebServerFactory
   └──createTomcat()
         ├── Create Tomcat instance
         ├── Configure connectors
         ├── Setup thread pool
         ├── Register servlets
         └──start()

---

Customization Hooks

Change Port

server.port=9090

Customize Tomcat Programmatically

@Bean
public WebServerFactoryCustomizer<TomcatServletWebServerFactory>customizer() {
return factory -> factory.setPort(9090);
}

---

Common Startup Issues (Debug Tips)

Issue	Cause
Port already in use	Another process running
Server not starting	WebApplicationType = NONE
DispatcherServlet not registered	Context load failure
Filters not applied	Order or registration issue

Enable debug:

debug=true

---

Why Embedded Server Lifecycle Matters

• No external server needed
• Faster development & deployment
• Consistent environments
• Easy containerization (Docker)
• Full programmatic control

---

Key Takeaways

• Embedded server is started inside Spring context
• Created during onRefresh()
• Started before ApplicationReadyEvent
• Fully customizable via auto-configuration
• Integral to Spring Boot’s “run anywhere” model

---

Conclusion

The Embedded Server Startup Lifecycle is a core pillar of Spring Boot architecture.

It:

• Eliminates traditional deployment complexity
• Integrates web server lifecycle with Spring context
• Provides powerful extension and customization points
• Enables cloud-native, container-friendly applications