Close

Spring Boot - Serving JSPs with War Packaging

[Last Updated: Nov 20, 2026]

In the last tutorial, we served JSPs with JAR packaging. In this tutorial, we will change that example to produce 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.


Example

Specifying packaging as war

With Maven, we set the packaging type to war in pom.xml

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

 <groupId>com.logicbig.example</groupId>
 <artifactId>boot-war-serving-jsp</artifactId>
 <version>1.0-SNAPSHOT</version>
 <packaging>war</packaging>
.......
</project>

With Gradle KTS, 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 (Groovy), 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'
}

Location for JSPs

We have two options:

  • Keep the JSP files where they were in the last tutorial: src/main/resources/META-INF/resources/WEB-INF/views/
  • Put them in the traditional webapp folder: src/main/webapp/WEB-INF/views/

Both options work for a war file. In this example, we use the webapp folder. The same folder is used by both Maven and Gradle.

The main class

package com.logicbig.example;

import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;
import org.springframework.boot.builder.SpringApplicationBuilder;
import org.springframework.boot.web.servlet.support.SpringBootServletInitializer;

@SpringBootApplication
public class ExampleMain extends SpringBootServletInitializer {

    @Override
    protected SpringApplicationBuilder configure(SpringApplicationBuilder builder) {
        return builder.sources(ExampleMain.class);
    }

    public static void main(String[] args) {

        SpringApplication app =
                new SpringApplication(ExampleMain.class);
        app.run(args);
    }
}

Why do we need to extend SpringBootServletInitializer?

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.

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.

The main method is ignored by an external container. We still keep it, so we can run the same application from an IDE or from the command line.

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.

If you are interested, look at the onStartup(..) method in the source code of SpringBootServletInitializer.java.

Note: War deployment only works for servlet-based applications (Spring MVC). It is not supported for Spring WebFlux applications.



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".

In Gradle, we use providedRuntime and not compileOnly. A compileOnly dependency is not on the test classpath, so web integration tests would fail.

We also mark the JSP engine (tomcat-embed-jasper) as provided. We need it to run the application locally, but an external Tomcat already has its own JSP engine. JSTL is different: a container like Tomcat does not include it, so JSTL stays a normal dependency and goes inside the war (needed only if your JSPs use JSTL tags).


Complete build scripts

<?xml version="1.0" encoding="UTF-8"?>
<project xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd" xmlns="http://maven.apache.org/POM/4.0.0"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
  <modelVersion>4.0.0</modelVersion>
  <parent>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-parent</artifactId>
    <version>4.1.2</version>
    <relativePath></relativePath>
  </parent>
  <groupId>com.logicbig.example</groupId>
  <artifactId>boot-war-serving-jsp</artifactId>
  <version>1.0-SNAPSHOT</version>
  <packaging>war</packaging>
  <properties>
    <java.version>25</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-tomcat-runtime</artifactId>
      <scope>provided</scope>
    </dependency>
    <dependency>
      <groupId>org.apache.tomcat.embed</groupId>
      <artifactId>tomcat-embed-jasper</artifactId>
      <scope>provided</scope>
    </dependency>
    <dependency>
      <groupId>jakarta.servlet.jsp.jstl</groupId>
      <artifactId>jakarta.servlet.jsp.jstl-api</artifactId>
      <exclusions>
        <exclusion>
          <artifactId>*</artifactId>
          <groupId>jakarta.servlet</groupId>
        </exclusion>
        <exclusion>
          <artifactId>*</artifactId>
          <groupId>jakarta.servlet.jsp</groupId>
        </exclusion>
        <exclusion>
          <artifactId>*</artifactId>
          <groupId>jakarta.el</groupId>
        </exclusion>
      </exclusions>
    </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("jakarta.servlet.jsp.jstl:jakarta.servlet.jsp.jstl-api") {
        exclude(group = "jakarta.servlet")
        exclude(group = "jakarta.servlet.jsp")
        exclude(group = "jakarta.el")
    }

    providedRuntime("org.springframework.boot:spring-boot-starter-tomcat-runtime")
    providedRuntime("org.apache.tomcat.embed:tomcat-embed-jasper")
}
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('jakarta.servlet.jsp.jstl:jakarta.servlet.jsp.jstl-api') {
        exclude group: 'jakarta.servlet'
        exclude group: 'jakarta.servlet.jsp'
        exclude group: 'jakarta.el'
    }

    providedRuntime 'org.springframework.boot:spring-boot-starter-tomcat-runtime'
    providedRuntime 'org.apache.tomcat.embed:tomcat-embed-jasper'
}

JSTL pulls in the Servlet, JSP and EL API jars, but Tomcat already has these classes. Two copies on the classpath can clash and cause errors like ClassNotFoundException: com.sun.el.ExpressionFactoryImpl, so we exclude them.



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.


Output
D:\boot-war-serving-jsp>mvn -q clean package

D:\boot-war-serving-jsp>dir target
Volume in drive D is Joe Projects
Volume Serial Number is D064-5C43

Directory of D:\boot-war-serving-jsp\target

11/18/2026 12:27 AM <DIR> .
11/17/2026 10:02 PM <DIR> ..
11/18/2026 12:26 AM <DIR> boot-war-serving-jsp-1.0-SNAPSHOT
11/18/2026 12:27 AM 19,525,583 boot-war-serving-jsp-1.0-SNAPSHOT.war
11/18/2026 12:27 AM 11,225,227 boot-war-serving-jsp-1.0-SNAPSHOT.war.original
11/17/2026 09:57 PM <DIR> classes
11/17/2026 09:57 PM <DIR> generated-sources
11/18/2026 12:26 AM <DIR> maven-archiver
11/17/2026 09:57 PM <DIR> maven-status
2 File(s) 30,750,810 bytes
7 Dir(s) 8,763,576,320 bytes free

Output
D:\boot-war-serving-jsp>gradle clean -q bootWar
>>> EXECUTING SCRIPT: build.gradle.kts (Kotlin DSL)

D:\boot-war-serving-jsp>dir build\libs
Volume in drive D is Joe Projects
Volume Serial Number is D064-5C43

Directory of D:\boot-war-serving-jsp\build\libs

11/18/2026 01:34 AM <DIR> .
11/18/2026 01:34 AM <DIR> ..
11/18/2026 01:34 AM 21,453,056 boot-war-serving-jsp-1.0-SNAPSHOT.war
1 File(s) 21,453,056 bytes
2 Dir(s) 8,741,076,992 bytes free

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.
  • Run it as an executable war: java -jar boot-war-serving-jsp-1.0-SNAPSHOT.war
  • Run it from the build tool, in exploded form:
Maven:   mvn spring-boot:run
Gradle:  gradle bootRun

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.

Output


Output
$ curl -s "http://localhost:8080"
<h2>From JSP page </h2>

<html>
<body>
Message : a war packaging example
</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. Spring Boot's code is now split into smaller modules. 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.1.2.RELEASE - 4.1.2Version List
    ×

    Version compatibilities of spring-boot-starter-parent with this example:

    • 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-tomcat-runtime (Starter for the Tomcat runtime)
  • tomcat-embed-jasper 11.0.27 (Core Tomcat implementation)
  • jakarta.servlet.jsp.jstl-api 3.0.2 (Jakarta Standard Tag Library API)
  • JDK 25

Build Tool:
Spring Boot - Serving JSPs with War Packaging Select All Download
  • boot-war-serving-jsp
    • src
      • main
        • java
          • com
            • logicbig
              • example
                • MyController.java
          • resources
          • webapp
            • WEB-INF
              • views

    See Also

    Join