We are going to modify the last tutorial's example to package it as a war file. A war file can be deployed to an external servlet container (like Apache Tomcat). It can also still be run on its own.
Thymeleaf reads templates from the classpath, so it does not matter if they are inside a jar, inside a war, or in an IDE folder. We only change the main class and the build files.
Example
Specifying packaging as war
With Maven, we set the packaging type to in pom.xml:
plugins {
java
war
id("org.springframework.boot") version "4.1.2"
id("io.spring.dependency-management") version "1.1.7"
}
With Gradle, we apply the
war plugin.
plugins {
id 'java'
id 'war'
id 'org.springframework.boot' version '4.1.2'
id 'io.spring.dependency-management' version '1.1.7'
}
Excluding the embedded Tomcat server from the deployable war file
The Spring MVC starter has a dependency on spring-boot-starter-tomcat (embedded Tomcat). If this embedded server goes inside our war, it can clash with the servlet container where we deploy the war. So we mark it as provided. This means: "it is needed to compile and run locally, but the container will supply it, so do not put it in the war".
plugins {
java
war
id("org.springframework.boot") version "4.1.2"
id("io.spring.dependency-management") version "1.1.7"
}
println(">>> EXECUTING SCRIPT: build.gradle.kts (Kotlin DSL)")
group = "com.logicbig.example"
version = "1.0-SNAPSHOT"
java {
sourceCompatibility = JavaVersion.VERSION_25
}
repositories {
mavenCentral()
}
dependencies {
implementation("org.springframework.boot:spring-boot-starter-web")
implementation("org.springframework.boot:spring-boot-starter-thymeleaf")
providedRuntime("org.springframework.boot:spring-boot-starter-tomcat-runtime")
}
plugins {
id 'java'
id 'war'
id 'org.springframework.boot' version '4.1.2'
id 'io.spring.dependency-management' version '1.1.7'
}
println ">>> EXECUTING SCRIPT: build.gradle (Groovy DSL)"
group = 'com.logicbig.example'
version = '1.0-SNAPSHOT'
java {
sourceCompatibility = JavaVersion.VERSION_25
}
repositories {
mavenCentral()
}
dependencies {
implementation 'org.springframework.boot:spring-boot-starter-web'
implementation 'org.springframework.boot:spring-boot-starter-thymeleaf'
providedRuntime 'org.springframework.boot:spring-boot-starter-tomcat-runtime'
}
The main class
To make a deployable war file, we need a subclass of SpringBootServletInitializer. We override its configure method to tell Spring Boot which class is the main source of our application.
@SpringBootApplication
public class ExampleMain extends SpringBootServletInitializer {
@Override
protected SpringApplicationBuilder configure(SpringApplicationBuilder builder) {
return builder.sources(ExampleMain.class);
}
public static void main(String[] args) {
SpringApplication.run(ExampleMain.class, args);
}
}
Why do we need to extend SpringBootServletInitializer?
Here is the reason, in simple steps:
When we run a jar (or run from an IDE), Java calls the main method. Our main method calls SpringApplication.run(), and the application starts.
When we deploy a war to an external container, the container starts the application. It does not call our main method.
Instead, the servlet specification has a feature called ServletContainerInitializer. The container finds all implementations of this interface and calls them at startup.
Spring provides one such implementation. It finds all classes that implement WebApplicationInitializer and calls their onStartup method.
SpringBootServletInitializer implements WebApplicationInitializer. In its onStartup method, it creates a SpringApplication using the sources we give in the configure method. Then it runs it. This gives us auto-configuration, bean wiring, and everything else Spring Boot does for us.
Tip: In current versions, if the class that extends SpringBootServletInitializer is also the @SpringBootApplication class (like in our example), the configure override is optional. Spring Boot adds that class as the source by itself. We keep the override here because it makes the idea clear.
Note: War deployment only works for servlet-based applications (Spring MVC). It is not supported for Spring WebFlux applications.
Building and running the war application
To build the war file:
Maven: mvn package
Gradle: gradle bootWar
The file is created in the target folder (Maven) or in the build/libs folder (Gradle). Because we used the Spring Boot build plugin, this war is also executable. The provided dependencies (like the embedded Tomcat) are packaged in a special WEB-INF/lib-provided folder. An external container ignores that folder, but java -jar uses it.
Note for Gradle: when the Spring Boot plugin is applied together with the war plugin, the normal war task creates a "plain" war (the file name ends with -plain.war, with no Spring Boot loader). Use the bootWar task for the deployable and executable war.
Creating war with Maven
Output
D:\boot-serve-dynamic-thymeleaf-with-war>mvn clean -q package D:\boot-serve-dynamic-thymeleaf-with-war>dir target Volume in drive D is Joe Projects Volume Serial Number is D064-5C43
Directory of D:\boot-serve-dynamic-thymeleaf-with-war\target
11/19/2026 02:55 AM <DIR> . 11/19/2026 02:55 AM <DIR> .. 11/19/2026 02:55 AM <DIR> boot-serve-dynamic-thymeleaf-with-war-1.0-SNAPSHOT 11/19/2026 02:55 AM 21,557,334 boot-serve-dynamic-thymeleaf-with-war-1.0-SNAPSHOT.war 11/19/2026 02:55 AM 15,153,606 boot-serve-dynamic-thymeleaf-with-war-1.0-SNAPSHOT.war.original 11/19/2026 02:55 AM <DIR> classes 11/19/2026 02:55 AM <DIR> generated-sources 11/19/2026 02:55 AM <DIR> maven-archiver 11/19/2026 02:55 AM <DIR> maven-status 2 File(s) 36,710,940 bytes 7 Dir(s) 8,529,166,336 bytes free
Creating war with Gradle
Output
D:\boot-serve-dynamic-thymeleaf-with-war>gradle clean -q bootWar >>> EXECUTING SCRIPT: build.gradle.kts (Kotlin DSL) D:\boot-serve-dynamic-thymeleaf-with-war>dir build\libs Volume in drive D is Joe Projects Volume Serial Number is D064-5C43
Directory of D:\boot-serve-dynamic-thymeleaf-with-war\build\libs
11/19/2026 04:04 AM <DIR> . 11/19/2026 04:04 AM <DIR> .. 11/19/2026 04:04 AM 21,555,819 boot-serve-dynamic-thymeleaf-with-war-1.0-SNAPSHOT.war 1 File(s) 21,555,819 bytes 2 Dir(s) 8,490,369,024 bytes free
Running
We have three ways to run it:
Deploy the war to a servlet container that supports Servlet 6.1, for example Apache Tomcat 11. Copy the file to Tomcat's webapps folder. The context path is the war file name, unless you name the file ROOT.war. So the page is at http://localhost:8080/boot-thymeleaf-war-1.0-SNAPSHOT/.
Run it as an executable war: java -jar boot-thymeleaf-war-1.0-SNAPSHOT.war
Run it from the build tool or IDE, in exploded form:
Spring Boot 1.x:SpringBootServletInitializer was in a different package. Since Spring Boot 2.0 it is in org.springframework.boot.web.servlet.support.
Spring Boot 2.x: It used Java 8+ and the old javax.servlet API. In Gradle, we used apply plugin: 'war' and providedRuntime 'org.springframework.boot:spring-boot-starter-tomcat'. The web starter was called spring-boot-starter-web.
Spring Boot 3.x: It needs Java 17 or newer. All javax.* packages changed to jakarta.* (Jakarta EE 9/10, Servlet 6.0). An old javax-based servlet container (like Tomcat 9) cannot run these wars any more. We need Tomcat 10.1 or newer.
Spring Boot 4.x (current): Spring Framework 7, Jakarta EE 11, Servlet 6.1. Use Tomcat 11 or newer as the external container. The web starter is renamed to spring-boot-starter-webmvc. In Gradle, the "provided" dependency is now spring-boot-starter-tomcat-runtime (it was spring-boot-starter-tomcat before). In Maven, the provided dependency is still spring-boot-starter-tomcat.
Example Project
Dependencies and Technologies Used:
Spring Boot 4.1.2 Corresponding Spring Framework Version 7.0.10 Version Compatibility: 2.0.0.RELEASE - 4.1.2Version List
×
Version compatibilities of spring-boot-starter-parent with this example:
2.0.0.RELEASE
2.1.2.RELEASE
2.1.3.RELEASE
2.1.4.RELEASE
2.1.5.RELEASE
2.1.6.RELEASE
2.1.7.RELEASE
2.1.8.RELEASE
2.1.9.RELEASE
2.1.10.RELEASE
2.1.11.RELEASE
2.1.12.RELEASE
2.1.13.RELEASE
2.1.14.RELEASE
2.1.15.RELEASE
2.1.16.RELEASE
2.1.17.RELEASE
2.1.18.RELEASE
2.2.0.RELEASE
2.2.1.RELEASE
2.2.2.RELEASE
2.2.3.RELEASE
2.2.4.RELEASE
2.2.5.RELEASE
2.2.6.RELEASE
2.2.7.RELEASE
2.2.8.RELEASE
2.2.9.RELEASE
2.2.10.RELEASE
2.2.11.RELEASE
2.2.12.RELEASE
2.2.13.RELEASE
2.3.0.RELEASE
2.3.1.RELEASE
2.3.2.RELEASE
2.3.3.RELEASE
2.3.4.RELEASE
2.3.5.RELEASE
2.3.6.RELEASE
2.3.7.RELEASE
2.3.8.RELEASE
2.3.9.RELEASE
2.3.10.RELEASE
2.3.11.RELEASE
2.3.12.RELEASE
2.4.0
2.4.1
2.4.2
2.4.3
2.4.4
2.4.5
2.4.6
2.4.7
2.4.8
2.4.9
2.4.10
2.4.11
2.4.12
2.4.13
2.5.0
2.5.1
2.5.2
2.5.3
2.5.4
2.5.5
2.5.6
2.5.7
2.5.8
2.5.9
2.5.10
2.5.11
2.5.12
2.5.13
2.5.14
2.5.15
2.6.0
2.6.1
2.6.2
2.6.3
2.6.4
2.6.5
2.6.6
2.6.7
2.6.8
2.6.9
2.6.10
2.6.11
2.6.12
2.6.13
2.6.14
2.6.15
2.7.0
2.7.1
2.7.2
2.7.3
2.7.4
2.7.5
2.7.6
2.7.7
2.7.8
2.7.9
2.7.10
2.7.11
2.7.12
2.7.13
2.7.14
2.7.15
2.7.16
2.7.17
2.7.18
Java 17 min
3.0.0
3.0.1
3.0.2
3.0.3
3.0.4
3.0.5
3.0.6
3.0.7
3.0.8
3.0.9
3.0.10
3.0.11
3.0.12
3.0.13
3.1.0
3.1.1
3.1.2
3.1.3
3.1.4
3.1.5
3.1.6
3.1.7
3.1.8
3.1.9
3.1.10
3.1.11
3.1.12
3.2.0
3.2.1
3.2.2
3.2.3
3.2.4
3.2.5
3.2.6
3.2.7
3.2.8
3.2.9
3.2.10
3.2.11
3.2.12
3.3.0
3.3.1
3.3.2
3.3.3
3.3.4
3.3.5
3.3.6
3.3.7
3.3.8
3.3.9
3.3.10
3.3.11
3.3.12
3.3.13
3.4.0
3.4.1
3.4.2
3.4.3
3.4.4
3.4.5
3.4.6
3.4.7
3.4.8
3.4.9
3.4.10
3.4.11
3.4.12
3.4.13
3.5.0
3.5.1
3.5.2
3.5.3
3.5.4
3.5.5
3.5.6
3.5.7
3.5.8
3.5.9
3.5.10
3.5.11
3.5.12
3.5.13
3.5.14
3.5.15
3.5.16
4.0.0
4.0.1
4.0.2
4.0.3
4.0.4
4.0.5
4.0.6
4.0.7
4.0.8
4.0.9
4.1.0
4.1.1
4.1.2
Versions in green have been tested.
spring-boot-starter-web (Starter for building web, including RESTful, applications using Spring MVC. Uses Tomcat as the default embedded container (deprecated in favor of spring-boot-starter-webmvc))
spring-boot-starter-thymeleaf (Starter for using Thymeleaf)
spring-boot-starter-tomcat-runtime (Starter for the Tomcat runtime)