Configure the embedded web server in Spring Boot

Spring Boot embeds a web server — Tomcat by default — directly in the application jar. This eliminates the need to deploy to an external container, but it also means server configuration happens through Spring Boot properties and programmatic customizers rather than server-specific XML files. This guide covers the most common embedded server configuration tasks.

Changing the server port

The default HTTP port is 8080. Override it with server.port in application.properties or application.yaml:

server:
  port: 9090

You can also set it via an OS environment variable (SERVER_PORT) or a JVM system property (-Dserver.port=9090). To disable the HTTP endpoint entirely (useful in some test scenarios) while still creating a WebApplicationContext:

server:
  port: -1

Using a random port

To let the OS assign a free port (avoiding clashes in parallel test runs), set server.port=0:

server:
  port: 0

To discover the actual port at runtime in a test, inject it with @LocalServerPort:

import org.springframework.boot.test.context.SpringBootTest;
import org.springframework.boot.test.context.SpringBootTest.WebEnvironment;
import org.springframework.boot.test.web.server.LocalServerPort;

@SpringBootTest(webEnvironment = WebEnvironment.RANDOM_PORT)
class MyWebIntegrationTests {

    @LocalServerPort
    int port;

    // use 'port' in your tests

}

@LocalServerPort is a meta-annotation for @Value("${local.server.port}"). Do not inject it in regular application code — the value is only available after the container starts, which is after most application beans initialize.

Configuring HTTPS

Configure HTTPS declaratively by setting server.ssl.* properties. Spring Boot supports Java KeyStore files and PEM-encoded certificate files.

Java KeyStore (JKS)
PEM files
SSL bundles

server:
  port: 8443
  ssl:
    key-store: "classpath:keystore.jks"
    key-store-password: "secret"
    key-password: "another-secret"

Use PKCS#8 key files (beginning with -----BEGIN PRIVATE KEY-----). If you have PKCS#1 or SEC 1 format, convert first:

openssl pkcs8 -topk8 -nocrypt -in <input file> -out <output file>

Then configure:

server:
  port: 8443
  ssl:
    certificate: "classpath:my-cert.crt"
    certificate-private-key: "classpath:my-cert.key"
    trust-certificate: "classpath:ca-cert.crt"

Define a named SSL bundle and reference it by name:

server:
  port: 8443
  ssl:
    bundle: "example"

The bundle’s trust material is configured separately under spring.ssl.bundle.*.

Once HTTPS is configured, the server no longer supports plain HTTP on port 8080. Spring Boot does not support configuring both HTTP and HTTPS through application.properties — configure HTTPS in properties and add the HTTP connector programmatically if both are needed.

Switching the embedded server

Spring Boot supports Tomcat (default), Jetty, and Undertow. To switch servers, exclude the default starter and add the replacement.

Tomcat to Jetty

Maven
Gradle

<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-webmvc</artifactId>
    <exclusions>
        <!-- Exclude the Tomcat dependency -->
        <exclusion>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-tomcat</artifactId>
        </exclusion>
    </exclusions>
</dependency>
<!-- Use Jetty instead -->
<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-jetty</artifactId>
</dependency>

dependencies {
    implementation('org.springframework.boot:spring-boot-starter-webmvc') {
        // Exclude the Tomcat dependency
        exclude group: 'org.springframework.boot', module: 'spring-boot-starter-tomcat'
    }
    // Use Jetty instead
    implementation "org.springframework.boot:spring-boot-starter-jetty"
}

The same approach applies to reactive stack applications: exclude spring-boot-starter-reactor-netty from spring-boot-starter-webflux and add the replacement starter.

For reactive stack applications, the spring-boot-starter-webflux includes Reactor Netty by default. You can use spring-boot-starter-tomcat or spring-boot-starter-jetty instead.

Configuring thread pools and connection settings

Use server.tomcat.* properties to tune Tomcat’s thread pool and connection handling:

server:
  tomcat:
    threads:
      max: 200          # maximum worker threads (default: 200)
      min-spare: 10     # minimum spare worker threads
    connection-timeout: 20s
    max-connections: 8192
    accept-count: 100

For Jetty, the equivalent namespace is server.jetty.*:

server:
  jetty:
    threads:
      max: 200
      min: 8
      idle-timeout: 60000

For most use cases, prefer using application.properties to configure server settings over programmatic customization. The server.* namespace is extensive — check the ServerProperties class for all supported options.

Enabling HTTP/2

Set server.http2.enabled=true to enable HTTP/2. Both h2 (over TLS) and h2c (over TCP, cleartext) are supported.

server:
  http2:
    enabled: true

HTTP/2 with Tomcat

Spring Boot ships with Tomcat 11.0.x, which supports both h2c and h2 out of the box. No additional dependencies are required. To use h2, SSL must also be enabled. To use h2c without TLS (for example, behind a TLS-terminating proxy), enable HTTP/2 and leave SSL disabled.Optionally, libtcnative can be used for h2 support if installed on the host OS:

-Djava.library.path=/usr/local/opt/tomcat-native/lib

HTTP/2 with Jetty

Jetty requires the additional dependency org.eclipse.jetty.http2:jetty-http2-server.For h2 (over TLS), also add one of:

org.eclipse.jetty:jetty-alpn-java-server — uses the JDK’s built-in ALPN support
org.eclipse.jetty:jetty-alpn-conscrypt-server — uses the Conscrypt library

No additional dependencies are required for h2c.

HTTP/2 with Reactor Netty (WebFlux)

Reactor Netty supports both h2 and h2c out of the box. For optimal performance with native libraries, add io.netty:netty-tcnative-boringssl-static.

Enabling response compression

HTTP response compression is supported by Tomcat, Jetty, and Reactor Netty. Enable it in application.properties:

server:
  compression:
    enabled: true

By default:

Responses must be at least 2048 bytes to be compressed.
Only text/html, text/xml, text/plain, text/css, text/javascript, application/javascript, application/json, and application/xml content types are compressed.

Customize the minimum size and mime types:

server:
  compression:
    enabled: true
    min-response-size: 1024
    mime-types:
      - text/html
      - application/json
      - application/xml
      - application/octet-stream

To keep the default types and add extras, use additional-mime-types instead of overriding mime-types.

Configuring proxy and forwarded headers

When running behind a reverse proxy or load balancer, the original request information (host, port, scheme) may differ from what the application sees. Configure server.forward-headers-strategy to handle forwarded headers:

server:
  forward-headers-strategy: NATIVE

NATIVE: Instructs the web server itself to handle X-Forwarded-* headers natively. Works for X-Forwarded-For and X-Forwarded-Proto.
FRAMEWORK: Activates Spring’s ForwardedHeaderFilter (servlet) or ForwardedHeaderTransformer (reactive). Use when NATIVE is insufficient.

On supported cloud platforms (Cloud Foundry, Kubernetes, etc.), server.forward-headers-strategy defaults to NATIVE. On all other platforms, it defaults to NONE.

To customize Tomcat’s remote IP header names:

server:
  tomcat:
    remoteip:
      remote-ip-header: "x-your-remote-ip-header"
      protocol-header: "x-your-protocol-header"

Graceful shutdown

To enable graceful shutdown, configure server.shutdown=graceful. When a shutdown signal is received, the server stops accepting new requests and waits for in-flight requests to complete before the context is closed.

server:
  shutdown: graceful
spring:
  lifecycle:
    timeout-per-shutdown-phase: 30s

Enable graceful shutdown

server:
  shutdown: graceful

Set the grace period

Configure how long Spring Boot waits for active requests to finish before forcing a shutdown. The default is 30 seconds:

spring:
  lifecycle:
    timeout-per-shutdown-phase: 30s

Graceful shutdown applies to the web server. Requests that have already been accepted are allowed to complete, but no new connections are accepted. Ensure your load balancer stops routing traffic to the instance before the shutdown signal is sent.

Programmatic server customization

For cases not covered by application.properties, use WebServerFactoryCustomizer to access the server factory directly. The following example customizes Tomcat using the servlet stack:

import org.springframework.boot.tomcat.servlet.TomcatServletWebServerFactory;
import org.springframework.boot.web.server.WebServerFactoryCustomizer;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;

@Configuration
public class MyTomcatWebServerCustomizer
        implements WebServerFactoryCustomizer<TomcatServletWebServerFactory> {

    @Override
    public void customize(TomcatServletWebServerFactory factory) {
        // access Tomcat-specific APIs here
        factory.addConnectorCustomizers(connector ->
                connector.setProperty("maxParameterCount", "200"));
    }

}

Available factory types:

Server	Servlet stack	Reactive stack
Tomcat	`TomcatServletWebServerFactory`	`TomcatReactiveWebServerFactory`
Jetty	`JettyServletWebServerFactory`	`JettyReactiveWebServerFactory`
Reactor Netty	N/A	`NettyReactiveWebServerFactory`

Spring Boot’s own auto-configured WebServerFactoryCustomizer beans have order 0 and run before any user-defined customizers unless you set an explicit order on yours.

Configuration

Data & Messaging

Web & API

Build & Deploy

Configure the embedded web server in Spring Boot

Changing the server port

Using a random port

Configuring HTTPS

Switching the embedded server

Tomcat to Jetty

Configuring thread pools and connection settings

Enabling HTTP/2

Enabling response compression

Configuring proxy and forwarded headers

Graceful shutdown

Programmatic server customization

Build docs developers (and LLMs) love

Configuration

Data & Messaging

Web & API

Build & Deploy

Documentation Index

​Changing the server port

​Using a random port

​Configuring HTTPS

​Switching the embedded server

​Tomcat to Jetty

​Configuring thread pools and connection settings

​Enabling HTTP/2

​Enabling response compression

​Configuring proxy and forwarded headers

​Graceful shutdown

​Programmatic server customization

Build docs developers (and LLMs) love

Changing the server port

Using a random port

Configuring HTTPS

Switching the embedded server

Tomcat to Jetty

Configuring thread pools and connection settings

Enabling HTTP/2

Enabling response compression

Configuring proxy and forwarded headers

Graceful shutdown

Programmatic server customization