Spring Boot Servlet Containers: Port, SSL/TLS, Graceful Shutdown

Spring Boot ships with embedded servlet containers, which is convenient until you need to debug a port conflict at 2am or watch requests get dropped during a rolling deployment. This guide walks through port configuration, SSL/TLS setup, and graceful shutdown—the three container settings that matter most in production.

Understanding Embedded Servlet Containers

Introduction

An embedded servlet container gives a Spring Boot web application its HTTP server without requiring a separately installed application server. This guide explains how embedded Tomcat, Jetty, and Undertow receive requests, how to configure ports and server behavior, and how container choices affect deployment and runtime operations.

Customizing the Server Port

Default Behavior

Out of the box, Spring Boot listens on port 8080. The server.port property controls this, with SERVER_PORT as an environment variable fallback.

Configuration Options

# Change the port
server.port=8080

# Bind to a specific interface
server.address=0.0.0.0

# Pick a random available port (handy for tests)
server.port=0

server:
  port: 8443
  address: 127.0.0.1

When to Use Custom Ports

Custom ports make sense when:

• You are running multiple microservices on the same host
• Your deployment platform assigns ports dynamically (Cloud Foundry, Heroku)
• You need to isolate internal services from external-facing ones
• You want to avoid port conflicts in local development

When to Skip Custom Ports

Don’t overconfigure ports if:

• Your organization enforces a standard port layout
• Your platform handles port routing automatically
• You are just spinning up a quick demo

Servlet Container Lifecycle

Here is how the container moves through its phases:

graph TD
    A[Application Starts] --> B[Embedded Container Created]
    B --> C[Network Socket Binds to Port]
    C --> D[HTTP Connector Initialized]
    D --> E[Application Ready - Requests Accepted]
    E --> F[Shutdown Signal Received]
    F --> G[Graceful Shutdown Phase]
    G --> H[In-Flight Requests Complete]
    H --> I[Container Stops - Socket Closed]
    I --> J[Application Context Closed]

The key phase is “Graceful Shutdown Phase” – new connections stop, but existing requests get to finish.

Configuring SSL/TLS

Why SSL Matters

Even services behind a load balancer can have traffic intercepted. TLS encrypts what crosses the network, and these days there is really no excuse to skip it for any service that handles meaningful data.

If you need a refresher on the TLS protocol stack, see our SSL/TLS and HTTPS guide.

Generating a Keystore

You need a Java KeyStore (JKS) holding your certificate and private key:

# Create a new keystore with a key pair
keytool -genkeypair -alias springboot -keyalg RSA \
  -keysize 2048 -keystore keystore.jks \
  -validity 365 -storepass changeit -keypass changeit

# Export the certificate if you need external systems to trust it
keytool -exportcert -alias springboot -file certificate.cer \
  -keystore keystore.jks -storepass changeit

For anything beyond local development, get a certificate from a real CA. Let’s Encrypt works well for public services. Internal PKI or your company’s security team is the right path for enterprise internal services.

SSL Configuration in Spring Boot

# Basic SSL setup
server.port=8443
server.ssl.enabled=true
server.ssl.key-store=classpath:keystore.jks
server.ssl.key-store-password=changeit
server.ssl.key-password=changeit
server.ssl.key-alias=springboot

# Tighten it down
server.ssl.protocol=TLS
server.ssl.enabled-protocols=TLSv1.3,TLSv1.2
server.ssl.ciphers=TLS_AES_256_GCM_SHA384,TLS_AES_128_GCM_SHA256

server:
  port: 8443
  ssl:
    enabled: true
    key-store: "classpath:keystore.jks"
    key-store-password: "changeit"
    key-password: "changeit"
    key-alias: "springboot"
    protocol: "TLS"
    enabled-protocols:
      - "TLSv1.3"
      - "TLSv1.2"
    ciphers:
      - "TLS_AES_256_GCM_SHA384"
      - "TLS_AES_128_GCM_SHA256"

Certificate Types

Type	When to use it	Good	Bad
Self-signed	Local dev only	Instant	Not trusted anywhere
CA-issued	Production	Trusted universally	Costs money, setup delay
Let’s Encrypt	Public services	Free, auto-renewal	Needs domain validation
Internal PKI	Enterprise internal	Fits your org	Requires running a PKI

When to Enable SSL

Turn it on when:

• The service is reachable from outside your network
• Compliance matters (PCI-DSS, HIPAA, SOC2, whatever applies to your situation)
• Services talk to each other across machines
• Your security team requires it

You can probably skip it when:

• Everything is localhost only
• A service mesh handles mTLS for you
• You are in early prototyping and performance tracing is the priority

Graceful Shutdown

Without graceful shutdown, a SIGTERM kills requests mid-flight. Connections drop, transactions roll back, users get errors. Graceful shutdown lets in-flight requests finish before the process exits.

Enabling It

server.shutdown=graceful
spring.lifecycle.timeout-per-shutdown-phase=30s

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

How It Works

sequenceDiagram
    participant K8s as Kubernetes
    participant App as Spring Boot App
    participant LB as Load Balancer

    K8s->>App: SIGTERM Signal
    Note over App: Shutdown begins
    App->>LB: Health check failure
    Note over LB: Removed from rotation
    LB->>App: Existing requests continue
    loop In-Flight Requests
        App->>App: Processing...
    end
    App-->>K8s: Shutdown complete
    Note over App: Process exits cleanly

The health endpoint starts returning failures, the load balancer drains the instance, existing requests complete, then the process stops.

Setting the Timeout

Default is 30 seconds. Size it to your actual request patterns:

• What is your p99 latency?
• Do you have long-running requests (file uploads, report generation)?
• What does your Kubernetes terminationGracePeriodSeconds allow?

# If you know you have longer-running requests
spring.lifecycle.timeout-per-shutdown-phase=60s

When It Matters

Graceful shutdown is worth the configuration when:

• Requests touch databases or message queues
• You have external API dependencies
• You are running in Kubernetes
• Dropped connections would leave data in an inconsistent state

When You Can Skip It

It is safe to disable graceful shutdown when:

• Requests are stateless and finish in milliseconds
• Blue-green deployments route traffic before the old instance stops
• It is a dev or test environment
• A dropped request has no side effects

Implementation Checklist

Port Configuration

• Pick the right port for each environment
• Keep a record of any non-standard ports
• Check firewall rules before deploying
• Make sure health endpoints are reachable on the right port

SSL/TLS Setup

• Get certificates from a CA (not self-signed for production)
• Keep the keystore out of version control
• Use strong passwords (and store them in a secrets manager, not a properties file)
• Lock down protocols to TLS 1.2 and up
• Set up HSTS headers
• Redirect HTTP to HTTPS

Graceful Shutdown Checklist

• Set server.shutdown=graceful
• Triage your request duration and set the timeout accordingly
• Align with your Kubernetes terminationGracePeriodSeconds
• Actually test shutdown under load before going to production
• Keep an eye on shutdown duration in production

When to Use / When NOT to Use

Custom Ports Use Cases

Custom ports make sense when you are running multiple microservices on the same host, your deployment platform assigns ports dynamically (Cloud Foundry, Heroku), you need to isolate internal services from external-facing ones, or you want to avoid port conflicts in local development.

When NOT to Use Custom Ports

Do not add custom port configuration if your organization enforces a standard port layout, your platform handles port routing automatically, or you are just spinning up a quick demo. Unnecessary port configuration creates operational overhead and becomes yet another thing to document and maintain.

When to Use SSL/TLS

Turn on SSL when the service is reachable from outside your network, compliance matters (PCI-DSS, HIPAA, SOC2), services talk to each other across machines, or your security team requires it.

When to Skip SSL/TLS

You can skip SSL when everything is localhost-only, a service mesh handles mTLS for you, or you are in early prototyping where performance tracing is the priority.

When to Enable Graceful Shutdown

Graceful shutdown is worth the configuration when requests touch databases or message queues, you have external API dependencies, you are running in Kubernetes, or dropped connections would leave data in an inconsistent state.

When to Disable Graceful Shutdown

It is safe to disable when requests are stateless and finish in milliseconds, blue-green deployments route traffic before the old instance stops, it is a dev or test environment, or a dropped request has no side effects.

Production Failure Scenarios

Port Conflict at Startup

Symptom: Application fails to start with “Port 8080 already in use.”

Cause: Another process is bound to the same port. This happens after failed deployments that did not terminate cleanly, or when running multiple instances locally without accounting for port offsets.

Fix: Run netstat -tlnp | grep <port> to find the conflicting process. Either stop it or change your port configuration. In Kubernetes, use a Service to map from a stable external port to your container port rather than hardcoding port numbers.

SSL Handshake Failures in Production

Symptom: Clients report “SSL handshake failed” or “certificate chain incomplete” errors.

Cause: The certificate has expired, the intermediate CA certificate is missing from the keystore, or the client does not trust the signing CA.

Fix: Check certificate expiration with keytool -list -v -keystore keystore.jks. For production, automate renewal using cert-manager with Let’s Encrypt for public services, or your internal PKI for private services. Always include the full certificate chain in the keystore.

Graceful Shutdown Timeout Too Short

Symptom: Deployments cause intermittent connection resets and 503 errors even with graceful shutdown enabled.

Cause: spring.lifecycle.timeout-per-shutdown-phase is shorter than your actual request processing time. When the timeout fires, in-flight requests are killed mid-execution.

Fix: Profile your actual request durations under load. Set the shutdown timeout to at least 2x your p99 latency. If you have long-running requests (file uploads, batch jobs), size the timeout accordingly and coordinate with your Kubernetes terminationGracePeriodSeconds.

Secrets Leaked Through Properties Files

Symptom: Keystore passwords appear in logs, error reports, and git history.

Cause: Passwords were stored in application.properties or application.yml which is committed to version control.

Fix: Pull all secrets from environment variables or a secrets manager. Spring Boot reads server.ssl.key-store-password from ${KEYSTORE_PASSWORD} natively. Use Kubernetes Secrets, HashiCorp Vault, or AWS Secrets Manager for production secret management.

Trade-Off Table

Configuration	Port Customization	SSL/TLS Setup	Graceful Shutdown
Complexity	Low	Medium (keystore management)	Low
Risk if misconfigured	Deployment failure	Service unreachable or insecure	Connection drops on deploy
Automation available	No	cert-manager (Let’s Encrypt)	No
Required for compliance	No	Often yes (PCI, HIPAA, SOC2)	Often yes
Performance impact	None	Encryption overhead (~2-3%)	None
Debugging difficulty	Easy (port conflict)	Medium (chain issues)	Medium (timeout tuning)

Observability Checklist

• Confirm server.port is explicitly set for each environment (do not rely on defaults in production)
• Verify SSL certificate expiration dates are tracked in a monitoring system
• Test graceful shutdown under load before going to production — do not wait for a real deployment to discover the timeout is too short
• Align spring.lifecycle.timeout-per-shutdown-phase with terminationGracePeriodSeconds in your Kubernetes deployment
• Monitor shutdown duration in production — if shutdown regularly approaches the timeout, requests are being killed
• Log the SSL configuration at startup (certificate subject, issuer, validity dates) to aid debugging
• Ensure keystore path is read from an environment variable, not hardcoded in properties
• Verify health endpoints are accessible on the configured port during shutdown

Common Pitfalls / Anti-Patterns

Port Already in Use

Symptom: Application will not start. “Port already in use.”

Fix: netstat -tlnp | grep <port> to find the culprit. Either stop that process or pick a different port.

Certificate Expiration

Symptom: SSL handshake starts failing on a specific date.

Fix: Monitor expiration proactively. keytool -list shows you remaining validity. Automate renewal for production certs.

Shutdown Timeout Too Short

Symptom: Deployments cause intermittent connection resets.

Fix: Bump spring.lifecycle.timeout-per-shutdown-phase. If requests regularly take longer than your timeout, that is a separate problem worth investigating.

Passwords in Plain Text Properties

Symptom: Keystore passwords show up in logs, git history, and error reports.

Fix: Pull secrets from environment variables or a vault. Spring Boot can read server.ssl.key-store-password from ${KEYSTORE_PASSWORD}.

Security Notes

1. Keep keystores out of version control – Add *.jks to .gitignore and use a secrets manager.
2. Rotate certificates before they expire – Automated renewal avoids urgent renewals at midnight.
3. Drop deprecated protocols – SSLv3, TLS 1.0, and TLS 1.1 have known vulnerabilities. Lock to TLS 1.2+.
4. Use strong ciphers only – Your SSL config should not include anything from the 1990s.
5. Consider mTLS for service-to-service – When containers talk to each other, mutual TLS verifies both sides.

Quick Recap Checklist

• Spring Boot includes embedded containers (Tomcat by default)
• Set the port with server.port
• Turn on SSL with server.ssl.enabled=true and point to your keystore
• Enable graceful shutdown with server.shutdown=graceful
• Match spring.lifecycle.timeout-per-shutdown-phase to your request patterns
• Align the application shutdown timeout with your Kubernetes terminationGracePeriodSeconds
• Keep keystores and passwords out of source control

Interview Questions

Further Reading

• Embedded Web Servers: Tomcat, Jetty, Undertow — Compare servlet container options beyond the defaults
• SSL/TLS and HTTPS — Protocol stack deep dive and HTTPS setup
• mTLS (Mutual TLS) — Service-to-service certificate authentication
• Spring Boot Actuator Deep Dive — Production-ready endpoints including health and shutdown
• Spring Boot Configuration Properties — Externalized configuration patterns
• Spring Boot Profiles and Environments — Environment-specific container configuration
• Spring Boot Testing — Testing servlet container behavior including SSL and shutdown

Conclusion

Spring Boot’s embedded servlet containers expose three production-critical configuration axes: the port you bind to, the TLS setup protecting your traffic, and the graceful shutdown behavior protecting in-flight requests during deployments.

Port configuration is simple in principle—server.port—but production systems need explicit port declarations per environment rather than relying on defaults, plus validation that firewall rules and health endpoints align with whatever port is chosen. SSL/TLS configuration requires managing a Java KeyStore containing your certificate and private key, keeping that keystore out of version control, and locking down protocols to TLS 1.2 minimum while preferring TLS 1.3. The keystore password belongs in a secrets manager, never in a properties file.

Graceful shutdown is the most commonly forgotten of the three. Without server.shutdown=graceful and a properly sized spring.lifecycle.timeout-per-shutdown-phase, every deployment sends connection resets to clients and potentially rolls back in-flight database transactions. Size the shutdown timeout to at least 2x your p99 request duration, and align it with your Kubernetes terminationGracePeriodSeconds so the kubelet does not SIGKILL your process before it has finished draining. All three of these—port, TLS, shutdown—are low-complexity to configure correctly and high-impact when misconfigured, making them worth treating as a mandatory part of any Spring Boot production checklist.