diff --git a/spring-boot-project/spring-boot-tools/spring-boot-gradle-plugin/src/docs/asciidoc/index.adoc b/spring-boot-project/spring-boot-tools/spring-boot-gradle-plugin/src/docs/asciidoc/index.adoc index 96de9cf313..a9630836f2 100644 --- a/spring-boot-project/spring-boot-tools/spring-boot-gradle-plugin/src/docs/asciidoc/index.adoc +++ b/spring-boot-project/spring-boot-tools/spring-boot-gradle-plugin/src/docs/asciidoc/index.adoc @@ -34,7 +34,8 @@ Andy Wilkinson, Scott Frederick :boot-run-javadoc: {api-documentation}/org/springframework/boot/gradle/tasks/run/BootRun.html :github-code: https://github.com/spring-projects/spring-boot/tree/{github-tag} :buildpacks-reference: https://buildpacks.io/docs -:paketo-java-reference: https://paketo.io/docs/buildpacks/language-family-buildpacks/java +:paketo-reference: https://paketo.io/docs +:paketo-java-reference: {paketo-reference}/buildpacks/language-family-buildpacks/java [[introduction]] diff --git a/spring-boot-project/spring-boot-tools/spring-boot-gradle-plugin/src/docs/asciidoc/packaging-oci-image.adoc b/spring-boot-project/spring-boot-tools/spring-boot-gradle-plugin/src/docs/asciidoc/packaging-oci-image.adoc index a684ed4a87..18e905affc 100644 --- a/spring-boot-project/spring-boot-tools/spring-boot-gradle-plugin/src/docs/asciidoc/packaging-oci-image.adoc +++ b/spring-boot-project/spring-boot-tools/spring-boot-gradle-plugin/src/docs/asciidoc/packaging-oci-image.adoc @@ -228,9 +228,6 @@ include::../gradle/packaging/boot-build-image-env.gradle[tags=env] include::../gradle/packaging/boot-build-image-env.gradle.kts[tags=env] ---- -In a similar way, Paketo Java buildpacks support {paketo-java-reference}/#runtime-jvm-configuration[configuring JVM runtime behavior]. -Refer to the {paketo-java-reference}[Paketo documentation] for additional configuration options supported by Paketo Java buildpacks. - If there is a network proxy between the Docker daemon the builder runs in and network locations that buildpacks download artifacts from, you will need to configure the builder to use the proxy. When using the Paketo builder, this can be accomplished by setting the `HTTPS_PROXY` and/or `HTTP_PROXY` environment variables as show in the following example: @@ -248,6 +245,27 @@ include::../gradle/packaging/boot-build-image-env-proxy.gradle.kts[tags=env] +[[build-image-example-runtime-jvm-configuration]] +==== Runtime JVM Configuration +Paketo Java buildpacks {paketo-java-reference}/#runtime-jvm-configuration[configure the JVM runtime environment] by setting the `JAVA_TOOL_OPTIONS` environment variable. +The buildpack-provided `JAVA_TOOL_OPTIONS` value can be modified to customize JVM runtime behavior when the application image is launched in a container. + +Environment variable modifications that should be stored in the image and applied to every deployment can be set as described in the {paketo-reference}/buildpacks/configuration/#environment-variables[Paketo documentation] and shown in the following example: + +[source,groovy,indent=0,subs="verbatim,attributes",role="primary"] +.Groovy +---- +include::../gradle/packaging/boot-build-image-env-runtime.gradle[tags=env-runtime] +---- + +[source,kotlin,indent=0,subs="verbatim,attributes",role="secondary"] +.Kotlin +---- +include::../gradle/packaging/boot-build-image-env-runtime.gradle.kts[tags=env-runtime] +---- + + + [[build-image-example-custom-image-name]] ==== Custom Image Name By default, the image name is inferred from the `name` and the `version` of the project, something like `docker.io/library/${project.name}:${project.version}`. diff --git a/spring-boot-project/spring-boot-tools/spring-boot-gradle-plugin/src/docs/gradle/packaging/boot-build-image-env-runtime.gradle b/spring-boot-project/spring-boot-tools/spring-boot-gradle-plugin/src/docs/gradle/packaging/boot-build-image-env-runtime.gradle new file mode 100644 index 0000000000..bdf71d3d98 --- /dev/null +++ b/spring-boot-project/spring-boot-tools/spring-boot-gradle-plugin/src/docs/gradle/packaging/boot-build-image-env-runtime.gradle @@ -0,0 +1,23 @@ +plugins { + id 'java' + id 'org.springframework.boot' version '{gradle-project-version}' +} + +bootJar { + mainClassName 'com.example.ExampleApplication' +} + +// tag::env-runtime[] +bootBuildImage { + environment = [ + "BPE_DELIM_JAVA_TOOL_OPTIONS" : " ", + "BPE_APPEND_JAVA_TOOL_OPTIONS" : "-XX:+HeapDumpOnOutOfMemoryError" + ] +} +// end::env-runtime[] + +task bootBuildImageEnvironment { + doFirst { + bootBuildImage.environment.each { name, value -> println "$name=$value" } + } +} diff --git a/spring-boot-project/spring-boot-tools/spring-boot-gradle-plugin/src/docs/gradle/packaging/boot-build-image-env-runtime.gradle.kts b/spring-boot-project/spring-boot-tools/spring-boot-gradle-plugin/src/docs/gradle/packaging/boot-build-image-env-runtime.gradle.kts new file mode 100644 index 0000000000..a98d23ebfa --- /dev/null +++ b/spring-boot-project/spring-boot-tools/spring-boot-gradle-plugin/src/docs/gradle/packaging/boot-build-image-env-runtime.gradle.kts @@ -0,0 +1,24 @@ +import org.springframework.boot.gradle.tasks.bundling.BootBuildImage + +plugins { + java + id("org.springframework.boot") version "{gradle-project-version}" +} + +// tag::env-runtime[] +tasks.getByName("bootBuildImage") { + environment = mapOf( + "BPE_DELIM_JAVA_TOOL_OPTIONS" to " ", + "BPE_APPEND_JAVA_TOOL_OPTIONS" to "-XX:+HeapDumpOnOutOfMemoryError" + ) +} +// end::env-runtime[] + +tasks.register("bootBuildImageEnvironment") { + doFirst { + for((name, value) in tasks.getByName("bootBuildImage").environment) { + print(name + "=" + value) + } + } +} + diff --git a/spring-boot-project/spring-boot-tools/spring-boot-gradle-plugin/src/test/java/org/springframework/boot/gradle/docs/PackagingDocumentationTests.java b/spring-boot-project/spring-boot-tools/spring-boot-gradle-plugin/src/test/java/org/springframework/boot/gradle/docs/PackagingDocumentationTests.java index 8d612650e6..6b68af4c5b 100644 --- a/spring-boot-project/spring-boot-tools/spring-boot-gradle-plugin/src/test/java/org/springframework/boot/gradle/docs/PackagingDocumentationTests.java +++ b/spring-boot-project/spring-boot-tools/spring-boot-gradle-plugin/src/test/java/org/springframework/boot/gradle/docs/PackagingDocumentationTests.java @@ -263,6 +263,14 @@ class PackagingDocumentationTests { .contains("HTTPS_PROXY=https://proxy.example.com"); } + @TestTemplate + void bootBuildImageWithCustomRuntimeConfiguration() { + BuildResult result = this.gradleBuild.script("src/docs/gradle/packaging/boot-build-image-env-runtime") + .build("bootBuildImageEnvironment"); + assertThat(result.getOutput()).contains("BPE_DELIM_JAVA_TOOL_OPTIONS= ") + .contains("BPE_APPEND_JAVA_TOOL_OPTIONS=-XX:+HeapDumpOnOutOfMemoryError"); + } + @TestTemplate void bootBuildImageWithCustomImageName() { BuildResult result = this.gradleBuild.script("src/docs/gradle/packaging/boot-build-image-name") diff --git a/spring-boot-project/spring-boot-tools/spring-boot-maven-plugin/src/docs/asciidoc/index.adoc b/spring-boot-project/spring-boot-tools/spring-boot-maven-plugin/src/docs/asciidoc/index.adoc index e621e7b100..814a7fcfa7 100644 --- a/spring-boot-project/spring-boot-tools/spring-boot-maven-plugin/src/docs/asciidoc/index.adoc +++ b/spring-boot-project/spring-boot-tools/spring-boot-maven-plugin/src/docs/asciidoc/index.adoc @@ -14,7 +14,8 @@ Stephane Nicoll, Andy Wilkinson, Scott Frederick :spring-boot-api: {spring-boot-docs}/api/org/springframework/boot :spring-boot-reference: {spring-boot-docs}/reference/htmlsingle :version-properties-appendix: {spring-boot-reference}/#dependency-versions-properties -:paketo-java-reference: https://paketo.io/docs/buildpacks/language-family-buildpacks/java +:paketo-reference: https://paketo.io/docs +:paketo-java-reference: {paketo-reference}/buildpacks/language-family-buildpacks/java [[introduction]] diff --git a/spring-boot-project/spring-boot-tools/spring-boot-maven-plugin/src/docs/asciidoc/packaging-oci-image.adoc b/spring-boot-project/spring-boot-tools/spring-boot-maven-plugin/src/docs/asciidoc/packaging-oci-image.adoc index de9b32cca6..183513772f 100644 --- a/spring-boot-project/spring-boot-tools/spring-boot-maven-plugin/src/docs/asciidoc/packaging-oci-image.adoc +++ b/spring-boot-project/spring-boot-tools/spring-boot-maven-plugin/src/docs/asciidoc/packaging-oci-image.adoc @@ -226,9 +226,6 @@ The following is an example of {paketo-java-reference}/#configuring-the-jvm-vers include::../maven/packaging-oci-image/build-image-example-builder-configuration-pom.xml[tags=build-image-example-builder-configuration] ---- -In a similar way, Paketo Java buildpacks support {paketo-java-reference}/#runtime-jvm-configuration[configuring JVM runtime behavior]. -Refer to the {paketo-java-reference}[Paketo documentation] for additional configuration options supported by Paketo Java buildpacks. - If there is a network proxy between the Docker daemon the builder runs in and network locations that buildpacks download artifacts from, you will need to configure the builder to use the proxy. When using the Paketo builder, this can be accomplished by setting the `HTTPS_PROXY` and/or `HTTP_PROXY` environment variables as show in the following example: @@ -239,6 +236,37 @@ include::../maven/packaging-oci-image/paketo-pom.xml[tags=paketo] +[[build-image-example-runtime-jvm-configuration]] +==== Runtime JVM Configuration +Paketo Java buildpacks {paketo-java-reference}/#runtime-jvm-configuration[configure the JVM runtime environment] by setting the `JAVA_TOOL_OPTIONS` environment variable. +The buildpack-provided `JAVA_TOOL_OPTIONS` value can be modified to customize JVM runtime behavior when the application image is launched in a container. + +Environment variable modifications that should be stored in the image and applied to every deployment can be set as described in the {paketo-reference}/buildpacks/configuration/#environment-variables[Paketo documentation] and shown in the following example: + +[source,xml,indent=0,subs="verbatim,attributes"] +---- + + + + + org.springframework.boot + spring-boot-maven-plugin + + + + + -XX:+HeapDumpOnOutOfMemoryError + + + + + + + +---- + + + [[build-image-example-custom-image-name]] ==== Custom Image Name By default, the image name is inferred from the `artifactId` and the `version` of the project, something like `docker.io/library/${project.artifactId}:${project.version}`.