The plugin can create an https://github.com/opencontainers/image-spec[OCI image] from executable jars using https://buildpacks.io[Cloud Native Buildpacks].
Images can be built using the `bootBuildImage` task and a local Docker installation.
The task is automatically created when the `java` plugin is applied and is an instance of {boot-build-image-javadoc}[`BootBuildImage`].
[[build-image-customization]]
=== Image Customizations
The plugin invokes a {buildpacks-reference}/concepts/components/builder/[builder] to orchestrate the generation of an image.
@ -37,12 +38,15 @@ The following table summarizes the available properties and their default values
| `verboseLogging`
| Enables verbose logging of builder operations.
| `false`
|===
[[build-image-examples]]
=== Examples
[[build-image-example-custom-image-builder]]
==== Custom Image Builder
If you need to customize the builder used to create the image, configure the task as shown in the following example:
The example above assumes that the builder defines a `BP_JAVA_VERSION` property (typically used to customize the JDK version the image should use).
[[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}`.
The plugin can create executable archives (jar files and war files) that contain all of an application's dependencies and can then be run with `java -jar`.
[[packaging-executable-jars]]
=== Packaging executable jars
Executable jars can be built using the `bootJar` task.
The task is automatically created when the `java` plugin is applied and is an instance of {boot-jar-javadoc}[`BootJar`].
The `assemble` task is automatically configured to depend upon the `bootJar` task so running `assemble` (or `build`) will also run the `bootJar` task.
@ -16,7 +14,6 @@ The `assemble` task is automatically configured to depend upon the `bootJar` tas
[[packaging-executable-wars]]
=== Packaging executable wars
Executable wars can be built using the `bootWar` task.
The task is automatically created when the `war` plugin is applied and is an instance of {boot-war-javadoc}[`BootWar`].
The `assemble` task is automatically configured to depend upon the `bootWar` task so running `assemble` (or `build`) will also run the `bootWar` task.
@ -25,7 +22,6 @@ The `assemble` task is automatically configured to depend upon the `bootWar` tas
[[packaging-executable-wars-deployable]]
==== Packaging executable and deployable wars
A war file can be packaged such that it can be executed using `java -jar` and deployed to an external container.
To do so, the embedded servlet container dependencies should be added to the `providedRuntime` configuration, for example:
@ -50,7 +46,6 @@ NOTE: `providedRuntime` is preferred to Gradle's `compileOnly` configuration as,
[[packaging-executable-and-normal]]
=== Packaging executable and normal archives
By default, when the `bootJar` or `bootWar` tasks are configured, the `jar` or `war` tasks are disabled.
A project can be configured to build both an executable archive and a normal archive at the same time by enabling the `jar` or `war` task:
The {boot-jar-javadoc}[`BootJar`] and {boot-war-javadoc}[`BootWar`] tasks are subclasses of Gradle's `Jar` and `War` tasks respectively.
As a result, all of the standard configuration options that are available when packaging a jar or war are also available when packaging an executable jar or war.
A number of configuration options that are specific to executable jars and wars are also provided.
@ -93,7 +87,6 @@ A number of configuration options that are specific to executable jars and wars
[[packaging-executable-configuring-main-class]]
==== Configuring the main class
By default, the executable archive's main class will be configured automatically by looking for a class with a `public static void main(String[])` method in directories on the task's classpath.
The main class can also be configured explicitly using the task's `mainClassName` property:
If the {application-plugin}[`application` plugin] has been applied its `mainClassName` project property must be configured and can be used for the same purpose:
By default, the `bootJar` tasks builds an archive that contains the application's classes and dependencies in `BOOT-INF/classes` and `BOOT-INF/lib` respectively.
For cases where a docker image needs to be built from the contents of the jar, the jar format can be enhanced to support layer folders.
To use this feature, the layering feature must be enabled:
When the {maven-plugin}[`maven` plugin] is applied, an `Upload` task for the `bootArchives` configuration named `uploadBootArchives` is automatically created.
By default, the `bootArchives` configuration contains the archive produced by the `bootJar` or `bootWar` task.
The `uploadBootArchives` task can be configured to publish the archive to a Maven repository:
When the {dependency-management-plugin}[`io.spring.dependency-management` plugin] is applied to a project, the Spring Boot plugin will automatically import the `spring-boot-dependencies` bom.
[[reacting-to-other-plugins-application]]
=== Reacting to the application plugin
When Gradle's {application-plugin}[`application` plugin] is applied to a project, the Spring Boot plugin:
1. Creates a `CreateStartScripts` task named `bootStartScripts` that will create scripts that launch the artifact in the `bootArchives` configuration using `java -jar`.
@ -71,5 +65,4 @@ When Gradle's {application-plugin}[`application` plugin] is applied to a project
[[reacting-to-other-plugins-maven]]
=== Reacting to the Maven plugin
When Gradle's {maven-plugin}[`maven` plugin] is applied to a project, the Spring Boot plugin will configure the `uploadBootArchives` `Upload` task to ensure that no dependencies are declared in the pom that it generates.
If the {application-plugin}[`application` plugin] has been applied, its `mainClassName` property must be configured and can be used for the same purpose:
While you may start your Spring Boot application very easily from your test (or test suite) itself, it may be desirable to handle that in the build itself.
To make sure that the lifecycle of your Spring Boot application is properly managed around your integration tests, you can use the `start` and `stop` goals, as shown in the following example:
@ -30,6 +30,8 @@ It is possible to automate the creation of an image whenever the `package` phase
TIP: While the buildpack runs from an <<repackage,executable archive>>, it is not necessary to execute the `repackage` goal first as the executable archive is created automatically if necessary.
When the `build-image` repackages the application, it applies the same settings as the `repackage` goal would, i.e. dependencies can be excluded using one of the exclude options, and Devtools is automatically excluded by default (you can control that using the `excludeDevtools` property).
[[build-image-customization]]
=== Image Customizations
The plugin invokes a {buildpacks-reference}/concepts/components/builder/[builder] to orchestrate the generation of an image.
@ -62,7 +64,6 @@ The following table summarizes the available properties and their default values
| `verboseLogging`
| Enables verbose logging of builder operations.
| `false`
|===
For more details, see <<build-image-example-custom-image-builder,custom image builder>> and <<build-image-example-custom-image-name,custom image name>>.
@ -70,9 +71,12 @@ For more details, see <<build-image-example-custom-image-builder,custom image bu
include::goals/build-image.adoc[leveloffset=+1]
[[build-image-examples]]
=== Examples
[[build-image-example-custom-image-builder]]
==== Custom Image Builder
If you need to customize the builder used to create the image, configure yours as shown in the following example:
Phillip Webb
5 years ago