Docker is a Linux container management toolkit with a “social” aspect, letting users publish container images and consume those published by others. A Docker image is a recipe for running a containerized process. In this guide, we build one for a simple Spring boot application.

https://raw.githubusercontent.com/spring-guides/getting-started-macros/main/prereq_editor_jdk_buildtools.adoc

If you are NOT using a Linux machine, you need a virtualized server. If you install VirtualBox, other tools like the Mac’s boot2docker can seamlessly manage it for you. Visit VirtualBox’s download site and pick the version for your machine. Download and install. Do not worry about actually running it.

You also need Docker, which only runs on 64-bit machines. See https://docs.docker.com/installation/#installation for details on setting Docker up for your machine. Before proceeding further, verify you can run docker commands from the shell. If you use boot2docker, you need to run that first.

You can use this pre-initialized project and click Generate to download a ZIP file. This project is configured to fit the examples in this tutorial.

To manually initialize the project:

1. Navigate to https://start.spring.io. This service pulls in all the dependencies you need for an application and does most of the setup for you.

2. Choose either Gradle or Maven and the language you want to use. This guide assumes that you chose Java.

3. Click Dependencies and select Spring Web.

4. Click Generate.

5. Download the resulting ZIP file, which is an archive of a web application that is configured with your choices.

Now you can create a simple application:

The class is flagged as a @SpringBootApplication and as a @RestController, meaning that it is ready for use by Spring MVC to handle web requests. @RequestMapping maps / to the home() method, which sends a Hello World response. The main() method uses Spring Boot’s SpringApplication.run() method to launch an application.

Now we can run the application without the Docker container (that is, in the host OS):

If you use Gradle, run the following command:

If you use Maven, run the following command:

Then go to localhost:8080 to see your “Hello Docker World” message.

Docker has a simple "Dockerfile" file format that it uses to specify the “layers” of an image. Create the following Dockerfile in your Spring Boot project:

If you use Gradle, you can run it with the following command:

If you use Maven, you can run it with the following command:

This command builds an image and tags it as springio/gs-spring-boot-docker.

This Dockerfile is very simple, but it is all you need to run a Spring Boot app with no frills: just Java and a JAR file. The build creates a spring user and a spring group to run the application. It is then copied (by the COPY command) the project JAR file into the container as app.jar, which is run in the ENTRYPOINT. The array form of the Dockerfile ENTRYPOINT is used so that there is no shell wrapping the Java process. The Topical Guide on Docker goes into this topic in more detail.

Running applications with user privileges helps to mitigate some risks (see, for example, a thread on StackExchange). So, an important improvement to the Dockerfile is to run the application as a non-root user:

You can see the username in the application startup logs when you build and run the application:

Note the started by in the first INFO log entry:

Also, there is a clean separation between dependencies and application resources in a Spring Boot fat JAR file, and we can use that fact to improve performance. The key is to create layers in the container filesystem. The layers are cached both at build time and at runtime (in most runtimes), so we want the most frequently changing resources (usually the class and static resources in the application itself) to be layered after the more slowly changing resources. Thus, we use a slightly different implementation of the Dockerfile:

This Dockerfile has a DEPENDENCY parameter pointing to a directory where we have unpacked the fat JAR. To use the DEPENDENCY parameter with Gradle, run the following command:

To use the DEPENDENCY parameter with Maven, run the following command:

If we get that right, it already contains a BOOT-INF/lib directory with the dependency JARs in it, and a BOOT-INF/classes directory with the application classes in it. Notice that we use the application’s own main class: hello.Application. (This is faster than using the indirection provided by the fat JAR launcher.)

From a Gradle build, you need to add the explicit build arguments in the Docker command line:

To build the image in Maven, you can use a simpler Docker command line:

Instead of building with the Docker command line, you might want to use a build plugin. Spring Boot supports building a container from Maven or Gradle by using its own build plugin. Google also has an open source tool called Jib that has Maven and Gradle plugins. Probably the most interesting thing about this approach is that you do not need a Dockerfile. You can build the image by using the same standard container format as you get from docker build. Also, it can work in environments where docker is not installed (not uncommon in build servers).

Build a Docker Image with Gradle

./gradlew bootBuildImage --imageName=springio/gs-spring-boot-docker

Build a Docker Image with Maven

./mvnw spring-boot:build-image -Dspring-boot.build-image.imageName=springio/gs-spring-boot-docker

After the Push

$ docker run -p 8080:8080 -t springio/gs-spring-boot-docker
Container memory limit unset. Configuring JVM for 1G container.
Calculated JVM Memory Configuration: -XX:MaxDirectMemorySize=10M -XX:MaxMetaspaceSize=86381K -XX:ReservedCodeCacheSize=240M -Xss1M -Xmx450194K (Head Room: 0%, Loaded Class Count: 12837, Thread Count: 250, Total Memory: 1073741824)
....
2015-03-31 13:25:48.035  INFO 1 --- [           main] s.b.c.e.t.TomcatEmbeddedServletContainer : Tomcat started on port(s): 8080 (http)
2015-03-31 13:25:48.037  INFO 1 --- [           main] hello.Application                        : Started Application in 5.613 seconds (JVM running for 7.293)

Docker client to the Docker daemon, please set:
    export DOCKER_CERT_PATH=/Users/gturnquist/.boot2docker/certs/boot2docker-vm
    export DOCKER_TLS_VERIFY=1
    export DOCKER_HOST=tcp://192.168.59.103:2376

$ docker ps
CONTAINER ID        IMAGE                                   COMMAND                  CREATED             STATUS              PORTS                    NAMES
81c723d22865        springio/gs-spring-boot-docker:latest   "java -Djava.secur..."   34 seconds ago      Up 33 seconds       0.0.0.0:8080->8080/tcp   goofy_brown

docker stop goofy_brown
81c723d22865

docker rm goofy_brown

Using Spring Profiles

docker run -e "SPRING_PROFILES_ACTIVE=prod" -p 8080:8080 -t springio/gs-spring-boot-docker

docker run -e "SPRING_PROFILES_ACTIVE=dev" -p 8080:8080 -t springio/gs-spring-boot-docker

Debugging the Application in a Docker Container

docker run -e "JAVA_TOOL_OPTIONS=-agentlib:jdwp=transport=dt_socket,address=5005,server=y,suspend=n" -p 8080:8080 -p 5005:5005 -t springio/gs-spring-boot-docker

Congratulations! You have created a Docker container for a Spring Boot application! By default, Spring Boot applications run on port 8080 inside the container, and we mapped that to the same port on the host by using -p on the command line.

The following guides may also be helpful:

• Serving Web Content with Spring MVC

• Building an Application with Spring Boot

• Topical Guide on Spring Boot with Docker (more depth than this guide)

https://raw.githubusercontent.com/spring-guides/getting-started-macros/main/footer.adoc