Configure and Deploy Spring Boot applications to Open Liberty
You can enable Open Liberty to configure and deploy Spring Boot applications. Open Liberty also provides tools that optimize the deployment of Spring Boot applications to containers.
To enable Open Liberty to support a Spring Boot application, add one of the Spring Boot Support features to your server.xml
file. When you deploy a Spring Boot application, Open Liberty disables the web container that is embedded in the application and uses the Open Liberty web container instead. You can deploy one Spring Boot application for each server configuration. Open Liberty supports deploying Spring Boot applications as JAR files or as WAR files.
The examples in the following sections use a sample hellospringboot.jar
application that is similar to the finished application from the Spring Boot Building an Application with Spring Boot guide. If you are not familiar with Spring Boot, complete that guide first. The guide includes instructions to build the application as an executable JAR, which is the primary file format that is used in these examples.
As an alternative to using the optimized Spring Boot deployment described in the following sections, you can also deploy a Spring Boot application like any standard Jakarta EE WAR. For more information, see the Running a Spring Boot 3.x application WAR file on Liberty blog post.
Although the examples in the following sections use an example JAR application file, the Open Liberty configuration for the optimized Spring Boot deployment is the same for JAR and WAR files.
Deploying a Spring Boot JAR or WAR application to Open Liberty from the command line
Complete the following steps to deploy a sample Spring Boot application by manually configuring your server.xml
file and running the server from the command line. To deploy a Spring Boot application to Open Liberty by using Maven, see the Containerizing, packaging, and running a Spring Boot application Open Liberty guide.
In the following steps, you create a Liberty server instance, deploy your Spring Boot JAR or WAR application, and specify the default HTTP port for the server instance. By default, Liberty deploys the Spring Boot application with the default host configuration. The example uses a hellospringboot.jar
sample application and 9090
for the default HTTP port.
Run the
server create helloserver
command from thewlp/bin
directory to create a server and name ithelloserver
.server create helloserver
This command creates the
/usr/servers/helloserver/apps
directory.Enable the version of the Open Liberty Spring Boot Support feature that your application requires by adding it to the
featureManager
element of theserver.xml
file.If your application uses Spring Boot 1.5.8+, enable the springBoot-1.5 feature.
If your application uses Spring Boot 2.0.1+, enable the springBoot-2.0 feature.
If your application uses Spring Boot 3.0.4+, enable the springBoot-3.0 feature.
The
hellospringboot.jar
application uses thespring-boot-starter-web
dependency, which also requires you to enable a Jakarta Servlet feature, as shown in the followingserver.xml
file example:<featureManager> <feature>springBoot-3.0</feature> <feature>servlet-6.0</feature> </featureManager>
For more information about the Open Liberty features that are required to support certain Spring Boot Starters, see the Spring Boot Support feature.
Copy the
hellospringboot.jar
application into the/usr/servers/helloserver/apps
directory that theserver create
command created.Configure the JAR or WAR application by updating the
server.xml
file.Specify the JAR application location by using the springBootApplication element. Configure the HTTP port for the default host to
9090
by replacing thehttpPort="9080"
attribute value with anhttpPort="9090"
attribute value.<springBootApplication location="hellospringboot.jar"/> <httpEndpoint id="defaultHttpEndpoint" host="*" httpPort="9090" />
Alternatively, specify the WAR application location by using the springBootApplication element. Configure the HTTP port for the default host to
9090
by replacing thehttpPort="9080"
attribute value with anhttpPort="9090"
attribute value.<springBootApplication location="hellospringboot.war"/> <httpEndpoint id="defaultHttpEndpoint" host="*" httpPort="9090" />
Start the server in the foreground by running the
server run
command:server run helloserver
Test the application in a browser at the http://localhost:9090 URL.
You deployed a Spring Boot sample application to Open Liberty. When you finish testing the application, run the server stop
command.
server stop helloserver
Deploying a Spring Boot JAR or WAR application from the dropins directory
Alternatively, you can deploy a Spring Boot application without configuring the server.xml
file by using the Open Liberty dropins
directory. You can use these steps to deploy either a JAR file or a WAR file.
Complete steps 1 and 2 of Deploying a Spring Boot application to Open Liberty from the command line.
Create a
/spring
subdirectory in the/usr/servers/helloserver/dropins/
directory.Copy the
hellospringboot.jar
orhellospringboot.war
file to the/usr/servers/helloserver/dropins/spring/
directory.Start the server in the foreground by running the
server run
command:server run helloserver
Test the application in a browser by going to the
http://localhost:9080
URL.The default HTTP endpoint is used to service the application. When you finish testing the application, run the
server stop helloserver
command.
Defining Spring Boot application arguments
When you deploy a Spring Boot application to Open Liberty, you can configure application arguments to override the application property defaults. The following example uses the sample hellospringboot.jar
application that you deployed to Open Liberty in the previous section.
When you start a Spring Boot application from the command line as an executable JAR file, you start with a list of command-line arguments, as shown in the following example.
java -jar hellospringboot.jar --server.servlet.context-path=/mypath --myapp.arg=true
By default, the SpringApplication
Spring Boot class converts any command-line argument that starts with dashes (--
) to a property and adds it to the Spring environment.
When you deploy a Spring Boot application to Open Liberty, you can configure the command-line argument for the application with the applicationArgument
element within the springBootApplication
element. Use these elements when you want to override application property defaults that are included in the Spring Boot application.
In the following example, the hellospringboot.jar
Spring Boot application deployment to Open Liberty is configured to pass multiple command-line arguments. The two properties that are used in the example are the Spring Boot application properties for configuring the server.servlet.context-path
application context path and the spring.mvc.servlet.path
Spring dispatcher servlet path.
For more information about these and other Spring Boot application properties, see Spring Boot common application properties.
Find the
springBootApplication
element in theserver.xml
file of thehelloserver
server that you created in the previous section.<springBootApplication location="hellospringboot.jar"/>
Add a command-line argument for the application with the
applicationArgument
element and pass the--server.servlet.context-path=/testpath1
argument to change the application context root to/testpath1
, as shown in the following example.<springBootApplication location="hellospringboot.jar"> <applicationArgument>--server.servlet.context-path=/testpath1</applicationArgument> </springBootApplication>
Start the server in the foreground by running the
server run
command.server run helloserver
Test the application in a browser by going to the http://localhost:9090/testpath1 URL.
Without stopping the server, change the context path to
testpath2
.<springBootApplication location="hellospringboot.jar"> <applicationArgument>--server.servlet.context-path=/testpath2</applicationArgument> </springBootApplication>
Test the application in a browser by going to the http://localhost:9090/testpath2 URL.
Without stopping the server, add another
applicationArgument
element to configure the Spring dispatcher servlet path, as shown in the following example.<springBootApplication location="hellospringboot.jar"> <applicationArgument>--server.context-path=/testpath2</applicationArgument> <applicationArgument>--server.servlet-path=/mydispatcher</applicationArgument> </springBootApplication>
The Spring Boot application stops and restarts with the same context path.
Test the application in a browser by going to the http://localhost:9090/testpath2/mydispatcher URL.
Configuring thin Spring Boot applications
You can thin a Spring Boot application to create more efficient container layers and optimize resource usage.
A Spring Boot application JAR or WAR file is a self-contained artifact. It packages all of the application dependencies inside the final artifact alongside the application content, including an embedded server implementation, such as Tomcat, Jetty, or Undertow. The result is a fat artifact that is easy to run on any server that has a JVM. However, this result is a large artifact, even for the smallest hello world
Spring Boot web application.
With a microservices architecture, the application content that is included in a Spring Boot application JAR file can be much smaller than the Spring Boot framework dependencies. A large application JAR file might be costly to deploy if your application needs frequent updates. For example, if you use Docker to deploy your application to the cloud, each time you update your application, you need to build a new Docker layer. This layer includes both your updated application content and all the Spring Boot framework dependencies. This process results in large Docker layers when you update your application in the cloud.
Open Liberty can create Docker layers that use resources efficiently when you deploy frequent updates to your microservice applications in the cloud.
The following example uses the springBootUtility thin
command. This command separates the Spring Boot application content from its packaged dependencies, resulting in a thin Spring Boot application.
The examples in this section use a hellospringboot.jar
file, but the procedure is the same for thinning Spring Boot WAR applications. However, after you thin a Spring Boot WAR application by using the springBootUtility thin
command, the thin application must run on the Open Liberty server and can no longer run as a stand-alone WAR. Furthermore, any configuration details that are specified in the server.xml
file must be defined in a springBootApplication element. The thin WAR application does not read configuration that is specified in a generic webApplication
element in the server.xml
file.
Configure the thin Spring Boot application JAR or WAR file and the library dependencies.
Deploy the
hellospringboot.jar
orhellospringboot.war
application as explained in the Deploying a Spring Boot application to Open Liberty from the command line section.Deploy the library dependencies to the
wlp/usr/shared/resources/lib.index.cache/
directory.
Run the
springBootUtility thin
command with the necessary options to create thehellospringboot-thin.jar
thin application in thedropins/spring
directory of thehelloserver
server configuration and to cache the dependencies to theusr/servers/helloserver/apps/
directory.wlp/bin/springBootUtility thin \ --sourceAppPath=full_path_to/wlp/usr/servers/helloserver/apps/hellospringboot.jar \ --targetLibCachePath=full_path_to/wlp/usr/shared/resources/lib.index.cache \ --targetThinAppPath=full_path_to/wlp/usr/servers/helloserver/apps/hellospringboot-thin.jar
For more information about the available command-line options, see the springBootUtility thin command.
Update the
server.xml
file to specify the location of the thin application.Replace the value of the
springBootApplication location
element to specify thehellospringboot-thin.jar
application.<springBootApplication location="hellospringboot-thin.jar"/>
Start the server in the foreground by running the
server run
command.server run helloserver
Test the application in a browser by going to the
http://localhost:9090
URL.When you finish testing the application, run the
server stop helloserver
command. After you create thehellospringboot-thin.jar
thin application, you can delete the originalhellospringboot.jar
application.