Deploy a Spring Boot WAR into a Tomcat Server

Spring Boot applications can be packaged as JAR or WAR files. While JAR files are self-contained and runnable with an embedded server, WAR files are deployed to external servers like Apache Tomcat. This tutorial will guide you through the steps to deploy a Spring Boot WAR file into a Tomcat server.

Prerequisites

• JDK 17 or later
• Maven or Gradle
• Apache Tomcat installed
• IDE (IntelliJ IDEA, Eclipse, etc.)

Step 1: Set Up a Spring Boot Project

1.1 Create a New Spring Boot Project

Use Spring Initializr to create a new project with the following dependencies:

• Spring Web

Download and unzip the project, then open it in your IDE.

1.2 Configure application.properties

Set up the application properties for your project. This file is located in the src/main/resources directory.

# src/main/resources/application.properties

server.port=8080

Step 2: Modify the Project to Generate a WAR File

2.1 Update pom.xml for Maven

If you are using Maven, modify the pom.xml to package the application as a WAR file and to include the Tomcat dependency for provided scope.

<packaging>war</packaging>

<dependencies>
    <!-- Other dependencies -->

    <!-- Provided Tomcat dependency -->
    <dependency>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-tomcat</artifactId>
        <scope>provided</scope>
    </dependency>
</dependencies>

<build>
    <plugins>
        <plugin>
            <groupId>org.apache.maven.plugins</groupId>
            <artifactId>maven-war-plugin</artifactId>
        </plugin>
        <plugin>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-maven-plugin</artifactId>
            <configuration>
                <excludeDevtools>false</excludeDevtools>
            </configuration>
        </plugin>
    </plugins>
</build>

2.2 Update build.gradle for Gradle

If you are using Gradle, modify the build.gradle to package the application as a WAR file and to include the Tomcat dependency for provided scope.

plugins {
    id 'org.springframework.boot' version '3.2.0'
    id 'io.spring.dependency-management' version '1.1.0'
    id 'java'
    id 'war'
}

group = 'com.example'
version = '0.0.1-SNAPSHOT'
sourceCompatibility = '17'

repositories {
    mavenCentral()
}

dependencies {
    implementation 'org.springframework.boot:spring-boot-starter-web'
    providedRuntime 'org.springframework.boot:spring-boot-starter-tomcat'
}

bootWar {
    mainClassName = 'com.example.demo.DemoApplication'
}

2.3 Extend SpringBootServletInitializer

Create a class that extends SpringBootServletInitializer to configure the application when it's launched by a servlet container.

package com.example.demo;

import org.springframework.boot.builder.SpringApplicationBuilder;
import org.springframework.boot.web.servlet.support.SpringBootServletInitializer;
import org.springframework.context.annotation.Configuration;

@Configuration
public class ServletInitializer extends SpringBootServletInitializer {

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

2.4 Main Application Class

Ensure your main application class is annotated with @SpringBootApplication.

package com.example.demo;

import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;

@SpringBootApplication
public class DemoApplication {

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

2.5 Create a Simple REST Controller

Create a simple REST controller to test the application.

package com.example.demo.controller;

import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RestController;

@RestController
public class HelloController {

    @GetMapping("/hello")
    public String hello() {
        return "Hello, World!";
    }
}

Step 3: Build the WAR File

3.1 Package the Application

Build and package your Spring Boot application as a WAR file using Maven or Gradle.

For Maven:

./mvnw clean package

For Gradle:

./gradlew clean build

Explanation:

• These commands compile the code, run tests, and package the application into a WAR file located in the target (for Maven) or build/libs (for Gradle) directory.

Step 4: Deploy the WAR File to Tomcat

4.1 Copy the WAR File to Tomcat

Locate the generated WAR file (e.g., demo-0.0.1-SNAPSHOT.war) and copy it to the webapps directory of your Tomcat installation.

4.2 Start Tomcat

Start the Tomcat server. You can do this by running the startup script in the bin directory of your Tomcat installation.

For Windows:

./bin/startup.bat

For Unix/Linux:

./bin/startup.sh

4.3 Access the Application

Open your browser and navigate to http://localhost:8080/demo-0.0.1-SNAPSHOT/hello. You should see the following response:

Hello, World!

Step 5: Troubleshooting and Common Issues

5.1 Tomcat Logs

If the application does not start correctly, check the Tomcat logs in the logs directory for any errors or stack traces that can help diagnose the problem.

5.2 Application Context Path

The application will be accessible using the context path derived from the WAR file name. If you need to change the context path, rename the WAR file before copying it to the webapps directory, or configure the context path in the server.xml file of your Tomcat installation.

5.3 Common Errors

• ClassNotFoundException: Ensure that all necessary dependencies are included and the provided scope is set correctly.
• Port Conflicts: Ensure that the port specified in application.properties does not conflict with other applications.

Conclusion

In this tutorial, you have learned how to deploy a Spring Boot application as a WAR file to an external Tomcat server. We covered:

• Setting up a Spring Boot project.
• Modifying the project to generate a WAR file.
• Building the WAR file.
• Deploying the WAR file to a Tomcat server.
• Accessing the deployed application.

By following these steps, you can deploy your Spring Boot applications to any external servlet container, providing flexibility in how you deploy and manage your applications.