Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/openliberty/guide-spring-boot
A guide on how to containerize, package, and run a Spring Boot application on an Open Liberty server without modification.
https://github.com/openliberty/guide-spring-boot
Last synced: 3 months ago
JSON representation
A guide on how to containerize, package, and run a Spring Boot application on an Open Liberty server without modification.
- Host: GitHub
- URL: https://github.com/openliberty/guide-spring-boot
- Owner: OpenLiberty
- Created: 2018-06-20T20:05:58.000Z (over 6 years ago)
- Default Branch: prod
- Last Pushed: 2024-08-08T15:17:15.000Z (6 months ago)
- Last Synced: 2024-08-08T20:47:56.180Z (5 months ago)
- Language: Java
- Homepage: https://openliberty.io/guides/spring-boot.html
- Size: 15.1 MB
- Stars: 20
- Watchers: 6
- Forks: 12
- Open Issues: 2
-
Metadata Files:
- Readme: README.adoc
- Contributing: CONTRIBUTING.md
Awesome Lists containing this project
README
// Copyright (c) 2019, 2023 IBM Corporation and others.
// Licensed under Creative Commons Attribution-NoDerivatives
// 4.0 International (CC BY-ND 4.0)
// https://creativecommons.org/licenses/by-nd/4.0/
//
// Contributors:
// IBM Corporation
//
:page-layout: guide-multipane
:projectid: spring-boot
:page-duration: 20 minutes
:page-releasedate: 2019-11-04
:page-majorupdateddate: 2023-11-15
:page-description: Learn how to containerize, package, and run a Spring Boot application on Open Liberty.
:page-tags: ['Docker']
:page-related-guides: ['rest-intro', 'containerize']
:page-permalink: /guides/{projectid}
:common-includes: https://raw.githubusercontent.com/OpenLiberty/guides-common/prod
:source-highlighter: prettify
:page-seo-title: Deploying a Spring Boot application
:page-seo-description: A tutorial with examples on how to containerize, package, and run a Spring Boot application in a Docker container on an Open Liberty server.
:guide-author: Open Liberty
= Containerizing, packaging, and running a Spring Boot application
[.hidden]
NOTE: This repository contains the guide documentation source. To view the guide in published form, view it on the https://openliberty.io/guides/{projectid}.html[Open Liberty website].
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 https://spring.io/guides/gs/spring-boot/[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.
[role='command']
include::{common-includes}/gitclone.adoc[]
== 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:
include::{common-includes}/os-tabs.adoc[]
[.tab_content.windows_section]
--
[role='command']
```
cd start
mvnw.cmd package
```
--
[.tab_content.mac_section.linux_section]
--
[role='command']
```
cd start
./mvnw package
```
--
You can now run the application in the embedded Tomcat web container by executing the JAR file that you built:
[role='command']
```
java -jar target/guide-spring-boot-0.1.0.jar
```
After you see the following messages, the application is ready:
[role='no_copy']
----
... 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
----
// Static guide instruction
ifndef::cloud-hosted[]
Go to the http://localhost:8080/hello[^] URL to access the application.
The following output is displayed in your browser:
[role='no_copy']
----
Greetings from Spring Boot!
----
endif::[]
// Cloud hosted guide instruction
ifdef::cloud-hosted[]
Open another command-line session by selecting **Terminal** > **New Terminal** from the menu of the IDE. Run the following command to access the application:
```bash
curl http://localhost:8080/hello
```
The following output is returned:
```
Greetings from Spring Boot!
```
endif::[]
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 https://openliberty.io/guides/containerize.html[Containerizing microservices^] guide.
Learn more about Docker on the https://www.docker.com/why-docker[official Docker website^].
Install Docker by following the instructions in the https://docs.docker.com/engine/install[official Docker documentation^].
Navigate to the `start` directory.
[role="code_command hotspot file=0", subs="quotes"]
----
#Create the `Dockerfile` in the `start` directory.#
`Dockerfile`
----
Dockerfile
[source, Text, linenums, role='code_column']
----
include::finish/Dockerfile[]
----
This Dockerfile is written in two main stages. For more information about multi-stage Dockerfiles, see the documentation on the https://docs.docker.com/develop/develop-images/multistage-build/[official Docker website^].
The first stage copies the [hotspot=copyJar]`guide-spring-boot-0.1.0.jar` Spring Boot application to the [hotspot=7 file=0]`/staging` temporary directory,
and then uses the Open Liberty [hotspot=springBootUtility]`springBootUtility` command to thin the application. For more information about the `springBootUtility` command, see the https://openliberty.io/docs/latest/reference/command/springbootUtility-thin.html[springBootUtility documentation^].
The second stage begins with the [hotspot=OLimage2 file=0]`Open Liberty Docker image`. The Dockerfile copies the Liberty [hotspot=serverXml file=0]`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 [hotspot=libcache file=0]`lib.index.cache` directory and the [hotspot=thinjar file=0]`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:
[role='command']
```
docker build -t springboot .
```
To verify that the images are built, run the `docker images` command to list all local Docker images:
[role='command']
```
docker images
```
Your `springboot` image appears in the list of Docker images:
[role='no_copy']
```
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:
[role='command']
```
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:
[role='command']
----
docker ps
----
You see an entry similar to the following example:
[role='no_copy']
----
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:
[role='command']
```
docker logs springBootContainer
```
// Static guide instruction
ifndef::cloud-hosted[]
After the application starts, go to the http://localhost:9080/hello[^] URL to access the application.
endif::[]
// Cloud hosted guide instruction
ifdef::cloud-hosted[]
After the application starts, run the following command to access the application:
```bash
curl http://localhost:9080/hello
```
endif::[]
=== Tearing down the Docker container
To stop and remove your container, run the following commands:
[role='command']
```
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 [hotspot file=0]`pom.xml` was created for you in this directory.
[role="code_command hotspot file=0", subs="quotes"]
----
#Update the `Maven POM` file in the `start` directory.#
`pom.xml`
----
pom.xml
[source, XML, linenums, role='code_column hide_tags=packageFile,include,packageGoals']
----
include::finish/pom.xml[]
----
[role="edit_command_text"]
Add the [hotspot=libertyMavenPlugin file=0]`liberty-maven-plugin` to the [hotspot file=0]`pom.xml` file.
The `liberty-maven-plugin` downloads and installs Open Liberty to the `target/liberty` directory. The [hotspot=installAppPackages file=0]`installAppPackages` configuration element in the [hotspot file=0]`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 [hotspot=installAppPackages file=0]`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 [hotspot=appsDirectory file=0]`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.
[role="code_command hotspot file=1", subs="quotes"]
----
#Create the Liberty `server.xml` configuration file.#
`src/main/liberty/config/server.xml`
----
server.xml
[source, XML, linenums, role='code_column']
----
include::finish/src/main/liberty/config/server.xml[]
----
The [hotspot=servlet file=1]`servlet` and [hotspot=springboot file=1]`springBoot` features are required for the Liberty instance to run the Spring Boot application. The application port is specified as [hotspot=httpport file=1]`9080` and the application is configured as a [hotspot=springBootApplication file=1]`springBootApplication` element. For more information, see the https://www.openliberty.io/docs/latest/reference/config/springBootApplication.html[springBootApplication element documentation^].
If you didn't build the Spring Boot application, run the `package` goal:
include::{common-includes}/os-tabs.adoc[]
[.tab_content.windows_section]
--
[role='command']
```
mvnw.cmd package
```
--
[.tab_content.mac_section.linux_section]
--
[role='command']
```
./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.
include::{common-includes}/os-tabs.adoc[]
[.tab_content.windows_section]
--
[role='command']
```
mvnw.cmd liberty:run
```
--
[.tab_content.mac_section.linux_section]
--
[role='command']
```
./mvnw liberty:run
```
--
After you see the following message, your Liberty instance is ready:
[role="no_copy"]
----
The defaultServer server is ready to run a smarter planet.
----
// Static guide instruction
ifndef::cloud-hosted[]
Go to the http://localhost:9080/hello[^] URL to access the application.
endif::[]
// Cloud hosted guide instruction
ifdef::cloud-hosted[]
In another command-line sesssion, run the following command to access the application:
```bash
curl http://localhost:9080/hello
```
endif::[]
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:
include::{common-includes}/os-tabs.adoc[]
[.tab_content.windows_section]
--
[role='command']
```
mvnw.cmd liberty:stop
```
--
[.tab_content.mac_section.linux_section]
--
[role='command']
```
./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.
[role="code_command hotspot file=0", subs="quotes"]
----
#Update the Maven POM file in the `start` directory.#
`pom.xml`
----
pom.xml
[source, XML, linenums, role='code_column']
----
include::finish/pom.xml[]
----
[role="edit_command_text"]
Add the [hotspot=include file=0]`include` and [hotspot=packageFile file=0]`packageName` configuration elements, and the [hotspot=packageGoals file=0]`executions` element to the `pom.xml` file.
The [hotspot=include file=0]`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 [hotspot=packageFile file=0]`packageName` configuration element specifies that the application is generated as a `GSSpringBootApp.jar` file.
The [hotspot=packageGoals file=0]`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:
include::{common-includes}/os-tabs.adoc[]
[.tab_content.windows_section]
--
[role='command']
```
mvnw.cmd package
```
--
[.tab_content.mac_section.linux_section]
--
[role='command']
```
./mvnw package
```
--
Run the repackaged Spring Boot application. This JAR file was defined previously in the [hotspot file=0]`pom.xml` file.
[role='command']
```
java -jar target/GSSpringBootApp.jar
```
After you see the following message, your Liberty instance is ready:
[role="no_copy"]
----
The defaultServer server is ready to run a smarter planet.
----
// Static guide instruction
ifndef::cloud-hosted[]
Go to the http://localhost:9080/hello[^] URL to access the application.
endif::[]
// Cloud hosted guide instruction
ifdef::cloud-hosted[]
In another command-line sesssion, run the following command to access the application:
```bash
curl http://localhost:9080/hello
```
endif::[]
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.
include::{common-includes}/attribution.adoc[subs="attributes"]