Configure Embedded Tomcat in Spring Boot

A Spring Boot servlet application can start Tomcat inside its executable JAR. Configure the server with server.* properties first. Use a Tomcat-specific factory customizer when the property set does not cover a server behavior you need. This tutorial uses Spring Boot 4.1.2 and checks each setting with a running application.

1. Start a Web Application with Tomcat

The spring-boot-starter-webmvc dependency provides Spring MVC and includes embedded Tomcat by default. The Spring Boot starter parent manages the compatible dependency versions. The application below exposes a small endpoint so we can check which address and protocol the server actually accepts:

<parent>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-parent</artifactId>
    <version>4.1.2</version>
</parent>
<dependencies>
    <dependency>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-webmvc</artifactId>
    </dependency>
</dependencies>

package com.howtodoinjava.tomcat;

import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RestController;

@SpringBootApplication
@RestController
public class TomcatApplication {
    public static void main(String[] args) {
        SpringApplication.run(TomcatApplication.class, args);
    }

    @GetMapping("/status")
    public String status() {
        return "ready";
    }
}

When SpringApplication.run() starts the servlet application, Spring Boot creates a Tomcat server and registers the controller. The /status response gives us a simple way to verify configuration changes. A service that only performs background work can avoid starting a web server; it does not need this starter merely to run Spring Boot.

2. Set the Port and Bind Address

The default HTTP port is 8080. For this local example, put the following settings in src/main/resources/application.properties:

server.address=127.0.0.1
server.port=9090

server.port changes where Tomcat listens. server.address binds it to the loopback interface, so the example accepts connections from the same machine rather than every network interface. Build and start the JAR, then send a request:

mvn package
java -jar target/spring-boot-tomcat-demo-1.0.0.jar
curl http://127.0.0.1:9090/status

The response body is ready, and the startup log reports Tomcat started on port 9090 (http). The address and port settings affect the listener, not the controller mapping. If the port is already occupied, choose another port, such as --server.port=9091 on the application command line. See Spring Boot’s embedded server reference for the related server settings.

3. Write HTTP Access Logs

Tomcat access logs record requests handled by the server. They are different from application logs written by Spring or by your code. Enable them and set a persistent base directory for this example:

server.tomcat.basedir=tomcat-work
server.tomcat.accesslog.enabled=true
server.tomcat.accesslog.buffered=false
server.tomcat.accesslog.pattern=%h %r %s

The pattern records the client address (%h), request line (%r), and HTTP status (%s). Setting buffered to false makes the entry visible promptly during the local demonstration; buffering is normally preferable for throughput. The default log directory is below Tomcat’s base directory, so this configuration writes to tomcat-work/logs relative to the application’s working directory.

After requesting /status, inspect the generated access-log file:

curl http://127.0.0.1:9090/status
# ready

# Example line in tomcat-work/logs/access_log.YYYY-MM-DD.log:
127.0.0.1 GET /status HTTP/1.1 200

The 200 is Tomcat’s response status for that request. A startup message such as Tomcat started on port 9090 belongs to the application log and will not appear in this access log. Configure log retention and a suitable path for your deployment rather than assuming the working directory is permanent.

4. Enable HTTPS in a Separate Profile

For a local HTTPS check, generate a development key store in the project directory. The command creates a self-signed certificate; browsers will not trust it automatically. Keep the generated file out of Git and use a certificate issued for the deployment hostname in production.

keytool -genkeypair -alias local -keyalg RSA -keysize 2048 \
  -storetype PKCS12 -keystore local-dev.p12 -validity 30 \
  -dname "CN=localhost" -storepass changeit -keypass changeit

Create src/main/resources/application-ssl.properties. The ssl profile activates these settings only when requested. The key-store password comes from an environment variable instead of being stored in the project file:

server.port=9443
server.ssl.key-store=file:./local-dev.p12
server.ssl.key-store-password=${DEMO_KEYSTORE_PASSWORD}
server.ssl.key-store-type=PKCS12

Start the packaged JAR with the profile active. On a POSIX shell, export the variable first; in PowerShell, use $env:DEMO_KEYSTORE_PASSWORD='changeit'. The self-signed certificate requires curl -k for this local check; do not disable certificate validation in application clients.

export DEMO_KEYSTORE_PASSWORD=changeit
java -jar target/spring-boot-tomcat-demo-1.0.0.jar --spring.profiles.active=ssl
curl -k https://127.0.0.1:9443/status
# ready

The verified run reports Tomcat started on port 9443 (https) and returns ready over HTTPS. The ssl profile changes the existing connector to HTTPS; it does not create a second HTTP listener. If both protocols are required, configure a second connector explicitly or terminate TLS at a front-end proxy. See the Spring Boot SSL bundle guide for reusable certificate configuration.

5. Customize Tomcat in Java

Properties cover most server settings. When a Tomcat-specific API is necessary, provide a WebServerFactoryCustomizer for TomcatServletWebServerFactory. The example sets the default servlet session timeout to 15 minutes:

package com.howtodoinjava.tomcat;

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

@Configuration
public class TomcatSessionConfig implements WebServerFactoryCustomizer<TomcatServletWebServerFactory> {
    @Override
    public void customize(TomcatServletWebServerFactory factory) {
        factory.addContextCustomizers(context -> context.setSessionTimeout(15));
    }
}

Spring Boot calls customize() while preparing the embedded server, before Tomcat accepts requests. The context customizer then applies the timeout to Tomcat’s servlet context. This setting is about idle HTTP sessions; it does not stop a long-running request after 15 minutes. For the common session-timeout requirement, the simpler server.servlet.session.timeout property is usually enough. Keep this Java form for settings that genuinely require a server-specific API.

# Simpler alternative for the same session timeout:
server.servlet.session.timeout=15m

Do not set both forms merely to repeat the same value. The property is portable across supported servlet servers, while the Java customizer directly depends on Tomcat.

6. FAQs

6.1. Why does the access-log file stay empty after startup?

Tomcat writes access entries for completed HTTP requests, not for starting the server. Send a request to the configured address and port, then check the log directory. With buffered logging, writes may also appear later. The example disables buffering to make the result easy to inspect.

curl http://127.0.0.1:9090/status
# Look under tomcat-work/logs after the request completes.

6.2. Does changing server.port update an HTTPS listener too?

server.port selects the port of the configured embedded server connector. With the ssl profile above, that connector uses HTTPS on 9443. Without the profile, the HTTP connector uses port 9090. The two profile launches are separate application runs, so they do not create two listeners in one process.

java -jar target/spring-boot-tomcat-demo-1.0.0.jar --server.port=9091
# HTTP on 9091; this does not activate the ssl profile.

7. Conclusion

Use server.* properties for common Tomcat settings such as the port, address, access log, and TLS key store. Keep development TLS material out of source control, and verify the listener with an actual HTTP or HTTPS request. Reach for a Tomcat factory customizer only when a property cannot express the configuration you need.

Happy Learning!

The complete runnable example is in the Spring Boot embedded Tomcat project folder.