From 3f9d0058adebb02db74e5ad3433c872122fd32c6 Mon Sep 17 00:00:00 2001 From: Madhura Bhave Date: Tue, 4 Feb 2020 18:36:39 -0800 Subject: [PATCH] Document new Docker-related features Closes gh-19868 --- .../docs/asciidoc/spring-boot-features.adoc | 148 ++++++++++++++++++ 1 file changed, 148 insertions(+) diff --git a/spring-boot-project/spring-boot-docs/src/docs/asciidoc/spring-boot-features.adoc b/spring-boot-project/spring-boot-docs/src/docs/asciidoc/spring-boot-features.adoc index 1e90297dc5..911955a5ca 100644 --- a/spring-boot-project/spring-boot-docs/src/docs/asciidoc/spring-boot-features.adoc +++ b/spring-boot-project/spring-boot-docs/src/docs/asciidoc/spring-boot-features.adoc @@ -7703,6 +7703,154 @@ If you need the `Mockk` equivalent of the Mockito specific </ + classes/ + ... + lib/ + ... + / + classes/ + ... + lib/ + ... + layers.idx +---- + +You still see the bootstrap loader classes (you can still run `java -jar`) but now the `lib` and `classes` folders have been split up and categorized into layers. +There’s also a `layers.idx` file that provides the order in which layers should be added. +Out-of-the-box, the following layers are supported: + +* `dependencies` (for regular released dependencies) +* `snapshot-dependencies` (for snapshot dependencies) +* `resources` (for static resources) +* `application` (for application classes and resources) + + +This layering is designed to separate code based on how likely it is to change between application builds. +Library code is less likely to change between builds, so it is placed in its own layers to allow tooling to re-use the layers from cache. +Application code is more likely to change between builds so it is isolated in a separate layer. + +For Maven, layered jars can be created using a new `layout` type called `LAYERED_JAR`. +See the {spring-boot-maven-plugin-docs}/#goals-build-image-parameters-details-layout[layout section] for more details. +For Gradle, refer to the {spring-boot-gradle-plugin-docs}/#packaging-layered-jars[packaging layered jars section] of the Gradle plugin documentation. + +==== Writing the Dockerfile + +When you create a layered jar, the `spring-boot-layertools` jar will be added as a dependency to your jar. +With this jar on the classpath, you can launch your application in a special mode which allows the bootstrap code to run something entirely different from your application, for example, something that extracts the layers. +Here’s how you can launch your jar with a `layertools` jar mode: + +[source] +---- +$ java -Djarmode=layertools -jar my-app.jar +---- + +This will provide the following output: + +[source] +---- +Usage: + java -Djarmode=layertools -jar my-app.jar + +Available commands: + list List layers from the jar that can be extracted + extract Extracts layers from the jar for image creation + help Help about any command +---- + +The `extract` command can be used to easily split the application into layers to be added to the dockerfile. +Here's an example of a Dockerfile using `jarmode`. + +[source] +---- +FROM adoptopenjdk:11-jre-hotspot as builder +WORKDIR application +ARG JAR_FILE=target/*.jar +COPY ${JAR_FILE} application.jar +RUN java -Djarmode=layertools -jar application.jar extract + +FROM adoptopenjdk:11-jre-hotspot +WORKDIR application +COPY --from=builder application/dependencies/ ./ +COPY --from=builder application/snapshot-dependencies/ ./ +COPY --from=builder application/resources/ ./ +COPY --from=builder application/application/ ./ +ENTRYPOINT ["java", "org.springframework.boot.loader.JarLauncher"] +---- + +This is a multi-stage dockerfile. +The builder stage extracts the folders that are needed later. +Each of the `COPY` commands relates to the layers extracted by the jarmode. + +Of course, a Dockerfile can be written without using the jarmode. +You can use some combination of `unzip` and `mv` to move things to the right layer but jarmode simplifies that. + + + +==== Buildpacks +Dockerfiles are just one way to build docker images. +Another way to build docker images is directly from your Maven or Gradle plugin, using buildpacks. +If you’ve ever used an application platform such as Cloud Foundry or Heroku then you’ve probably used a buildpack. +Buildpacks are the part of the platform that takes your application and converts it into something that the platform can actually run. +For example, Cloud Foundry’s Java buildpack will notice that you’re pushing a `.jar` file and automatically add a relevant JRE. + +With Cloud Native Buildpacks, you can create Docker compatible images that you can run anywhere. +Spring Boot includes buildpack support directly for both Maven and Gradle. +This means you can just type a single command and quickly get a sensible image into your locally running Docker daemon. + +Refer to the individual plugin documentation on how to use buildpacks with {spring-boot-maven-plugin-docs}/#build-image[Maven] and {spring-boot-gradle-plugin-docs}/#packaging-oci-images[Gradle]. + + + [[boot-features-whats-next]] == What to Read Next If you want to learn more about any of the classes discussed in this section, you can check out the {spring-boot-api}[Spring Boot API documentation] or you can browse the {spring-boot-code}[source code directly].