@@ -40,26 +40,20 @@ Andy Wilkinson, Scott Frederick
[[introduction]]
== Introduction
The Spring Boot Gradle Plugin provides Spring Boot support in https://gradle.org[Gradle].
It allows you to package executable jar or war archives, run Spring Boot applications, and use the dependency management provided by `spring-boot-dependencies`.
Spring Boot's Gradle plugin requires Gradle 6.8, 6.9, or 7.x and can be used with Gradle's {gradle-userguide}/configuration_cache.html[configuration cache].
include::introduction.adoc[leveloffset=+1]
In addition to this user guide, {api-documentation}[API documentation] is also available.
Spring Boot Actuator's `info` endpoint automatically publishes information about your build in the presence of a `META-INF/build-info.properties` file.
A {build-info-javadoc}[`BuildInfo`] task is provided to generate this file.
The easiest way to use the task is via the plugin's DSL:
The Spring Boot Gradle Plugin provides Spring Boot support in https://gradle.org[Gradle].
It allows you to package executable jar or war archives, run Spring Boot applications, and use the dependency management provided by `spring-boot-dependencies`.
Spring Boot's Gradle plugin requires Gradle 6.8, 6.9, or 7.x and can be used with Gradle's {gradle-userguide}/configuration_cache.html[configuration cache].
In addition to this user guide, {api-documentation}[API documentation] is also available.
To manage dependencies in your Spring Boot application, you can either apply the {dependency-management-plugin}[`io.spring.dependency-management`] plugin or use Gradle's native bom support.
The primary benefit of the former is that it offers property-based customization of managed versions, while using the latter will likely result in faster builds.
=== Managing Dependencies with the Dependency Management Plugin
When you apply the {dependency-management-plugin}[`io.spring.dependency-management`] plugin, Spring Boot's plugin will automatically <<reacting-to-other-plugins-dependency-management,import the `spring-boot-dependencies` bom>> from the version of Spring Boot that you are using.
== Managing Dependencies with the Dependency Management Plugin
When you apply the {dependency-management-plugin}[`io.spring.dependency-management`] plugin, Spring Boot's plugin will automatically <<reacting-to-other-plugins.dependency-management,import the `spring-boot-dependencies` bom>> from the version of Spring Boot that you are using.
This provides a similar dependency management experience to the one that's enjoyed by Maven users.
For example, it allows you to omit version numbers when declaring dependencies that are managed in the bom.
To make use of this functionality, declare dependencies in the usual way but omit the version number:
The `spring-boot-dependencies` bom that is automatically imported when the dependency management plugin is applied uses properties to control the versions of the dependencies that it manages.
Browse the {version-properties-appendix}[`Dependency versions Appendix`] in the Spring Boot reference for a complete list of these properties.
...
...
@@ -51,8 +51,8 @@ Overriding versions may cause compatibility issues and should be done with care.
=== Using Spring Boot's Dependency Management in Isolation
Spring Boot's dependency management can be used in a project without applying Spring Boot's plugin to that project.
The `SpringBootPlugin` class provides a `BOM_COORDINATES` constant that can be used to import the bom without having to know its group ID, artifact ID, or version.
To learn more about the capabilities of the dependency management plugin, please refer to its {dependency-management-plugin-documentation}[documentation].
[[managing-dependencies-gradle-bom-support]]
=== Managing Dependencies with Gradle's Bom Support
[[managing-dependencies.gradle-bom-support]]
== Managing Dependencies with Gradle's Bom Support
Gradle allows a bom to be used to manage a project's versions by declaring it as a `platform` or `enforcedPlatform` dependency.
A `platform` dependency treats the versions in the bom as recommendations and other versions and constraints in the dependency graph may cause a version of a dependency other than that declared in the bom to be used.
An `enforcedPlatform` dependency treats the versions in the bom as requirements and they will override any other version found in the dependency graph.
...
...
@@ -157,8 +157,8 @@ As a result, in may be necessary to declare the same dependency in more than one
When using Gradle's bom support, you cannot use the properties from `spring-boot-dependencies` to control the versions of the dependencies that it manages.
Instead, you must use one of the mechanisms that Gradle provides.
The plugin can create an https://github.com/opencontainers/image-spec[OCI image] from a jar or war file using https://buildpacks.io[Cloud Native Buildpacks] (CNB).
Images can be built using the `bootBuildImage` task.
...
...
@@ -8,13 +8,13 @@ See the {buildpacks-reference}/reference/spec/platform-api/#users[CNB specificat
The task is automatically created when the `java` or `war` plugin is applied and is an instance of {boot-build-image-javadoc}[`BootBuildImage`].
NOTE: The `bootBuildImage` task can not be used with a <<packaging-executable-configuring-launch-script, fully executable Spring Boot archive>> that includes a launch script.
NOTE: The `bootBuildImage` task can not be used with a <<packaging-executable.configuring.launch-script, fully executable Spring Boot archive>> that includes a launch script.
Disable launch script configuration in the `bootJar` task when building a jar file that is intended to be used with `bootBuildImage`.
[[build-image-docker-daemon]]
=== Docker Daemon
[[build-image.docker-daemon]]
== Docker Daemon
The `bootBuildImage` task requires access to a Docker daemon.
By default, it will communicate with a Docker daemon over a local connection.
This works with https://docs.docker.com/install/[Docker Engine] on all supported platforms without configuration.
...
...
@@ -53,12 +53,12 @@ The following table summarizes the available properties:
| Path to certificate and key files for HTTPS (required if `tlsVerify` is `true`, ignored otherwise)
|===
For more details, see also <<build-image-example-docker,examples>>.
For more details, see also <<build-image.examples.docker,examples>>.
[[build-image-docker-registry]]
=== Docker Registry
[[build-image.docker-registry]]
== Docker Registry
If the Docker images specified by the `builder` or `runImage` properties are stored in a private Docker image registry that requires authentication, the authentication credentials can be provided using `docker.builderRegistry` properties.
If the generated Docker image is to be published to a Docker image registry, the authentication credentials can be provided using `docker.publishRegistry` properties.
...
...
@@ -87,12 +87,12 @@ The following table summarizes the available properties for `docker.builderRegis
| Identity token for the Docker image registry user. Required for token authentication.
|===
For more details, see also <<build-image-example-docker,examples>>.
For more details, see also <<build-image.examples.docker,examples>>.
[[build-image-customization]]
=== Image Customizations
[[build-image.customization]]
== Image Customizations
The plugin invokes a {buildpacks-reference}/concepts/components/builder/[builder] to orchestrate the generation of an image.
The builder includes multiple {buildpacks-reference}/concepts/components/buildpack[buildpacks] that can inspect the application to influence the generated image.
By default, the plugin chooses a builder image.
...
...
@@ -176,17 +176,17 @@ Where `<options>` can contain:
NOTE: The plugin detects the target Java compatibility of the project using the JavaPlugin's `targetCompatibility` property.
When using the default Paketo builder and buildpacks, the plugin instructs the buildpacks to install the same Java version.
You can override this behaviour as shown in the <<build-image-example-builder-configuration,builder configuration>> examples.
You can override this behaviour as shown in the <<build-image.examples.builder-configuration,builder configuration>> examples.
[[build-image-examples]]
=== Examples
[[build-image.examples]]
== Examples
[[build-image-example-custom-image-builder]]
==== Custom Image Builder and Run Image
[[build-image.examples.custom-image-builder]]
=== Custom Image Builder and Run Image
If you need to customize the builder used to create the image or the run image used to launch the built image, configure the task as shown in the following example:
@@ -212,8 +212,8 @@ The builder and run image can be specified on the command line as well, as shown
[[build-image-example-builder-configuration]]
==== Builder Configuration
[[build-image.examples.builder-configuration]]
=== Builder Configuration
If the builder exposes configuration options, those can be set using the `environment` property.
The following is an example of {paketo-java-reference}/#configuring-the-jvm-version[configuring the JVM version] used by the Paketo Java buildpacks at build time:
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.
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}`.
You can take control over the name by setting task properties, as shown in the following example:
...
...
@@ -297,8 +297,8 @@ The image name can be specified on the command line as well, as shown in this ex
[[build-image-example-buildpacks]]
==== Buildpacks
[[build-image.examples.buildpacks]]
=== Buildpacks
By default, the builder will use buildpacks included in the builder image and apply them in a pre-defined order.
An alternative set of buildpacks can be provided to apply buildpacks that are not included in the builder, or to change the order of included buildpacks.
When one or more buildpacks are provided, only the specified buildpacks will be applied.
...
...
@@ -347,8 +347,8 @@ An OCI image containing a https://buildpacks.io/docs/buildpack-author-guide/pack
[[build-image-example-publish]]
==== Image Publishing
[[build-image.examples.publish]]
=== Image Publishing
The generated image can be published to a Docker registry by enabling a `publish` option and configuring authentication for the registry using `docker.publishRegistry` properties.
@@ -372,8 +372,8 @@ The publish option can be specified on the command line as well, as shown in thi
[[build-image-example-docker]]
==== Docker Configuration
[[build-image.examples.docker]]
=== Docker Configuration
If you need the plugin to communicate with the Docker daemon using a remote connection instead of the default local connection, the connection details can be provided using `docker` properties as shown in the following example:
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
[[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.
[[packaging-executable-wars]]
=== Packaging Executable Wars
[[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.
[[packaging-executable-wars-deployable]]
==== Packaging Executable and Deployable Wars
[[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:
...
...
@@ -43,8 +43,8 @@ NOTE: `providedRuntime` is preferred to Gradle's `compileOnly` configuration as,
[[packaging-executable-and-plain]]
=== Packaging Executable and Plain Archives
[[packaging-executable.and-plain-archives]]
== Packaging Executable and Plain Archives
By default, when the `bootJar` or `bootWar` tasks are configured, the `jar` or `war` tasks are configured to use `plain` as the convention for their archive classifier.
This ensures that `bootJar` and `jar` or `bootWar` and `war` have different output locations, allowing both the executable archive and the plain archive to be built at the same time.
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.
[[packaging-executable-configuring-main-class]]
==== Configuring the Main Class
[[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 `mainClass` property:
...
...
@@ -153,8 +153,8 @@ If another name is defined using `@JvmName` then that name should be used.
By default all dependencies declared in the `developmentOnly` configuration will be excluded from an executable jar or war.
If you want to include dependencies declared in the `developmentOnly` configuration in your archive, configure the classpath of its task to include the configuration, as shown in the following example for the `bootWar` task:
By default, the `bootJar` task builds an archive that contains the application's classes and dependencies in `BOOT-INF/classes` and `BOOT-INF/lib` respectively.
Similarly, `bootWar` builds an archive that contains the application's classes in `WEB-INF/classes` and dependencies in `WEB-INF/lib` and `WEB-INF/lib-provided`.
For cases where a docker image needs to be built from the contents of the jar, it's useful to be able to separate these directories further so that they can be written into distinct layers.
WARNING: Due to its deprecation in Gradle 6, this plugin's support for publishing with Gradle's `maven` plugin is deprecated and will be removed in a future release.
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
[[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`.
...
...
@@ -65,7 +65,7 @@ When Gradle's {application-plugin}[`application` plugin] is applied to a project
[[reacting-to-other-plugins-maven]]
=== Reacting to the Maven plugin
=Í= Reacting to the Maven plugin
WARNING: Support for reacting to Gradle's `maven` plugin is deprecated and will be removed in a future release.
