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:
Example 1. Dockerfile
FROM openjdk:8-jdk-alpine
ARG JAR_FILE=target/*.jar
COPY ${JAR_FILE} app.jar
ENTRYPOINT ["java","-jar","/app.jar"]
If you use Gradle, you can run it with the following command:
docker build --build-arg JAR_FILE=build/libs/\*.jar -t springio/gs-spring-boot-docker .
If you use Maven, you can run it with the following command:
docker build -t springio/gs-spring-boot-docker .
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:
Example 2. Dockerfile
FROM openjdk:8-jdk-alpine
RUN addgroup -S spring && adduser -S spring -G spring
USER spring:spring
ARG JAR_FILE=target/*.jar
COPY ${JAR_FILE} app.jar
ENTRYPOINT ["java","-jar","/app.jar"]
You can see the username in the application startup logs when you build and run the application:
docker build -t springio/gs-spring-boot-docker .
docker run -p 8080:8080 springio/gs-spring-boot-docker
Note the started by in the first INFO log entry:
:: Spring Boot :: (v2.2.1.RELEASE)
2020-04-23 07:29:41.729 INFO 1 --- [ main] hello.Application : Starting Application on b94c86e91cf9 with PID 1 (/app started by spring in /)
...
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:
Example 3. Dockerfile
FROM openjdk:8-jdk-alpine
RUN addgroup -S spring && adduser -S spring -G spring
USER spring:spring
ARG DEPENDENCY=target/dependency
COPY ${DEPENDENCY}/BOOT-INF/lib /app/lib
COPY ${DEPENDENCY}/META-INF /app/META-INF
COPY ${DEPENDENCY}/BOOT-INF/classes /app
ENTRYPOINT ["java","-cp","app:app/lib/*","hello.Application"]
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:
mkdir -p build/dependency && (cd build/dependency; jar -xf ../libs/*.jar)
To use the DEPENDENCY parameter with Maven, run the following command:
mkdir -p target/dependency && (cd target/dependency; jar -xf ../*.jar)
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.)
|
Exploding the JAR file can result in the classpath order being different at runtime. A well-behaved and well-written application should not care about this, but you may see behavior changes if the dependencies are not carefully managed. |
|
If you use boot2docker, you need to run it first before you do anything with the Docker command line or with the build tools (it runs a daemon process that handles the work for you in a virtual machine). |
From a Gradle build, you need to add the explicit build arguments in the Docker command line:
docker build --build-arg DEPENDENCY=build/dependency -t springio/gs-spring-boot-docker .
To build the image in Maven, you can use a simpler Docker command line:
docker build -t springio/gs-spring-boot-docker .
|
If you use only Gradle, you could change the Dockerfile to make the default value of DEPENDENCY match the location of the unpacked archive. |
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).
|
By default, the images generated by the default buildpacks do not run your application as root. Check the configuration guide for Gradle or Maven for how to change the default settings. |
Build a Docker Image with Gradle
You can build a tagged docker image with Gradle in one command:
./gradlew bootBuildImage --imageName=springio/gs-spring-boot-docker
Build a Docker Image with Maven
To get started quickly, you can run the Spring Boot image generator without even changing your pom.xml (remember that the Dockerfile, if it is still, there is ignored):
./mvnw spring-boot:build-image -Dspring-boot.build-image.imageName=springio/gs-spring-boot-docker
To push to a Docker registry, you need to have permission to push, which you do not have by default. Change the image prefix to your own Dockerhub ID and docker login to make sure you are authenticated before you run Docker.
After the Push
A docker push in the example fails (unless you are part of the "springio" organization at Dockerhub). However, if you change the configuration to match your own docker ID, it should succeed. You then have a new tagged, deployed image.
You do NOT have to register with docker or publish anything to run a docker image that was built locally. If you built with Docker (from the command line or from Spring Boot), you still have a locally tagged image, and you can run it like this:
$ 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)
|
The buildpack uses a memory calculator at runtime to size the JVM to fit the container. |
The application is then available on http://localhost:8080 (visit that and it says, “Hello Docker World”).
|
When using a Mac with boot2docker, you typically see things like this at startup:
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
To see the application, you must visit the IP address in DOCKER_HOST instead of localhost — in this case, https://192.168.59.103:8080, the public facing IP of the VM.
|
When it is running, you can see in the list of containers, similar to the following example:
$ 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
To shut it down again, you can run docker stop with the container ID from the previous listing (yours will be different):
docker stop goofy_brown
81c723d22865
If you like, you can also delete the container (it is persisted in your filesystem somewhere under /var/lib/docker) when you are finished with it:
Using Spring Profiles
Running your freshly minted Docker image with Spring profiles is as easy as passing an environment variable to the Docker run command (for the prod profile):
docker run -e "SPRING_PROFILES_ACTIVE=prod" -p 8080:8080 -t springio/gs-spring-boot-docker
You can do the same for the dev profile:
docker run -e "SPRING_PROFILES_ACTIVE=dev" -p 8080:8080 -t springio/gs-spring-boot-docker
Debugging the Application in a Docker Container
To debug the application, you can use JPDA Transport. We treat the container like a remote server. To enable this feature, pass Java agent settings in the JAVA_OPTS variable and map the agent’s port to localhost during a container run. With Docker for Mac, there is a limitation because we can’t access the container by IP without black magic usage.
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