By default, Spring Boot applications are packaged as executable JARs with an embedded Tomcat server. While convenient for development and microservices, this approach has limitations in certain scenarios—particularly when dealing with file uploads that need to persist acrross application restarts. Since the embedded server starts fresh each time, any files stored within the application directory are lost after a restart.

To address this, deploying the application as a WAR file on an external Tomcat server allows for persistent file storage outside the application lifecycle. Below are the essential steps to convert a Spring Boot project into a deployable WAR file compatible with Apache Tomcat.

1. Change Packaging Type to WAR

In your pom.xml, set the packaging type explicitly:

<packaging>war</packaging>

2. Exclude Embedded Tomcat

Since the application will run on an external servlet container, exclude the embedded Tomcat starter from spring-boot-starter-web:

<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-web</artifactId>
    <exclusions>
        <exclusion>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-tomcat</artifactId>
        </exclusion>
    </exclusions>
</dependency>

3. Add Servlet API Dependency

Provide the Servlet API at compile time (it’s already available in Tomcat at runtime). Use one of the following—typically the standard Java EE version:

<dependency>
    <groupId>javax.servlet</groupId>
    <artifactId>javax.servlet-api</artifactId>
    <scope>provided</scope>
</dependency>

4. Extend SpringBootServletInitializer

Modify your main application class to inherit from SpringBootServletInitializer and override the configure method:

package com.example.demo;

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 DemoApplication extends SpringBootServletInitializer {

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

    public static void main(String[] args) {
        SpringApplication.run(DemoApplication.class, args);
    }
}

5. Build and Deploy

Run the Maven build command from the project root:

mvn clean package

Upon successful completion ([INFO] BUILD SUCCESS), locate the generated WAR file in the target/ directory. Copy it to the webapps folder of your Tomcat installation. Start (or restart) Tomcat—it will automatically deploy the application.

Access the application via: http://localhost:[port]/[war-file-name-without-extension]/