What you’ll learn
Getting started
- Running the application in embedded Tomcat
Modifying the POM
Configuring the server
Changing the application startup process
Building and running the application
Great work! You’re done!
Contribute to this guide

Running a Spring Boot MVC application as a WAR file

20 minutes

Prerequisites:

Table of contents

Learn how to run a Spring Boot Model-View-Controller (MVC) application as a WAR file in Open Liberty instead of an embedded container.

What you’ll learn

You will learn how to use Maven to run a sample Spring Boot Model-View-Controller (MVC) application as a WAR file in Open Liberty. The sample application that you will be working with is from Spring’s Serving Web Content with Spring MVC guide. If you are not familiar with Spring Boot or Spring MVC, it will be helpful to to complete that guide before proceeding.

Three main steps are required to build the WAR file from the Spring Boot MVC application. First, you will modify the project POM, primarily to remove Tomcat and add the Liberty Maven Plugin. Next, you will configure the Open Liberty server through a server.xml file. Finally, you will modify the application to run from a traditional WAR deployment. After these steps are complete, you will package and deploy the application to Open Liberty. This guide will not cover running the Spring Boot MVC test cases in Open Liberty, and the starting project does not include test code or dependencies.

Getting started

The fastest way to work through this guide is to clone the Git repository and use the projects that are provided inside:

git clone https://github.com/openliberty/guide-springboot-mvc.git
cd guide-springboot-mvc

The start directory contains the starting project that you will build upon.

The finish directory contains the finished project that you will build.

Before you begin, make sure you have all the necessary prerequisites.

Running the application in embedded Tomcat

You might first want to run the initial Spring Boot application without modifications. Move to the start directory and run the sample application in embedded Tomcat. Java 8 or later is required.

cd start
mvn spring-boot:run

Notice that the console output will display that the application is running in Tomcat on port 8080. Now access the application at the following URL: http://localhost:8080/greeting?name=GreetingApplication

You’ll see from the page output that the name request parameter from the URL was received and handled:

Hello, GreetingApplication!

You are now ready to build the application into a WAR file and run in Open Liberty instead of embedded Tomcat.

Modifying the POM

You will modify the pom.xml file in several steps. For reference, the completed pom.xml is provided at the end of this section.

Navigate to the start directory to begin.

Changing the packaging type

Start by setting the application packaging type to liberty-assembly. No packaging type is specified in the starting project, so add <packaging>liberty-assembly</packaging> after <version>1.0-SNAPSHOT</version> in the POM.

Adding POM properties

Next, add the <start-class>hello.Application</start-class> property to the properties block, which should look this afterwards:

<properties>
    <java.version>1.8</java.version>
    <start-class>hello.Application</start-class>
</properties>

The start-class property references the fully qualified Spring Boot startup class; in this case src/main/java/hello/Application.java. This property indicates the main class to use for the runnable JAR.

Adding and modifying dependencies

In the project dependencies, the spring-boot-starter-thymeleaf artifact depends on the spring-boot-starter-web dependency. Because spring-boot-starter-web uses Tomcat as the default embedded server, you will need to exclude it in your configuration to run your application on Open Liberty. Modify the spring-boot-starter-thymeleaf dependency definition to look like this:

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

You can also remove the spring-boot-devtools dependency since you are running on Open Liberty.

Adding the Liberty Maven Plugin

Finally, replace the spring-boot-maven-plugin configuration with the liberty-maven-plugin configuration inside the <build> <plugins> block:

<plugin>
    <groupId>net.wasdev.wlp.maven.plugins</groupId>
    <artifactId>liberty-maven-plugin</artifactId>
    <version>2.6</version>
    <extensions>true</extensions>
    <!-- Specify configuration, executions for liberty-maven-plugin -->
    <configuration>
        <serverName>MVCServer</serverName>
        <assemblyArtifact>
            <groupId>io.openliberty</groupId>
            <artifactId>openliberty-runtime</artifactId>
            <version>RELEASE</version>
            <type>zip</type>
        </assemblyArtifact>
        <configFile>src/main/liberty/config/server.xml</configFile>
        <assemblyInstallDirectory>${project.build.directory}/liberty</assemblyInstallDirectory>
        <packageFile>${project.build.directory}/MVCServerPackage.jar</packageFile>
        <features>
            <acceptLicense>true</acceptLicense>
        </features>
        <include>runnable</include>
        <installAppPackages>all</installAppPackages>
        <appsDirectory>apps</appsDirectory>
        <stripVersion>true</stripVersion>
        <looseApplication>true</looseApplication>
        <skipTestServer>true</skipTestServer>
    </configuration>
</plugin>

In this plugin, you specify an Open Liberty server called MVCServer which the application will be deployed to. You also set <include>runnable</include> to indicate that the application will be packaged into a runnable JAR, which is set to be called MVCServerPackage.jar in the <packageFile> parameter.

Further documentation of the plugin configuration is provided in the ci.maven repository.

Completed pom.xml

After updating your pom.xml, it should look as shown in the following example:

<?xml version="1.0" encoding="UTF-8"?>
<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 http://maven.apache.org/xsd/maven-4.0.0.xsd">
    <modelVersion>4.0.0</modelVersion>

    <groupId>io.openliberty.guides</groupId>
    <artifactId>guide-spring-boot-mvc</artifactId>
    <version>1.0-SNAPSHOT</version>
    <packaging>liberty-assembly</packaging>

    <parent>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-parent</artifactId>
        <version>2.0.1.RELEASE</version>
    </parent>

    <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>
            <exclusions>
                <exclusion>
                    <groupId>org.springframework.boot</groupId>
                    <artifactId>spring-boot-starter-tomcat</artifactId>
                </exclusion>
            </exclusions>
        </dependency>
    </dependencies>

    <properties>
        <java.version>1.8</java.version>
        <start-class>hello.Application</start-class>
    </properties>

    <build>
        <plugins>
            <plugin>
                <groupId>net.wasdev.wlp.maven.plugins</groupId>
                <artifactId>liberty-maven-plugin</artifactId>
                <version>2.6</version>
                <extensions>true</extensions>
                <!-- Specify configuration, executions for liberty-maven-plugin -->
                <configuration>
                    <serverName>MVCServer</serverName>
                    <assemblyArtifact>
                        <groupId>io.openliberty</groupId>
                        <artifactId>openliberty-runtime</artifactId>
                        <version>RELEASE</version>
                        <type>zip</type>
                    </assemblyArtifact>
                    <configFile>src/main/liberty/config/server.xml</configFile>
                    <assemblyInstallDirectory>${project.build.directory}/liberty</assemblyInstallDirectory>
                    <packageFile>${project.build.directory}/MVCServerPackage.jar</packageFile>
                    <features>
                        <acceptLicense>true</acceptLicense>
                    </features>
                    <include>runnable</include>
                    <installAppPackages>all</installAppPackages>
                    <appsDirectory>apps</appsDirectory>
                    <stripVersion>true</stripVersion>
                    <looseApplication>true</looseApplication>
                    <skipTestServer>true</skipTestServer>
                </configuration>
            </plugin>
        </plugins>
    </build>
    
</project>

Configuring the server

Next, provide the configuration for the Open Liberty server. Create a src/main/liberty/config/server.xml server configuration file.

<?xml version="1.0" encoding="UTF-8"?>
<server description="new server">
    <application context-root="/"
        location="guide-spring-boot-mvc.war"></application>

    <featureManager>
        <feature>servlet-4.0</feature>
    </featureManager>

    <httpEndpoint id="defaultHttpEndpoint" httpPort="9080"
        httpsPort="9443" />

    <applicationManager autoExpand="true" />

    <webContainer deferServletLoad="false"/>

</server>

In the server configuration, the application context root is mapped to the server root directory. The servlet-3.1 feature is also needed for running the application. The <applicationManager autoExpand="true" /> configuration automatically expands the WAR file and the <webContainer deferServletLoad="false"/> configuration automatically loads the Spring application endpont once the server is ready.

Changing the application startup process

Traditionally, a Spring Boot application running on an embedded server such as Tomcat calls SpringApplication.run(…) in its main class. In this case, the main class is hello.Application. However, your class needs to extend SpringBootServletInitializer when being deployed to an Open Liberty server. Replace the original code in src/main/java/hello/Application.java with the following code:

package hello;

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

@SpringBootApplication
public class Application extends SpringBootServletInitializer {

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

Also recall that you previously set the <start-class> parameter in the POM properties above to hello.Application. This tells the server that your application starts its execution from this class.

This concludes the code changes; you are now ready to build and run your application in Open Liberty.

Building and running the application

To build the application, run the Maven install phase from the active command-line session in the start directory:

mvn install

This command builds the application and creates a .war file in the target directory. It also configures and installs Open Liberty into the target/liberty/wlp directory.

Next, run the Maven liberty:start-server goal:

mvn liberty:start-server

This goal starts an Open Liberty server instance. Your Maven pom.xml is already configured to start the application in this server instance.

Now verify that your Spring Boot application is running in Open Liberty. Navigate to the following URL: http://localhost:9080/greeting?name=GreetingApplication. Notice that the port has changed to 9080, as this is the default port used by Open Liberty. You will see the same output on this page as in the starting application.

If you make changes to the code, use the Maven compile goal to rebuild the application and have the running Open Liberty instance pick them up automatically: