Review and refine where possible war deployments following 4.0's modularisation

[makigumo]

Steps to reproduce:

• Create basic Spring Boot project via this link start.spring.io
• Add basic controller, e.g.

package com.example.demo;

import org.springframework.http.ResponseEntity;
import org.springframework.stereotype.Controller;
import org.springframework.web.bind.annotation.GetMapping;

@Controller
public class RootController {

    @GetMapping("/")
    public ResponseEntity<String> index() {
        return ResponseEntity.ok("Hello World");
    }
}

• Build boot war ./gradlew bootWar
• Copy to build/libs/demo-0.0.1-SNAPSHOT.war to Tomcat webapps directory, e.g.

 cp build/libs/demo-0.0.1-SNAPSHOT.war $TOMCAT_HOME/webapps/demo.war

• Start Tomcat
• Open http://localhost:8080/demo in a web browser or use curl http://localhost:8080/demo/ from command line.

Expected

The text Hello World should be shown.

Actual

A 404 error is shown.

Notes/Observations

• When changing to Spring Boot 3.5.5 it is working as expected.
• Running with the embedded tomcat server, e.g. java -jar build/libs/demo-0.0.1-SNAPSHOT.war, is working as expected.
• Running with ./gradlew bootRun is working as expected.

Environment

• macOS 15.6
• Java 24.0.2 (Azul)
• Tomcat 11.0.10

[wilkinsona]

We still have a little bit of work to do for war deployments after the modularisation efforts in 4.0. The following dependencies will give you a war file that can be deployed to a servlet container and run using java -jar your-app.war:

dependencies {
	implementation("org.springframework.boot:spring-boot-starter-webmvc")
	providedRuntime("org.apache.tomcat.embed:tomcat-embed-core")
	testImplementation("org.springframework.boot:spring-boot-starter-test")
	testRuntimeOnly("org.junit.platform:junit-platform-launcher")
}

As a minimum we need to update the documentation and the configuration generated by start.spring.io. There may be more that we can do though so that configuration that worked with 3.x will also work with 4.0. We'll use this issue to track that work.

[wilkinsona]

Jetty's also a problem here, although it doesn't work in 3.5.x either. The servlet API isn't on the compile classpath, causing the app's servlet initialiser to fail to compile with these dependencies:

implementation('org.springframework.boot:spring-boot-starter-web') {
	exclude module: "spring-boot-starter-tomcat"
}
providedRuntime 'org.springframework.boot:spring-boot-starter-jetty'

And with these dependencies that app compiles but fails to start as org.slf4j.LoggerFactory is missing and Logback needs it:

implementation('org.springframework.boot:spring-boot-starter-web') {
	exclude module: "spring-boot-starter-tomcat"
}
implementation 'org.springframework.boot:spring-boot-starter-jetty'
providedRuntime 'org.springframework.boot:spring-boot-starter-jetty'

We can either document the configuration that's needed (Jetty is quite a bit more complicated than Tomcat) or we could introduce new modules that contain only the dependencies that should move into WEB-INF/lib-provided when building a war file that is to be deployed to a container. If we go down the module route, spring-boot-starter-tomcat and spring-boot-starter-jetty could depend on spring-boot-tomcat-server and spring-boot-jetty-server (or whatever we decide to call them) to avoid having to maintain the dependencies in two places.

[wilkinsona]

Unfortunately, it doesn't appear to be possible to provide an extra module that works with both Maven and Gradle as they treat provided dependencies different. With Maven, when a dependency is declared in the provided scope, it and all of its transitive dependencies only actually move into that scope if they're not also in another scope. Gradle does the opposite so when a dependency is declared in providedRuntime it's removed from the normal runtime classpath.

As a result of the differences described above, the existing spring-boot-starter-tomcat works with Maven but not Gradle. If we introduced a new module that met Gradle's needs it would not work with Maven. As a result, different arrangements would be required for Maven and Gradle.