Close

Spring Boot - Serving Dynamic Pages with Thymeleaf using WAR packaging

[Last Updated: Nov 20, 2026]

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:

<project ....>
 <modelVersion>4.0.0</modelVersion>

 <groupId>com.logicbig.example</groupId>
 <artifactId>boot-thymeleaf-war</artifactId>
 <version>1.0-SNAPSHOT</version>
 <packaging>war</packaging>
.......
</project>
With Gradle, we apply the war plugin.
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".

<dependency>
   <groupId>org.springframework.boot</groupId>
   <artifactId>spring-boot-starter-tomcat</artifactId>
   <scope>provided</scope>
</dependency>
providedRuntime("org.springframework.boot:spring-boot-starter-tomcat-runtime")
providedRuntime 'org.springframework.boot:spring-boot-starter-tomcat-runtime'

Complete build scripts

<project xmlns="http://maven.apache.org/POM/4.0.0"
         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 https://maven.apache.org/xsd/maven-4.0.0.xsd">
    <modelVersion>4.0.0</modelVersion>

    <parent>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-parent</artifactId>
        <version>4.1.2</version>
        <relativePath/>
    </parent>

    <groupId>com.logicbig.example</groupId>
    <artifactId>boot-serve-dynamic-thymeleaf-with-war</artifactId>
    <version>1.0-SNAPSHOT</version>
    <packaging>war</packaging>

    <properties>
        <java.version>21</java.version>
    </properties>

    <dependencies>
        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-web</artifactId>
        </dependency>
        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-thymeleaf</artifactId>
        </dependency>
        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-tomcat-runtime</artifactId>
            <scope>provided</scope>
        </dependency>
    </dependencies>

    <build>
        <plugins>
            <plugin>
                <groupId>org.springframework.boot</groupId>
                <artifactId>spring-boot-maven-plugin</artifactId>
            </plugin>
        </plugins>
    </build>
</project>
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:

Output in the browser


Output
$ curl -s "http://localhost:8080/?name=Joe"
<!DOCTYPE html>
<html>
<head>
<meta charset="UTF-8"/>
<title>Thymeleaf Example</title>
</head>
<body>
<h2>Hello, Joe!</h2>
<p>Server time: <span>2026-11-19T03:11:44</span></p>
<p>Languages:</p>
<ul>
<li>Java</li>
<li>Python</li>
<li>JavaScript</li>
</ul>
</body>
</html>

Version history

  • 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)
  • JDK 21

Build Tool:
Spring Boot - Thymeleaf using WAR packaging Select All Download
  • boot-serve-dynamic-thymeleaf-with-war
    • src
      • main
        • java
          • com
            • logicbig
              • example
        • resources
          • templates
            • home.html

    See Also

    Join