Containerizing, packaging, and running a Spring Boot application

duration 20 minutes

Prerequisites:

Learn how to containerize, package, and run a Spring Boot application on Open Liberty without modification.

What you’ll learn

The starting point of this guide is the finished application from the Building an Application with Spring Boot guide. If you are not familiar with Spring Boot, complete that guide first. Java 17 is required to run this project.

You will learn how to use the springBootUtility command to deploy a Spring Boot application in Docker on Open Liberty without modification. This command stores the dependent library JAR files of the application to the target library cache, and packages the remaining application artifacts into a thin application JAR file.

You will also learn how to run the Spring Boot application locally with Open Liberty, and how to package it so that it is embedded with an Open Liberty server package.

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-spring-boot.git
cd guide-spring-boot

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.

Building and running the application

First, build the initial Spring Boot application into an executable JAR file. Navigate to the start directory and run the Maven package command:

WINDOWS

MAC

LINUX

cd start
mvnw.cmd package
cd start
./mvnw package

You can now run the application in the embedded Tomcat web container by executing the JAR file that you built:

java -jar target/guide-spring-boot-0.1.0.jar

After you see the following messages, the application is ready:

... INFO ... [ main] com.example.springboot.Application : Started Application in 2.511 seconds (process running for 3.24)
Let's inspect the beans provided by Spring Boot:
application
...
welcomePageHandlerMapping
welcomePageNotAcceptableHandlerMapping

Go to the http://localhost:8080/hello URL to access the application.

The following output is displayed in your browser:

Greetings from Spring Boot!

When you need to stop the application, press CTRL+C in the command-line session where you ran the application.

Building and running the application in a Docker container

You will build an Open Liberty Docker image to run the Spring Boot application. Using Docker, you can run your thinned application with a few simple commands. For more information on using Open Liberty with Docker, see the Containerizing microservices guide.

Learn more about Docker on the official Docker website.

Install Docker by following the instructions in the official Docker documentation.

Navigate to the start directory.

Create the Dockerfile in the start directory.
Dockerfile

Dockerfile

 1# Stage and thin the application 
 2# tag::OLimage1[]
 3FROM icr.io/appcafe/open-liberty:full-java17-openj9-ubi as staging
 4# end::OLimage1[]
 5
 6# tag::copyJar[]
 7COPY --chown=1001:0 target/guide-spring-boot-0.1.0.jar \
 8                    /staging/fat-guide-spring-boot-0.1.0.jar
 9# end::copyJar[]
10
11# tag::springBootUtility[]
12RUN springBootUtility thin \
13 --sourceAppPath=/staging/fat-guide-spring-boot-0.1.0.jar \
14 --targetThinAppPath=/staging/thin-guide-spring-boot-0.1.0.jar \
15 --targetLibCachePath=/staging/lib.index.cache
16# end::springBootUtility[]
17
18# Build the image
19# tag::OLimage2[]
20FROM icr.io/appcafe/open-liberty:kernel-slim-java17-openj9-ubi
21# end::OLimage2[]
22
23ARG VERSION=1.0
24ARG REVISION=SNAPSHOT
25
26LABEL \
27  org.opencontainers.image.authors="Your Name" \
28  org.opencontainers.image.vendor="Open Liberty" \
29  org.opencontainers.image.url="local" \
30  org.opencontainers.image.source="https://github.com/OpenLiberty/guide-spring-boot" \
31  org.opencontainers.image.version="$VERSION" \
32  org.opencontainers.image.revision="$REVISION" \
33  vendor="Open Liberty" \
34  name="hello app" \
35  version="$VERSION-$REVISION" \
36  summary="The hello application from the Spring Boot guide" \
37  description="This image contains the hello application running with the Open Liberty runtime."
38
39# tag::serverXml[]
40RUN cp /opt/ol/wlp/templates/servers/springBoot3/server.xml /config/server.xml
41# end::serverXml[]
42
43RUN features.sh
44
45# tag::libcache[]
46COPY --chown=1001:0 --from=staging /staging/lib.index.cache /lib.index.cache
47# end::libcache[]
48# tag::thinjar[]
49COPY --chown=1001:0 --from=staging /staging/thin-guide-spring-boot-0.1.0.jar \
50                    /config/dropins/spring/thin-guide-spring-boot-0.1.0.jar
51# end::thinjar[]
52
53RUN configure.sh

This Dockerfile is written in two main stages. For more information about multi-stage Dockerfiles, see the documentation on the official Docker website.

The first stage copies the guide-spring-boot-0.1.0.jar Spring Boot application to the /staging temporary directory, and then uses the Open Liberty springBootUtility command to thin the application. For more information about the springBootUtility command, see the springBootUtility documentation.

The second stage begins with the Open Liberty Docker image. The Dockerfile copies the Liberty server.xml configuration file from the /opt/ol/wlp/templates directory, which enables Spring Boot and TLS support. Then, the Dockerfile copies the Spring Boot dependent library JAR files that are at the lib.index.cache directory and the thin-guide-spring-boot-0.1.0.jar file. The lib.index.cache directory and the thin-guide-spring-boot-0.1.0.jar file were both generated in the first stage.

Use the following command to build the Docker image:

docker build -t springboot .

To verify that the images are built, run the docker images command to list all local Docker images:

docker images

Your springboot image appears in the list of Docker images:

REPOSITORY    TAG       IMAGE ID         CREATED           SIZE
springboot    latest    d3ffdaa81854     27 seconds ago    596MB

Now, you can run the Spring Boot application in a Docker container:

docker run -d --name springBootContainer -p 9080:9080 -p 9443:9443 springboot

Before you access your application from the browser, run the docker ps command to make sure that your container is running:

docker ps

You see an entry similar to the following example:

CONTAINER ID        IMAGE               COMMAND                  CREATED             STATUS              PORTS                                            NAMES
e33532aa07d6        springboot          "/opt/ibm/docker/doc…"   7 seconds ago       Up 2 seconds        0.0.0.0:9080->9080/tcp, 0.0.0.0:9443->9443/tcp   springBootContainer

You can watch the application start by monitoring the logs:

docker logs springBootContainer

After the application starts, go to the http://localhost:9080/hello URL to access the application.

Tearing down the Docker container

To stop and remove your container, run the following commands:

docker stop springBootContainer
docker rm springBootContainer

Running the application on Open Liberty

Next, you will run the Spring Boot application locally on Open Liberty by updating the pom.xml file.

The pom.xml was created for you in this directory.

Update the Maven POM file in the start directory.
pom.xml

pom.xml

 1<?xml version="1.0" encoding="UTF-8"?>
 2<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
 3    xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 https://maven.apache.org/xsd/maven-4.0.0.xsd">
 4    <modelVersion>4.0.0</modelVersion>
 5    <parent>
 6        <groupId>org.springframework.boot</groupId>
 7        <artifactId>spring-boot-starter-parent</artifactId>
 8        <version>3.4.0</version>
 9        <relativePath/> <!-- lookup parent from repository -->
10    </parent>
11    <groupId>com.example</groupId>
12    <artifactId>guide-spring-boot</artifactId>
13    <version>0.1.0</version>
14    <name>spring-boot-complete</name>
15    <description>Demo project for Spring Boot</description>
16
17    <properties>
18        <java.version>17</java.version>
19    </properties>
20
21    <dependencies>
22        <dependency>
23            <groupId>org.springframework.boot</groupId>
24            <artifactId>spring-boot-starter-web</artifactId>
25        </dependency>
26
27        <dependency>
28            <groupId>org.springframework.boot</groupId>
29            <artifactId>spring-boot-starter-actuator</artifactId>
30        </dependency>
31
32        <dependency>
33            <groupId>org.springframework.boot</groupId>
34            <artifactId>spring-boot-starter-test</artifactId>
35            <scope>test</scope>
36        </dependency>
37    </dependencies>
38
39    <build>
40        <plugins>
41            <plugin>
42                <groupId>org.springframework.boot</groupId>
43                <artifactId>spring-boot-maven-plugin</artifactId>
44            </plugin>
45
46      <!-- Enable Liberty Maven plugin -->
47      <!-- tag::libertyMavenPlugin[] -->
48      <plugin>
49        <groupId>io.openliberty.tools</groupId>
50        <artifactId>liberty-maven-plugin</artifactId>
51        <version>3.11.1</version>
52        <configuration>
53          <!-- tag::appsDirectory[] -->
54          <appsDirectory>apps</appsDirectory>
55          <!-- end::appsDirectory[] -->
56          <!-- tag::installAppPackages[] -->
57          <installAppPackages>spring-boot-project</installAppPackages>
58          <!-- end::installAppPackages[] -->
59          <!-- tag::include[] -->
60          <include>minify,runnable</include>
61          <!-- end::include[] -->
62          <!-- tag::packageFile[] -->
63          <packageName>GSSpringBootApp</packageName>
64          <!-- end::packageFile[] -->
65        </configuration>
66        <!-- tag::packageGoals[] -->
67        <executions>
68          <execution>
69            <id>package-server</id>
70            <phase>package</phase>
71            <goals>
72              <goal>create</goal>
73              <goal>install-feature</goal>
74              <goal>deploy</goal>
75              <goal>package</goal>
76            </goals>
77          </execution>
78        </executions>
79        <!-- end::packageGoals[] -->
80      </plugin>
81      <!-- end::libertyMavenPlugin[] -->
82      <!-- End of Liberty Maven plugin -->
83
84        </plugins>
85    </build>
86
87</project>

Add the liberty-maven-plugin to the pom.xml file.

The liberty-maven-plugin downloads and installs Open Liberty to the target/liberty directory. The installAppPackages configuration element in the pom.xml file typically takes in the following parameters: dependencies, project, or all. The default value is dependencies, but to install the Spring Boot application to Open Liberty, the value must be spring-boot-project. This value allows Maven to package, thin, and copy the guide-spring-boot-0.1.0.jar application to the Open Liberty runtime applications directory and shared library directory.

To run the Spring Boot application, the Open Liberty instance needs to be correctly configured. By default, the liberty-maven-plugin picks up the Liberty server.xml configuration file from the src/main/liberty/config directory.

Create the Liberty server.xml configuration file.
src/main/liberty/config/server.xml

server.xml

 1<?xml version="1.0" encoding="UTF-8"?>
 2<server description="new server">
 3
 4    <featureManager>
 5    <!-- tag::servlet[] -->
 6        <feature>servlet-6.0</feature>
 7    <!-- end::servlet[] -->
 8    <!-- tag::springboot[] -->
 9        <feature>springBoot-3.0</feature>
10    <!-- end::springboot[] -->
11    </featureManager>
12
13    <!-- tag::httpport[] -->
14    <httpEndpoint id="defaultHttpEndpoint"
15                  host="*"
16                  httpPort="9080"
17                  httpsPort="9443" />
18    <!-- end::httpport[] -->
19
20    <!-- tag::springBootApplication[] -->
21    <springBootApplication id="guide-spring-boot" 
22                           location="thin-guide-spring-boot-0.1.0.jar"
23                           name="guide-spring-boot" />
24    <!-- end::springBootApplication[] -->
25
26</server>

The servlet and springBoot features are required for the Liberty instance to run the Spring Boot application. The application port is specified as 9080 and the application is configured as a springBootApplication element. For more information, see the springBootApplication element documentation.

If you didn’t build the Spring Boot application, run the package goal:

WINDOWS

MAC

LINUX

mvnw.cmd package
./mvnw package

Next, run the liberty:run goal. This goal creates the Open Liberty instance, installs required features, deploys the Spring Boot application to the Open Liberty instance, and starts the application.

WINDOWS

MAC

LINUX

mvnw.cmd liberty:run
./mvnw liberty:run

After you see the following message, your Liberty instance is ready:

The defaultServer server is ready to run a smarter planet.

Go to the http://localhost:9080/hello URL to access the application.

After you finish exploring the application, press CTRL+C to stop the Open Liberty instance. Alternatively, you can run the liberty:stop goal from the start directory in a separate command-line session:

WINDOWS

MAC

LINUX

mvnw.cmd liberty:stop
./mvnw liberty:stop

Packaging the application embedded with Open Liberty

You can update the pom.xml file to bind more Open Liberty Maven goals to the package phase. Binding these goals to the package phase allows the Maven package goal to build a Spring Boot application that is embedded with Open Liberty.

Update the Maven POM file in the start directory.
pom.xml

pom.xml

 1<?xml version="1.0" encoding="UTF-8"?>
 2<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
 3    xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 https://maven.apache.org/xsd/maven-4.0.0.xsd">
 4    <modelVersion>4.0.0</modelVersion>
 5    <parent>
 6        <groupId>org.springframework.boot</groupId>
 7        <artifactId>spring-boot-starter-parent</artifactId>
 8        <version>3.4.0</version>
 9        <relativePath/> <!-- lookup parent from repository -->
10    </parent>
11    <groupId>com.example</groupId>
12    <artifactId>guide-spring-boot</artifactId>
13    <version>0.1.0</version>
14    <name>spring-boot-complete</name>
15    <description>Demo project for Spring Boot</description>
16
17    <properties>
18        <java.version>17</java.version>
19    </properties>
20
21    <dependencies>
22        <dependency>
23            <groupId>org.springframework.boot</groupId>
24            <artifactId>spring-boot-starter-web</artifactId>
25        </dependency>
26
27        <dependency>
28            <groupId>org.springframework.boot</groupId>
29            <artifactId>spring-boot-starter-actuator</artifactId>
30        </dependency>
31
32        <dependency>
33            <groupId>org.springframework.boot</groupId>
34            <artifactId>spring-boot-starter-test</artifactId>
35            <scope>test</scope>
36        </dependency>
37    </dependencies>
38
39    <build>
40        <plugins>
41            <plugin>
42                <groupId>org.springframework.boot</groupId>
43                <artifactId>spring-boot-maven-plugin</artifactId>
44            </plugin>
45
46      <!-- Enable Liberty Maven plugin -->
47      <!-- tag::libertyMavenPlugin[] -->
48      <plugin>
49        <groupId>io.openliberty.tools</groupId>
50        <artifactId>liberty-maven-plugin</artifactId>
51        <version>3.11.1</version>
52        <configuration>
53          <!-- tag::appsDirectory[] -->
54          <appsDirectory>apps</appsDirectory>
55          <!-- end::appsDirectory[] -->
56          <!-- tag::installAppPackages[] -->
57          <installAppPackages>spring-boot-project</installAppPackages>
58          <!-- end::installAppPackages[] -->
59          <!-- tag::include[] -->
60          <include>minify,runnable</include>
61          <!-- end::include[] -->
62          <!-- tag::packageFile[] -->
63          <packageName>GSSpringBootApp</packageName>
64          <!-- end::packageFile[] -->
65        </configuration>
66        <!-- tag::packageGoals[] -->
67        <executions>
68          <execution>
69            <id>package-server</id>
70            <phase>package</phase>
71            <goals>
72              <goal>create</goal>
73              <goal>install-feature</goal>
74              <goal>deploy</goal>
75              <goal>package</goal>
76            </goals>
77          </execution>
78        </executions>
79        <!-- end::packageGoals[] -->
80      </plugin>
81      <!-- end::libertyMavenPlugin[] -->
82      <!-- End of Liberty Maven plugin -->
83
84        </plugins>
85    </build>
86
87</project>

Add the include and packageName configuration elements, and the executions element to the pom.xml file.

The include configuration element specifies the minify, runnable values. The runnable value allows the application to be generated as a runnable JAR file. The minify value packages only what you need from your configuration files without bundling the entire Open Liberty install.

The packageName configuration element specifies that the application is generated as a GSSpringBootApp.jar file.

The executions element specifies the required Open Liberty Maven goals to generate the application that is embedded with Open Liberty.

Next, run the Maven package goal:

WINDOWS

MAC

LINUX

mvnw.cmd package
./mvnw package

Run the repackaged Spring Boot application. This JAR file was defined previously in the pom.xml file.

java -jar target/GSSpringBootApp.jar

After you see the following message, your Liberty instance is ready:

The defaultServer server is ready to run a smarter planet.

Go to the http://localhost:9080/hello URL to access the application.

When you need to stop the application, press CTRL+C.

Great work! You’re done!

You just ran a basic Spring Boot application with Open Liberty.

Guide Attribution

Containerizing, packaging, and running a Spring Boot application by Open Liberty is licensed under CC BY-ND 4.0

Copy file contents
Copied to clipboard

Prerequisites:

Nice work! Where to next?

What did you think of this guide?

Extreme Dislike Dislike Like Extreme Like

What could make this guide better?

Raise an issue to share feedback

Create a pull request to contribute to this guide

Need help?

Ask a question on Stack Overflow

Like Open Liberty? Star our repo on GitHub.

Star