Spring Boot — Administrator & Developer Guide

1. Architecture Overview

Spring Boot is a convention-over-configuration framework built on top of the Spring Framework. It eliminates boilerplate setup by providing auto-configuration, embedded servers, and opinionated defaults while preserving the full power and flexibility of the Spring ecosystem. The framework is designed as a multi-module Gradle project (11,264 source files, ~15M characters of source code) organized around a layered architecture that separates core runtime, auto-configuration, build tooling, and operational features.

The fundamental design principle is auto-configuration through classpath detection: Spring Boot scans the classpath for known libraries, evaluates conditional annotations (@ConditionalOnClass, @ConditionalOnMissingBean, @ConditionalOnProperty), and automatically creates and configures infrastructure beans. This allows applications to work with zero explicit configuration while remaining fully customizable when needed.

Spring Boot also introduces the concept of executable JARs — self-contained archives that embed all dependencies and an application server (Tomcat, Jetty, or Netty), enabling java -jar deployment without external servlet containers.

System Architecture

┌─────────────────────────────────────────────────────────────────┐
│                        Application Code                         │
│  (@SpringBootApplication, Controllers, Services, Repositories) │
├─────────────────────────────────────────────────────────────────┤
│                      Spring Boot Modules                        │
│  ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────────────┐  │
│  │ WebMVC   │ │ WebFlux  │ │ Data JPA │ │ Security         │  │
│  │ Module   │ │ Module   │ │ Module   │ │ Module           │  │
│  └──────────┘ └──────────┘ └──────────┘ └──────────────────┘  │
│  ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────────────┐  │
│  │ Actuator │ │ DevTools │ │ Docker   │ │ Messaging        │  │
│  │ Module   │ │ Module   │ │ Compose  │ │ (Kafka/AMQP/JMS) │  │
│  └──────────┘ └──────────┘ └──────────┘ └──────────────────┘  │
├─────────────────────────────────────────────────────────────────┤
│                    Core & Auto-Configure                        │
│  ┌─────────────────┐  ┌─────────────────────────────────────┐  │
│  │ spring-boot     │  │ spring-boot-autoconfigure           │  │
│  │ (SpringApp,     │  │ (conditional bean creation,         │  │
│  │  ConfigData,    │  │  property binding, classpath        │  │
│  │  Loader)        │  │  detection)                         │  │
│  └─────────────────┘  └─────────────────────────────────────┘  │
├─────────────────────────────────────────────────────────────────┤
│                     Spring Framework 6.2+                       │
│  (IoC Container, AOP, Transaction Management, MVC, WebFlux)    │
├─────────────────────────────────────────────────────────────────┤
│                        JVM (Java 17+)                           │
└─────────────────────────────────────────────────────────────────┘

Note

Spring Boot modules are designed as independently consumable units. An application only loads the modules whose starters are on the classpath. The auto-configure layer acts as the glue — it detects which modules are present and wires them together.

Component Inventory

Technology Stack

Application Lifecycle

main() → SpringApplication.run()
  │
  ├── 1. Create SpringApplication instance
  ├── 2. Publish ApplicationStartingEvent
  ├── 3. Prepare Environment (load application.properties/yml, profiles)
  ├── 4. Publish ApplicationEnvironmentPreparedEvent
  ├── 5. Create ApplicationContext
  ├── 6. Publish ApplicationContextInitializedEvent
  ├── 7. Load bean definitions (component scan, auto-configuration)
  ├── 8. Publish ApplicationPreparedEvent
  ├── 9. Refresh context (instantiate beans, start embedded server)
  ├── 10. Publish ApplicationStartedEvent
  ├── 11. Call ApplicationRunner / CommandLineRunner beans
  ├── 12. Publish ApplicationReadyEvent
  │
  └── Running (serving requests)
       │
       └── Shutdown
            ├── Publish ContextClosedEvent
            ├── Stop embedded server (graceful shutdown)
            └── Destroy beans

Important

The ApplicationFailedEvent is published if startup fails at any stage. Register listeners for this event to implement custom error reporting, cleanup, or alerting on startup failures.

Data Flow — HTTP Request Processing

HTTP Request
  │
  ├── Embedded Server (Tomcat/Jetty/Netty)
  │     └── Servlet Filter Chain / WebFilter Chain
  │           ├── Security Filters (authentication, authorization)
  │           ├── Error Handling (ErrorController / ErrorWebExceptionHandler)
  │           └── DispatcherServlet / DispatcherHandler
  │                 ├── Handler Mapping (URL → Controller method)
  │                 ├── Handler Adapter (invoke method)
  │                 ├── Argument Resolution (@RequestBody, @PathVariable)
  │                 ├── Return Value Handling (JSON serialization)
  │                 └── Exception Resolution (ErrorAttributes)
  │
  └── HTTP Response

2. System Requirements

Runtime Requirements

Build Requirements

Supported Embedded Servers

Supported Databases

3. Configuration Reference

Configuration File Locations and Priority

Spring Boot loads configuration from multiple sources. Later sources override earlier ones:

Configuration File Search Locations

Files are searched in this order (first found wins within each priority level):

1. file:./config/ — a config/ directory in the current working directory
2. file:./config/*/ — immediate subdirectories of config/
3. file:./ — current working directory
4. classpath:/config/ — config package on the classpath
5. classpath:/ — root of the classpath

Important

Profile-specific files (application-{profile}.properties) always override non-profile-specific files, regardless of location. A profile-specific file inside the JAR overrides a non-profile-specific file outside the JAR.

Core Server Properties

SSL/TLS Properties

Tomcat-Specific Properties

DataSource Properties

JPA/Hibernate Properties

Warning

spring.jpa.open-in-view=true (the default) keeps the database session open during the entire HTTP request, which can mask lazy loading issues and hold connections longer. Set to false in production for predictable connection management.

Logging Properties

Actuator Properties

Spring Security Properties

Docker Compose Properties

DevTools Properties

Kafka Properties

gRPC Properties

4. Deployment & Scaling

Executable JAR Deployment

The standard deployment model — a single JAR containing everything:

# Build
./mvnw clean package -DskipTests
# or
./gradlew bootJar

# Deploy
java -jar target/my-app.jar \
  --spring.profiles.active=prod \
  --server.port=8080 \
  -Xms512m -Xmx1g

The executable JAR uses Spring Boot's custom JarLauncher classloader that supports nested JARs — dependencies are stored as-is inside BOOT-INF/lib/ rather than being unpacked and merged.

Container Image Deployment

Buildpacks (recommended — no Dockerfile needed):

./mvnw spring-boot:build-image -Dspring-boot.build-image.imageName=myregistry/myapp:1.0

Dockerfile (manual control):

FROM eclipse-temurin:21-jre-alpine
WORKDIR /app
COPY target/my-app.jar app.jar
EXPOSE 8080
ENTRYPOINT ["java", "-jar", "app.jar"]

Layered Dockerfile (optimized for Docker layer caching):

FROM eclipse-temurin:21-jre-alpine AS builder
WORKDIR /app
COPY target/my-app.jar app.jar
RUN java -Djarmode=tools -jar app.jar extract --layers --launcher

FROM eclipse-temurin:21-jre-alpine
WORKDIR /app
COPY --from=builder /app/app/dependencies/ ./
COPY --from=builder /app/app/spring-boot-loader/ ./
COPY --from=builder /app/app/snapshot-dependencies/ ./
COPY --from=builder /app/app/application/ ./
EXPOSE 8080
ENTRYPOINT ["java", "org.springframework.boot.loader.launch.JarLauncher"]

Tip

The layered approach separates dependencies (which rarely change) from application code (which changes often). Docker caches unchanged layers, dramatically reducing build times for iterative deployments.

Kubernetes Deployment

apiVersion: apps/v1
kind: Deployment
metadata:
  name: my-app
spec:
  replicas: 3
  selector:
    matchLabels:
      app: my-app
  template:
    metadata:
      labels:
        app: my-app
    spec:
      containers:
        - name: my-app
          image: myregistry/myapp:1.0
          ports:
            - containerPort: 8080
            - containerPort: 8081  # management port
          env:
            - name: SPRING_PROFILES_ACTIVE
              value: prod
            - name: SPRING_DATASOURCE_URL
              valueFrom:
                secretKeyRef:
                  name: db-secret
                  key: url
          readinessProbe:
            httpGet:
              path: /actuator/health/readiness
              port: 8081
            initialDelaySeconds: 10
            periodSeconds: 5
          livenessProbe:
            httpGet:
              path: /actuator/health/liveness
              port: 8081
            initialDelaySeconds: 30
            periodSeconds: 10
          resources:
            requests:
              memory: 512Mi
              cpu: 250m
            limits:
              memory: 1Gi
              cpu: 1000m

Scaling Considerations

GraalVM Native Image

Spring Boot supports ahead-of-time compilation to GraalVM native images:

./mvnw -Pnative native:compile
# or
./gradlew nativeCompile

Native images start in milliseconds with minimal memory, suitable for serverless and short-lived workloads. Requires GraalVM JDK and the native-maven-plugin or native Gradle plugin.

Warning

Native images have limitations: no runtime reflection (unless explicitly configured), no dynamic class loading, and some Spring features may require AOT hints. Use @ImportRuntimeHints or RuntimeHintsRegistrar to register reflection, resources, and proxies needed at runtime.

5. Operations

Health Monitoring

Spring Boot Actuator provides health indicators that aggregate into a composite health status:

/actuator/health
├── db (DataSourceHealthIndicator)
├── diskSpace (DiskSpaceHealthIndicator)
├── redis (RedisHealthIndicator)
├── kafka (KafkaHealthIndicator)
├── mongo (MongoHealthIndicator)
└── custom (your HealthIndicator beans)

Custom health indicator:

@Component
public class PaymentGatewayHealthIndicator implements HealthIndicator {

    @Override
    public Health health() {
        boolean reachable = checkPaymentGateway();
        if (reachable) {
            return Health.up()
                .withDetail("gateway", "responsive")
                .withDetail("latencyMs", 45)
                .build();
        }
        return Health.down()
            .withDetail("gateway", "unreachable")
            .build();
    }
}

The health system uses a contributor registry (DefaultHealthContributorRegistry) that supports runtime registration and unregistration of health indicators. The registry is thread-safe with copy-on-write semantics for concurrent access. A reactive variant (DefaultReactiveHealthContributorRegistry) supports non-blocking health checks.

Kubernetes Health Probes

Spring Boot auto-creates readiness and liveness groups for Kubernetes:

management.endpoint.health.probes.enabled=true
# Auto-enabled when running in Kubernetes

Note

Health groups can be customized: management.endpoint.health.group.readiness.include=db,redis ensures the readiness probe reports DOWN only if database or Redis is unavailable, not for unrelated indicators.

Security Auditing

Spring Boot Actuator includes an audit subsystem that tracks security events:

Captured events:

• AUTHENTICATION_SUCCESS — successful login
• AUTHENTICATION_FAILURE — failed login attempt
• AUTHENTICATION_SWITCH — user impersonation/switching
• LOGOUT_SUCCESS — user logout
• Authorization decisions (granted/denied)

The AuthenticationAuditListener converts Spring Security events into AuditEvent objects, capturing the principal name, source IP, and event details. The AuthorizationAuditListener tracks access decisions for authorization monitoring.

Custom audit events are published through the AuditEventRepository:

@Component
public class CustomAuditor {

    private final AuditEventRepository repository;

    public CustomAuditor(AuditEventRepository repository) {
        this.repository = repository;
    }

    public void recordAction(String principal, String action, Map<String, Object> data) {
        repository.add(new AuditEvent(principal, action, data));
    }
}

Metrics and Observability

Spring Boot auto-configures Micrometer meter registries for multiple monitoring systems:

Built-in metrics include:

• JVM memory, GC, threads, classloader statistics
• HTTP request/response timing and counts
• DataSource connection pool statistics
• Cache hit/miss rates
• Spring Integration message channel throughput
• Kafka consumer lag and producer throughput

Tip

Use management.metrics.tags.application=my-app to add a global tag to all metrics, making it easier to filter by application in multi-service dashboards.

Logging Operations

Change log levels at runtime via the /actuator/loggers endpoint:

# View current level
curl http://localhost:8080/actuator/loggers/com.example

# Change level
curl -X POST http://localhost:8080/actuator/loggers/com.example \
  -H "Content-Type: application/json" \
  -d '{"configuredLevel": "DEBUG"}'

Application Info

The /actuator/info endpoint aggregates information from:

info.app.name=My Application
info.app.version=1.0.0
info.app.description=A Spring Boot service

# Build info (auto-populated by build plugin)
management.info.build.enabled=true

# Git info (from git.properties)
management.info.git.enabled=true
management.info.git.mode=full

# Java runtime info
management.info.java.enabled=true

# OS info
management.info.os.enabled=true

6. Performance

JVM Tuning

Virtual Threads (Java 21+)

Enable virtual threads for dramatically improved I/O-bound throughput:

spring.threads.virtual.enabled=true

This configures Tomcat/Jetty to use virtual threads for request handling, allowing thousands of concurrent connections without the thread pool being the bottleneck.

Connection Pool Tuning

HikariCP (default connection pool) — key settings:

spring.datasource.hikari.maximum-pool-size=20
spring.datasource.hikari.minimum-idle=5
spring.datasource.hikari.idle-timeout=300000
spring.datasource.hikari.max-lifetime=1800000
spring.datasource.hikari.connection-timeout=30000
spring.datasource.hikari.leak-detection-threshold=60000

Note

The optimal pool size formula: connections = (core_count * 2) + effective_spindle_count. For a 4-core server with SSD, start with 10 connections. Monitor the hikaricp.connections.active metric to tune.

Startup Optimization

• Lazy initialization: spring.main.lazy-initialization=true — defer bean creation until first use (faster startup, slower first request)
• AOT processing: Use GraalVM native image or Spring AOT for ahead-of-time compilation
• Class Data Sharing: -XX:SharedArchiveFile for reduced class loading time
• Slim dependencies: Exclude unused starters and transitive dependencies

7. Security

Auto-Configured Security

When spring-boot-starter-security is on the classpath, Spring Boot auto-configures:

• All HTTP endpoints require authentication
• A default user (user) with a generated password (logged at startup)
• Form-based login at /login
• HTTP Basic authentication
• CSRF protection (enabled for browser clients)
• Security headers (X-Frame-Options, X-Content-Type-Options, etc.)
• Session fixation protection

Production Security Checklist

• [ ] Configure a proper user store (JDBC, LDAP, OAuth2 provider)
• [ ] Enable HTTPS (server.ssl.* properties)
• [ ] Set server.error.include-stacktrace=never and server.error.include-message=never
• [ ] Restrict Actuator endpoints: management.endpoints.web.exposure.include=health,info
• [ ] Use a separate management port: management.server.port=8081
• [ ] Disable DevTools in production (automatic when running as JAR)
• [ ] Set spring.jpa.open-in-view=false to prevent lazy-loading security risks
• [ ] Configure CORS: @CrossOrigin or WebMvcConfigurer.addCorsMappings()
• [ ] Enable rate limiting (via Spring Cloud Gateway or a reverse proxy)
• [ ] Rotate secrets using environment variables or vault, not properties files

Caution

Never commit application.properties files containing passwords, API keys, or other secrets to version control. Use environment variables, Spring Cloud Vault, Kubernetes Secrets, or AWS Secrets Manager for production secret management.

OAuth2 and OIDC

Spring Boot auto-configures OAuth2 login and resource server:

# OAuth2 Client (login with Google)
spring.security.oauth2.client.registration.google.client-id=your-client-id
spring.security.oauth2.client.registration.google.client-secret=your-secret

# OAuth2 Resource Server (JWT validation)
spring.security.oauth2.resourceserver.jwt.issuer-uri=https://auth.example.com

SAML2 Service Provider

spring.security.saml2.relyingparty.registration.my-idp.assertingparty.metadata-uri=https://idp.example.com/metadata

8. Developer Internals

Repository Structure

spring-boot/
├── build-plugin/
│   ├── spring-boot-gradle-plugin/     Gradle build plugin
│   ├── spring-boot-maven-plugin/      Maven build plugin
│   └── spring-boot-antlib/            Ant build support
├── buildpack/
│   └── spring-boot-buildpack-platform/ CNB lifecycle, Docker API
├── buildSrc/                          Custom Gradle conventions
├── cli/
│   └── spring-boot-cli/              Command-line interface
├── configuration-metadata/
│   └── ...-changelog-generator/       Config property changelog
├── core/
│   ├── spring-boot/                   Core runtime (SpringApplication, config, loader)
│   ├── spring-boot-autoconfigure/     Auto-configuration engine
│   ├── spring-boot-autoconfigure-processor/  Compile-time annotation processor
│   ├── spring-boot-docker-compose/    Docker Compose integration
│   ├── spring-boot-properties-migrator/  Deprecated property detection
│   ├── spring-boot-test/              Testing support
│   └── spring-boot-test-autoconfigure/ Test slice annotations
├── documentation/
│   └── spring-boot-docs/             Antora-based documentation site
├── integration-test/                  Cross-module integration tests
├── loader/
│   ├── spring-boot-loader/           Executable JAR classloader
│   ├── spring-boot-loader-tools/     JAR repackaging tools
│   └── spring-boot-jarmode-tools/    Layer extraction tools
├── module/
│   ├── spring-boot-actuator/         Actuator endpoints core
│   ├── spring-boot-actuator-autoconfigure/  Actuator auto-config
│   ├── spring-boot-devtools/         Developer tools
│   ├── spring-boot-health/           Health contributor registry
│   ├── spring-boot-jackson/          Jackson ObjectMapper config
│   ├── spring-boot-jpa/              JPA/Hibernate integration
│   ├── spring-boot-security/         Security auto-config
│   ├── spring-boot-webmvc/           Spring MVC integration
│   ├── spring-boot-webflux/          WebFlux integration
│   ├── spring-boot-web-server/       Embedded server factories
│   ├── spring-boot-grpc-server/      gRPC server support
│   ├── spring-boot-grpc-client/      gRPC client support
│   ├── spring-boot-micrometer-metrics/ Metrics integration
│   ├── spring-boot-micrometer-tracing/  Distributed tracing
│   ├── spring-boot-opentelemetry/    OpenTelemetry support
│   └── ... (60+ additional modules)
├── platform/
│   └── spring-boot-dependencies/     Dependency BOM
├── smoke-test/                       End-to-end smoke tests
├── starter/                          ~60 curated starter POMs
├── system-test/                      System-level tests
└── test-support/                     Shared test utilities

Architecture Deep Dive

Auto-Configuration Mechanism

Auto-configuration classes are registered in META-INF/spring/org.springframework.boot.autoconfigure.AutoConfiguration.imports. Each class uses conditional annotations:

Evaluation order is controlled by @AutoConfigureOrder, @AutoConfigureBefore, and @AutoConfigureAfter. The spring-boot-autoconfigure-processor generates metadata at compile time to optimize condition evaluation without loading classes.

Configuration Loading System

The org.springframework.boot.context.config package implements a pluggable configuration loading system:

• ConfigDataEnvironmentPostProcessor — bootstraps the config loading pipeline
• ConfigDataLocationResolver — resolves location strings (e.g., classpath:, file:, optional:) to actual resources
• ConfigDataLoader — loads configuration from resolved resources
• ConfigData — container for loaded property sources with options (IGNORE_IMPORTS, IGNORE_PROFILES, PROFILE_SPECIFIC)
• ConfigDataActivationContext — tracks active profiles during loading
• ConfigTreePropertySource — supports config tree format (Kubernetes ConfigMap volume mounts)

The system supports import statements (spring.config.import) for loading from additional sources, enabling integration with Vault, Consul, and custom configuration servers.

Executable JAR Loader

Spring Boot's custom classloader (JarLauncher, WarLauncher) handles nested JAR files:

my-app.jar
├── META-INF/MANIFEST.MF (Main-Class: JarLauncher, Start-Class: com.example.MyApp)
├── org/springframework/boot/loader/  (loader classes)
├── BOOT-INF/
│   ├── classes/     (application classes)
│   ├── lib/         (dependency JARs, stored as-is)
│   └── classpath.idx  (classpath ordering)
└── BOOT-INF/layers.idx  (layer ordering for Docker)

The loader registers custom URL protocol handlers (jar:nested:) for accessing classes inside nested JARs without extraction. The jarmode=tools entry point provides layer extraction for optimized Docker builds.

Error Handling Architecture

Both MVC and WebFlux share the ErrorAttributes contract:

• DefaultErrorAttributes captures: timestamp, status, error, exception, message, errors (validation), trace, path
• ErrorAttributeOptions controls which fields are included based on server.error.include-* properties
• The error handling implements HandlerExceptionResolver (MVC) / WebExceptionHandler (WebFlux) and stores error details in request attributes

Error attributes include:

• Binding errors: extracted from BindingResult for form validation failures
• Method validation errors: from MethodValidationResult for parameter validation
• Stack traces are optionally captured and included based on configuration

Docker Compose Integration

The org.springframework.boot.docker.compose.core package provides:

• DockerCli — executes Docker CLI commands, parses output
• DefaultDockerCompose — manages lifecycle (up, down, start, stop)
• DefaultConnectionPorts — maps container ports to host ports, handles ephemeral port assignment
• DockerHost — resolves Docker host address (supports host networking mode)
• DockerCliInspectResponse — models Docker inspect output with Config, HostConfig, and NetworkSettings

Port mapping supports both TCP and UDP protocols, and handles IPv4 address filtering for multi-homed containers.

Module Reference

Core Runtime (core/spring-boot)

Key classes:

• SpringApplication — entry point, bootstraps the application context
• SpringApplicationBuilder — fluent API for customizing SpringApplication
• ApplicationRunner / CommandLineRunner — post-startup callback interfaces
• ExitCodeGenerator — allows beans to influence the exit code
• ApplicationPidFileWriter — writes PID file for process management

CLI (cli/spring-boot-cli)

Entry point: SpringCli.main() — creates a CommandRunner named "spring" and registers commands via ServiceLoader<CommandFactory>.

Default commands (from DefaultCommandFactory):

• version (VersionCommand) — prints Spring CLI v{version}
• init (InitCommand) — scaffolds a new project from start.spring.io
• encodepassword (EncodePasswordCommand) — BCrypt password encoding

Built-in commands (registered in main):

• help (HelpCommand) — displays help for commands
• hint (HintCommand) — provides shell auto-completion hints (hidden)
• shell (ShellCommand) — interactive shell mode

Extension: drop JARs in ${spring.home}/lib/ext/ — they are added to the classloader.

Build Plugins

Gradle plugin (build-plugin/spring-boot-gradle-plugin):

• JavaPluginAction — registers bootJar, bootWar, bootRun, bootBuildImage tasks
• ApplicationPluginAction — configures distribution plugin integration
• DependencyManagementPluginAction — imports spring-boot-dependencies BOM
• KotlinPluginAction — aligns Kotlin dependency versions
• CyclonedxPluginAction — integrates SBOM generation
• JarTypeFileSpec — filters out dependencies-starter and development-tool JARs

Maven plugin (build-plugin/spring-boot-maven-plugin):

• spring-boot:run — runs the application with fork/no-fork options
• spring-boot:repackage — creates the executable JAR/WAR
• spring-boot:build-image / build-image-no-fork — builds OCI images using Buildpacks
• spring-boot:build-info — generates build-info.properties
• spring-boot:aot-generate / aot-test-generate — AOT compilation

DevTools (module/spring-boot-devtools)

DevToolsSettings loads from META-INF/spring-devtools.properties across all JARs on the classpath:

• restart.include.* — regex patterns for JARs to monitor for changes
• restart.exclude.* — regex patterns for JARs to ignore
• defaults.* — property defaults for development

The restart mechanism uses two classloaders: a base classloader (for stable libraries) and a restart classloader (for application classes). Only the restart classloader is discarded and recreated on changes.

Code Patterns and Conventions

Testing Strategy

Test infrastructure:

• @GradleCompatibility — parameterized testing across Gradle versions
• @DisabledIfDockerUnavailable — skip Docker-dependent tests
• GradleBuild test kit — fluent API for Gradle integration tests
• ApplicationContextRunner — lightweight context testing without starting a full server

Potential Improvements

Based on community feature requests:

• gRPC observability — GrpcExchanges support in Actuator similar to HttpExchanges (issue #49828)
• gRPC baggage propagation — automatic baggage propagation from gRPC metadata (issue #49832)
• gRPC TLS rotation — support for server and client TLS certificate rotation (issues #49833, #49831)
• Virtual thread schedulers — Task Scheduler and Executor with virtual threads (issue #49949)
• Kafka health — tie @KafkaListener health into Actuator Health (issue #49899)
• MongoDB observability — configure MongoDB MicrometerObservabilitySettings (issue #49186)
• Actuator endpoint caching — support caching for endpoint read operations with parameters (issue #30696)
• OAuth2 + interface clients — auto-configuration for OAuth2 with interface HTTP clients (issue #46956)
• DataSource wrapping — allow autoconfigured DataSource beans to be wrapped in TransactionAwareDataSourceProxy (issue #50062)
• Nested configuration metadata — improved metadata for non-static nested classes and records (issues #50133, #50096, #50121)

Contributing

The project uses:

• License: Apache License 2.0
• Build: Gradle with custom convention plugins in buildSrc/
• Style: Checkstyle configuration in config/checkstyle/
• Kotlin style: Detekt configuration in config/detekt/
• HTTP validation: nohttp configuration in config/nohttp/
• Documentation: Antora-based site with AsciiDoc source in documentation/spring-boot-docs/

# Build the project
./gradlew build

# Run tests
./gradlew test

# Run integration tests
./gradlew intTest

# Run Docker tests (requires Docker)
./gradlew dockerTest

Note

The project uses mavenCentral() and a Shibboleth releases repository (for OpenSAML/Shibboleth dependencies used by SAML2 support). All dependency versions are managed by the spring-boot-dependencies BOM in the platform/ directory.

9. Integration Points

Spring Ecosystem Integration

Third-Party Integration

Testcontainers Service Connections

Spring Boot provides @ServiceConnection support for:

10. Troubleshooting

Diagnostic Approach

Application issue?
├── Won't start
│   ├── Check error message and stack trace
│   ├── Run with --debug for auto-config report
│   ├── Check /actuator/conditions (if partially started)
│   └── Verify Java version, dependency versions
├── Unexpected behavior
│   ├── Check active profiles: /actuator/env
│   ├── Check applied auto-configs: /actuator/conditions
│   ├── Check bean definitions: /actuator/beans
│   └── Check property sources: /actuator/env
├── Performance issue
│   ├── Check /actuator/metrics for JVM stats
│   ├── Check connection pool: hikaricp.* metrics
│   ├── Check GC activity: jvm.gc.* metrics
│   └── Enable heap dump: -XX:+HeapDumpOnOutOfMemoryError
└── Security issue
    ├── Check security filter chain ordering
    ├── Enable debug logging: logging.level.org.springframework.security=DEBUG
    └── Check /actuator/httptrace for request history

Error: No qualifying bean of type 'X' available

Cause: Spring cannot find a bean to inject. Common reasons: missing component scan, missing starter, or missing @Component/@Service annotation.

Solution:

1. Ensure the class is annotated with a stereotype annotation
2. Verify the class is in a package scanned by @SpringBootApplication
3. Check if auto-configuration is disabled for the relevant feature

Prevention: Keep all application classes in subpackages of the main application class package.

Error: Default security is misconfigured when spring-boot-actuator-autoconfigure is present and spring-boot-health is not

Cause: Dependency mismatch where Actuator auto-configuration expects the health module but it is not on the classpath. (Community issue #50190)

Solution:

1. Ensure spring-boot-starter-actuator (which transitively includes health) is used instead of cherry-picking individual actuator modules
2. If using custom module selection, add spring-boot-health explicitly

Prevention: Use the actuator starter rather than individual module dependencies.

Error: Elasticsearch Rest5Client auto-configuration misconfigures underlying HTTP client

Cause: The auto-configuration for Elasticsearch's Rest5Client may apply incorrect HTTP client settings in certain configurations. (Community issue #50189)

Solution:

1. Define a custom RestClientBuilder bean to override auto-configuration
2. Explicitly configure Elasticsearch connection properties

Prevention: Test Elasticsearch connectivity in integration tests before deploying.

Warning

When upgrading Spring Boot versions, run your application with spring-boot-properties-migrator on the classpath. It detects deprecated properties in your configuration and logs replacement suggestions at startup. Remove it after migration is complete.

11. Quick Reference

Spring Boot CLI Commands

Gradle Plugin Tasks

Maven Plugin Goals

Actuator Endpoints

Common Annotations