## File: build-plugin/spring-boot-maven-plugin/src/docs/antora/modules/maven-plugin/partials/nav-maven-plugin.adoc * xref:maven-plugin:index.adoc[] ** xref:maven-plugin:getting-started.adoc[] ** xref:maven-plugin:using.adoc[] ** xref:maven-plugin:goals.adoc[] ** xref:maven-plugin:packaging.adoc[] ** xref:maven-plugin:build-image.adoc[] ** xref:maven-plugin:run.adoc[] ** xref:maven-plugin:aot.adoc[] ** xref:maven-plugin:integration-tests.adoc[] ** xref:maven-plugin:build-info.adoc[] ** xref:maven-plugin:help.adoc[] --- ## File: build-plugin/spring-boot-maven-plugin/src/docs/antora/modules/maven-plugin/pages/aot.adoc [[aot]] = Ahead-of-Time Processing Spring AOT is a process that analyzes your application at build-time and generate an optimized version of it. It is a mandatory step to run a Spring `ApplicationContext` in a native image. NOTE: For an overview of GraalVM Native Images support in Spring Boot, check the xref:reference:packaging/native-image/index.adoc[reference documentation]. The Spring Boot Maven plugin offers goals that can be used to perform AOT processing on both application and test code. [[aot.processing-applications]] == Processing Applications To configure your application to use this feature, add an execution for the `process-aot` goal, as shown in the following example: [source,xml,indent=0,subs="verbatim,attributes"] ---- include::example$aot/pom.xml[tags=aot] ---- As the `BeanFactory` is fully prepared at build-time, conditions are also evaluated. This has an important difference compared to what a regular Spring Boot application does at runtime. For instance, if you want to opt-in or opt-out for certain features, you need to configure the environment used at build time to do so. The `process-aot` goal shares a number of properties with the xref:run.adoc[run goal] for that reason. [[aot.processing-applications.using-the-native-profile]] === Using the Native Profile If you use `spring-boot-starter-parent` as the `parent` of your project, a `native` profile can be used to streamline the steps required to build a native image. The `native` profile configures the following: * Execution of `process-aot` when the Spring Boot Maven Plugin is applied on a project. * Suitable settings so that xref:build-image.adoc[build-image] generates a native image. * Sensible defaults for the {url-native-build-tools-docs-maven-plugin}[Native Build Tools Maven Plugin], in particular: ** Making sure the plugin uses the raw classpath, and not the main jar file as it does not understand our repackaged jar format. ** Validate that a suitable GraalVM version is available. ** Download third-party reachability metadata. [WARNING] ==== The use of the raw classpath means that native image does not know about the generated `MANIFEST.MF`. If you need to read the content of the manifest in a native image, for instance to get the implementation version of your application, configure the `classesDirectory` option to use the regular jar. ==== To benefit from the `native` profile, a module that represents an application should define two plugins, as shown in the following example: [source,xml,indent=0,subs="verbatim,attributes"] ---- include::example$aot-native/pom.xml[tags=aot-native] ---- A single project can trigger the generation of a native image on the command-line using either xref:how-to:native-image/developing-your-first-application.adoc#howto.native-image.developing-your-first-application.buildpacks.maven[Cloud Native Buildpacks] or xref:how-to:native-image/developing-your-first-application.adoc#howto.native-image.developing-your-first-application.native-build-tools.maven[Native Image Build Tools]. To use the `native` profile with a multi-modules project, you can create a customization of the `native` profile so that it invokes your preferred technique. To bind Cloud Native Buildpacks during the `package` phase, add the following to the root POM of your multi-modules project: [source,xml,indent=0,subs="verbatim,attributes"] ---- include::example$aot-native-profile-buildpacks/pom.xml[tags=profile] ---- The example below does the same for Native Build Tools: [source,xml,indent=0,subs="verbatim,attributes"] ---- include::example$aot-native-profile-nbt/pom.xml[tags=profile] ---- Once the above is in place, you can build your multi-modules project and generate a native image in the relevant sub-modules, as shown in the following example: [source,shell] ---- $ mvn package -Pnative ---- NOTE: A "relevant" sub-module is a module that represents a Spring Boot application. Such module must define the Native Build Tools and Spring Boot plugins as described above. include::partial$goals/process-aot.adoc[leveloffset=+1] [[aot.processing-tests]] == Processing Tests The AOT engine can be applied to JUnit 5 tests that use Spring's Test Context Framework. Those tests are processed by the AOT engine and are then executed in a native image. NOTE: Tests are not processed when the regular tests are skipped using the `maven.test.skip` property. Just like <>, the `spring-boot-starter-parent` defines a `nativeTest` profile that can be used to streamline the steps required to execute your tests in a native image. The `nativeTest` profile configures the following: * Execution of `process-test-aot` when the Spring Boot Maven Plugin is applied on a project. * Execution of `test` when the {url-native-build-tools-docs-maven-plugin}[Native Build Tools Maven Plugin] is applied on a project. The execution defines sensible defaults, in particular: ** Making sure the plugin uses the raw classpath, and not the main jar file as it does not understand our repackaged jar format. ** Validate that a suitable GraalVM version is available. ** Download third-party reachability metadata. To benefit from the `nativeTest` profile, a module that represents an application should define two plugins, as shown in the following example: [source,xml,indent=0,subs="verbatim,attributes"] ---- include::example$aot-native/pom.xml[tags=aot-native] ---- Once the above is in place for each module that needs this feature, you can build your multi-modules project and execute your tests in a native image in the relevant sub-modules, as shown in the following example: [source,shell] ---- $ mvn test -PnativeTest ---- NOTE: As with application AOT processing, the `BeanFactory` is fully prepared at build-time. include::partial$goals/process-test-aot.adoc[leveloffset=+1] --- ## File: build-plugin/spring-boot-maven-plugin/src/docs/antora/modules/maven-plugin/pages/build-image.adoc [[build-image]] = Packaging OCI Images 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 on the command-line using the `build-image` goal. This makes sure that the package lifecycle has run before the image is created. NOTE: For security reasons, images build and run as non-root users. See the {url-buildpacks-docs}/reference/spec/platform-api/#users[CNB specification] for more details. The easiest way to get started is to invoke `mvn spring-boot:build-image` on a project. It is possible to automate the creation of an image whenever the `package` phase is invoked, as shown in the following example: [source,xml,indent=0,subs="verbatim,attributes"] ---- include::example$packaging-oci-image/pom.xml[tags=packaging-oci-image] ---- NOTE: Use `build-image-no-fork` when binding the goal to the package lifecycle. This goal is similar to `build-image` but does not fork the lifecycle to make sure `package` has run. In the rest of this section, `build-image` is used to refer to either the `build-image` or `build-image-no-fork` goals. TIP: While the buildpack runs from an xref:packaging.adoc[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, that is dependencies can be excluded using one of the exclude options. The `spring-boot-devtools` and `spring-boot-docker-compose` modules are automatically excluded by default (you can control this using the `excludeDevtools` and `excludeDockerCompose` properties). Pay also attention that optional dependencies are not included by default. If you have defined those modules as optional, you also need to set the `includeOptional` property to `true`. [[build-image.docker-daemon]] == Docker Daemon The `build-image` goal requires access to a Docker daemon. The goal will inspect local Docker CLI https://docs.docker.com/engine/reference/commandline/cli/#configuration-files[configuration files] to determine the current https://docs.docker.com/engine/context/working-with-contexts/[context] and use the context connection information to communicate with a Docker daemon. If the current context can not be determined or the context does not have connection information, then the goal will use a default local connection. This works with https://docs.docker.com/install/[Docker Engine] on all supported platforms without configuration. Environment variables can be set to configure the `build-image` goal to use an alternative local or remote connection. The following table shows the environment variables and their values: |=== | Environment variable | Description | DOCKER_CONFIG | Location of Docker CLI https://docs.docker.com/engine/reference/commandline/cli/#configuration-files[configuration files] used to determine the current context (defaults to `$HOME/.docker`) | DOCKER_CONTEXT | Name of a https://docs.docker.com/engine/context/working-with-contexts/[context] that should be used to retrieve host information from Docker CLI configuration files (overrides `DOCKER_HOST`) | DOCKER_HOST | URL containing the host and port for the Docker daemon - for example `tcp://192.168.99.100:2376` | DOCKER_TLS_VERIFY | Enable secure HTTPS protocol when set to `1` (optional) | DOCKER_CERT_PATH | Path to certificate and key files for HTTPS (required if `DOCKER_TLS_VERIFY=1`, ignored otherwise) |=== Docker daemon connection information can also be provided using `docker` parameters in the plugin configuration. The following table summarizes the available parameters: |=== | Parameter | Description | `context` | Name of a https://docs.docker.com/engine/context/working-with-contexts/[context] that should be used to retrieve host information from Docker CLI https://docs.docker.com/engine/reference/commandline/cli/#configuration-files[configuration files] | `host` | URL containing the host and port for the Docker daemon - for example `tcp://192.168.99.100:2376` | `tlsVerify` | Enable secure HTTPS protocol when set to `true` (optional) | `certPath` | Path to certificate and key files for HTTPS (required if `tlsVerify` is `true`, ignored otherwise) | `bindHostToBuilder` | When `true`, the value of the `host` property will be provided to the container that is created for the CNB builder (optional) |=== For more details, see also xref:build-image.adoc#build-image.examples.docker[examples]. [[build-image.docker-registry]] == Docker Registry If the Docker images specified by the `builder` or `runImage` parameters are stored in a private Docker image registry that requires authentication, the authentication credentials can be provided using `docker.builderRegistry` parameters. If the generated Docker image is to be published to a Docker image registry, the authentication credentials can be provided using `docker.publishRegistry` parameters. Parameters are provided for user authentication or identity token authentication. Consult the documentation for the Docker registry being used to store images for further information on supported authentication methods. The following table summarizes the available parameters for `docker.builderRegistry` and `docker.publishRegistry`: |=== | Parameter | Description | `username` | Username for the Docker image registry user. Required for user authentication. | `password` | Password for the Docker image registry user. Required for user authentication. | `url` | Address of the Docker image registry. Optional for user authentication. | `email` | E-mail address for the Docker image registry user. Optional for user authentication. | `token` | Identity token for the Docker image registry user. Required for token authentication. |=== For more details, see also xref:build-image.adoc#build-image.examples.docker[examples]. [NOTE] ==== If credentials are not provided, the plugin reads the user's existing Docker configuration file (typically located at `$HOME/.docker/config.json`) to determine authentication methods. Using these methods, the plugin attempts to provide authentication credentials for the requested image. The plugin supports the following authentication methods: - *Credential Helpers*: External tools configured in the Docker configuration file to provide credentials for specific registries. For example, tools like `osxkeychain` or `ecr-login` handle authentication for certain registries. - *Credential Store*: A default fallback mechanism that securely stores and retrieves credentials (e.g., `desktop` for Docker Desktop). - *Static Credentials*: Credentials that are stored directly in the Docker configuration file under the `auths` section. ==== [[build-image.customization]] == Image Customizations The plugin invokes a {url-buildpacks-docs}/for-app-developers/concepts/builder/[builder] to orchestrate the generation of an image. The builder includes multiple {url-buildpacks-docs}/for-app-developers/concepts/buildpack/[buildpacks] that can inspect the application to influence the generated image. By default, the plugin chooses a builder image. The name of the generated image is deduced from project properties. The `image` parameter allows configuration of the builder and how it should operate on the project. The following table summarizes the available parameters and their default values: [cols="1,4,1"] |=== | Parameter / (User Property)| Description | Default value | `builder` + (`spring-boot.build-image.builder`) | Name of the builder image to use. | `paketobuildpacks/builder-noble-java-tiny:latest` | `trustBuilder` + (`spring-boot.build-image.trustBuilder`) | Whether to treat the builder as {url-buildpacks-docs}/for-platform-operators/how-to/integrate-ci/pack/concepts/trusted_builders/#what-is-a-trusted-builder[trusted]. | `true` if the builder is one of `paketobuildpacks/builder-noble-java-tiny`, `paketobuildpacks/builder-jammy-java-tiny`, `paketobuildpacks/builder-jammy-tiny`, `paketobuildpacks/builder-jammy-base`, `paketobuildpacks/builder-jammy-full`, `paketobuildpacks/builder-jammy-buildpackless-tiny`, `paketobuildpacks/builder-jammy-buildpackless-base`, `paketobuildpacks/builder-jammy-buildpackless-full`, `gcr.io/buildpacks/builder`, `heroku/builder`; `false` otherwise. | `imagePlatform` + (`spring-boot.build-image.imagePlatform`) a|The platform (operating system and architecture) of any builder, run, and buildpack images that are pulled. Must be in the form of `OS[/architecture[/variant]]`, such as `linux/amd64`, `linux/arm64`, or `linux/arm/v5`. Refer to documentation of the builder being used to determine the image OS and architecture options available. | No default value, indicating that the platform of the host machine should be used. | `runImage` + (`spring-boot.build-image.runImage`) | Name of the run image to use. | No default value, indicating the run image specified in Builder metadata should be used. | `name` + (`spring-boot.build-image.imageName`) | javadoc:org.springframework.boot.buildpack.platform.docker.type.ImageName#of(java.lang.String)[Image name] for the generated image. | `docker.io/library/` + `${project.artifactId}:${project.version}` | `pullPolicy` + (`spring-boot.build-image.pullPolicy`) | javadoc:org.springframework.boot.buildpack.platform.build.PullPolicy[Policy] used to determine when to pull the builder and run images from the registry. Acceptable values are `ALWAYS`, `NEVER`, and `IF_NOT_PRESENT`. | `ALWAYS` | `env` | Environment variables that should be passed to the builder. | | `buildpacks` a|Buildpacks that the builder should use when building the image. Only the specified buildpacks will be used, overriding the default buildpacks included in the builder. Buildpack references must be in one of the following forms: * Buildpack in the builder - `[urn:cnb:builder:][@]` * Buildpack in a directory on the file system - `[file://]` * Buildpack in a gzipped tar (.tgz) file on the file system - `[file://]/` * Buildpack in an OCI image - `[docker://]/[:][@]` | None, indicating the builder should use the buildpacks included in it. | `bindings` a|https://docs.docker.com/storage/bind-mounts/[Volume bind mounts] that should be mounted to the builder container when building the image. The bindings will be passed unparsed and unvalidated to Docker when creating the builder container. Bindings must be in one of the following forms: * `:[:]` * `:[:]` Where `` can contain: * `ro` to mount the volume as read-only in the container * `rw` to mount the volume as readable and writable in the container * `volume-opt=key=value` to specify key-value pairs consisting of an option name and its value | | `network` + (`spring-boot.build-image.network`) | The https://docs.docker.com/network/#network-drivers[network driver] the builder container will be configured to use. The value supplied will be passed unvalidated to Docker when creating the builder container. | | `cleanCache` + (`spring-boot.build-image.cleanCache`) | Whether to clean the cache before building. | `false` | `verboseLogging` | Enables verbose logging of builder operations. | `false` | `publish` + (`spring-boot.build-image.publish`) | Whether to publish the generated image to a Docker registry. | `false` | `tags` | One or more additional tags to apply to the generated image. The values provided to the `tags` option should be *full* image references. See xref:build-image.adoc#build-image.customization.tags[the tags section] for more details. | | `buildWorkspace` | A temporary workspace that will be used by the builder and buildpacks to store files during image building. The value can be a named volume or a bind mount location. | A named volume in the Docker daemon, with a name derived from the image name. | `buildCache` | A cache containing layers created by buildpacks and used by the image building process. The value can be a named volume or a bind mount location. | A named volume in the Docker daemon, with a name derived from the image name. | `launchCache` | A cache containing layers created by buildpacks and used by the image launching process. The value can be a named volume or a bind mount location. | A named volume in the Docker daemon, with a name derived from the image name. | `createdDate` + (`spring-boot.build-image.createdDate`) | A date that will be used to set the `Created` field in the generated image's metadata. The value must be a string in the ISO 8601 instant format, or `now` to use the current date and time. | A fixed date that enables {url-buildpacks-docs}/for-app-developers/concepts/reproducibility/[build reproducibility]. | `applicationDirectory` + (`spring-boot.build-image.applicationDirectory`) | The path to a directory that application contents will be uploaded to in the builder image. Application contents will also be in this location in the generated image. | `/workspace` | `securityOptions` | https://docs.docker.com/reference/cli/docker/container/run/#security-opt[Security options] that will be applied to the builder container, provided as an array of string values | `["label=disable"]` on Linux and macOS, `[]` on Windows |=== NOTE: The plugin detects the target Java compatibility of the project using the compiler's plugin configuration or the `maven.compiler.target` 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 xref:build-image.adoc#build-image.examples.builder-configuration[builder configuration] examples. For more details, see also xref:build-image.adoc#build-image.examples[examples]. [[build-image.customization.tags]] === Tags Format The values provided to the `tags` option should be *full* image references. The accepted format is `[domainHost:port/][path/]name[:tag][@digest]`. If the domain is missing, it defaults to `docker.io`. If the path is missing, it defaults to `library`. If the tag is missing, it defaults to `latest`. Some examples: * `my-image` leads to the image reference `docker.io/library/my-image:latest` * `my-repository/my-image` leads to `docker.io/my-repository/my-image:latest` * `example.com/my-repository/my-image:1.0.0` will be used as is include::partial$goals/build-image.adoc[leveloffset=+1] include::partial$goals/build-image-no-fork.adoc[leveloffset=+1] [[build-image.examples]] == Examples [[build-image.examples.custom-image-builder]] === Custom Image Builder If you need to customize the builder used to create the image or the run image used to launch the built image, configure the plugin as shown in the following example: [source,xml,indent=0,subs="verbatim,attributes"] ---- include::example$packaging-oci-image/custom-image-builder-pom.xml[tags=custom-image-builder] ---- This configuration will use a builder image with the name `mine/java-cnb-builder` and the tag `latest`, and the run image named `mine/java-cnb-run` and the tag `latest`. The builder and run image can be specified on the command line as well, as shown in this example: [source,shell] ---- $ mvn spring-boot:build-image -Dspring-boot.build-image.builder=mine/java-cnb-builder -Dspring-boot.build-image.runImage=mine/java-cnb-run ---- [[build-image.examples.builder-configuration]] === Builder Configuration If the builder exposes configuration options using environment variables, those can be set using the `env` attributes. The following is an example of {url-paketo-docs-java-buildpack}/#configuring-the-jvm-version[configuring the JVM version] used by the Paketo Java buildpacks at build time: [source,xml,indent=0,subs="verbatim,attributes"] ---- include::example$packaging-oci-image/build-image-example-builder-configuration-pom.xml[tags=build-image-example-builder-configuration] ---- 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: [source,xml,indent=0,subs="verbatim,attributes"] ---- include::example$packaging-oci-image/paketo-pom.xml[tags=paketo] ---- [[build-image.examples.runtime-jvm-configuration]] === Runtime JVM Configuration Paketo Java buildpacks {url-paketo-docs-java-buildpack}/#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 {url-paketo-docs}/buildpacks/configuration/#environment-variables[Paketo documentation] and shown in the following example: [source,xml,indent=0,subs="verbatim,attributes"] ---- include::example$packaging-oci-image/runtime-jvm-configuration-pom.xml[tags=runtime-jvm-configuration] ---- [[build-image.examples.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}`. You can take control over the name, as shown in the following example: [source,xml,indent=0,subs="verbatim,attributes"] ---- include::example$packaging-oci-image/custom-image-name-pom.xml[tags=custom-image-name] ---- NOTE: This configuration does not provide an explicit tag so `latest` is used. It is possible to specify a tag as well, either using `${project.version}`, any property available in the build or a hardcoded version. The image name can be specified on the command line as well, as shown in this example: [source,shell] ---- $ mvn spring-boot:build-image -Dspring-boot.build-image.imageName=example.com/library/my-app:v1 ---- [[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. The following example instructs the builder to use a custom buildpack packaged in a `.tgz` file, followed by a buildpack included in the builder. [source,xml,indent=0,subs="verbatim,attributes"] ---- include::example$packaging-oci-image/buildpacks-pom.xml[tags=buildpacks] ---- Buildpacks can be specified in any of the forms shown below. A buildpack located in a CNB Builder (version may be omitted if there is only one buildpack in the builder matching the `buildpack-id`): * `urn:cnb:builder:buildpack-id` * `urn:cnb:builder:buildpack-id@0.0.1` * `buildpack-id` * `buildpack-id@0.0.1` A path to a directory containing buildpack content (not supported on Windows): * `\file:///path/to/buildpack/` * `/path/to/buildpack/` A path to a gzipped tar file containing buildpack content: * `\file:///path/to/buildpack.tgz` * `/path/to/buildpack.tgz` An OCI image containing a {url-buildpacks-docs}/for-buildpack-authors/how-to/distribute-buildpacks/package-buildpack/[packaged buildpack]: * `docker://example/buildpack` * `docker:///example/buildpack:latest` * `docker:///example/buildpack@sha256:45b23dee08...` * `example/buildpack` * `example/buildpack:latest` * `example/buildpack@sha256:45b23dee08...` [[build-image.examples.publish]] === Image Publishing The generated image can be published to a Docker registry by enabling a `publish` option. If the Docker registry requires authentication, the credentials can be configured using `docker.publishRegistry` parameters. If the Docker registry does not require authentication, the `docker.publishRegistry` configuration can be omitted. NOTE: The registry that the image will be published to is determined by the registry part of the image name (`docker.example.com` in these examples). If `docker.publishRegistry` credentials are configured and include a `url` parameter, this value is passed to the registry but is not used to determine the publishing registry location. [source,xml,indent=0,subs="verbatim,attributes"] ---- include::example$packaging-oci-image/docker-pom.xml[tags=docker] ---- The `publish` option can be specified on the command line as well, as shown in this example: [source,shell] ---- $ mvn spring-boot:build-image -Dspring-boot.build-image.imageName=docker.example.com/library/my-app:v1 -Dspring-boot.build-image.publish=true ---- When using the `publish` option on the command line with authentication, you can provide credentials using properties as in this example: [source,shell] ---- $ mvn spring-boot:build-image \ -Ddocker.publishRegistry.username=user \ -Ddocker.publishRegistry.password=secret \ -Ddocker.publishRegistry.url=docker.example.com \ -Dspring-boot.build-image.publish=true \ -Dspring-boot.build-image.imageName=docker.example.com/library/my-app:v1 ---- and reference the properties in the XML configuration: [source,xml,indent=0,subs="verbatim,attributes"] ---- include::example$packaging-oci-image/docker-pom-authentication-command-line.xml[tags=docker] ---- [[build-image.examples.caches]] === Builder Cache and Workspace Configuration The CNB builder caches layers that are used when building and launching an image. By default, these caches are stored as named volumes in the Docker daemon with names that are derived from the full name of the target image. If the image name changes frequently, for example when the project version is used as a tag in the image name, then the caches can be invalidated frequently. The cache volumes can be configured to use alternative names to give more control over cache lifecycle as shown in the following example: [source,xml,indent=0,subs="verbatim,attributes"] ---- include::example$packaging-oci-image/caches-pom.xml[tags=caches] ---- Builders and buildpacks need a location to store temporary files during image building. By default, this temporary build workspace is stored in a named volume. The caches and the build workspace can be configured to use bind mounts instead of named volumes, as shown in the following example: [source,xml,indent=0,subs="verbatim,attributes"] ---- include::example$packaging-oci-image/bind-caches-pom.xml[tags=caches] ---- The build cache can also be stored in an image instead of a named volume, which allows the cache to be shared between hosts by pushing and pulling it from an image registry, as shown in the following example: [source,xml,indent=0,subs="verbatim,attributes"] ---- include::example$packaging-oci-image/image-caches-pom.xml[tags=caches] ---- [[build-image.examples.docker]] === Docker Configuration [[build-image.examples.docker.minikube]] ==== Docker Configuration for minikube The plugin can communicate with the https://minikube.sigs.k8s.io/docs/tasks/docker_daemon/[Docker daemon provided by minikube] instead of the default local connection. On Linux and macOS, environment variables can be set using the command `eval $(minikube docker-env)` after minikube has been started. The plugin can also be configured to use the minikube daemon by providing connection details similar to those shown in the following example: [source,xml,indent=0,subs="verbatim,attributes"] ---- include::example$packaging-oci-image/docker-minikube-pom.xml[tags=docker-minikube] ---- [[build-image.examples.docker.podman]] ==== Docker Configuration for podman The plugin can communicate with a https://podman.io/[podman container engine]. The plugin can be configured to use podman local connection by providing connection details similar to those shown in the following example: [source,xml,indent=0,subs="verbatim,attributes"] ---- include::example$packaging-oci-image/docker-podman-pom.xml[tags=docker-podman] ---- TIP: With the `colima` CLI installed, the command `podman info --format='{{.Host.RemoteSocket.Path}}'` can be used to get the value for the `docker.host` configuration property shown in this example. [[build-image.examples.docker.colima]] ==== Docker Configuration for Colima The plugin can communicate with the Docker daemon provided by https://github.com/abiosoft/colima[Colima]. The `DOCKER_HOST` environment variable can be set by using the following command: [source,shell,subs="verbatim,attributes"] ---- $ export DOCKER_HOST=$(docker context inspect colima -f '{{.Endpoints.docker.Host}}') ---- The plugin can also be configured to use Colima daemon by providing connection details similar to those shown in the following example: [source,xml,indent=0,subs="verbatim,attributes"] ---- include::example$packaging-oci-image/docker-colima-pom.xml[tags=docker-colima] ---- [[build-image.examples.docker.auth]] ==== Docker Configuration for Authentication If the builder or run image are stored in a private Docker registry that supports user authentication, authentication details can be provided using `docker.builderRegistry` parameters as shown in the following example: [source,xml,indent=0,subs="verbatim,attributes"] ---- include::example$packaging-oci-image/docker-registry-authentication-pom.xml[tags=docker-registry-authentication] ---- If the builder or run image is stored in a private Docker registry that supports token authentication, the token value can be provided using `docker.builderRegistry` parameters as shown in the following example: [source,xml,indent=0,subs="verbatim,attributes"] ---- include::example$packaging-oci-image/docker-token-authentication-pom.xml[tags=docker-token-authentication] ---- --- ## File: build-plugin/spring-boot-maven-plugin/src/docs/antora/modules/maven-plugin/pages/build-info.adoc [[build-info]] = Integrating with Actuator Spring Boot Actuator displays build-related information if a `META-INF/build-info.properties` file is present. The `build-info` goal generates such file with the coordinates of the project and the build time. It also allows you to add an arbitrary number of additional properties, as shown in the following example: [source,xml,indent=0,subs="verbatim,attributes"] ---- include::example$build-info/pom.xml[tags=build-info] ---- This configuration will generate a `build-info.properties` at the expected location with three additional keys. NOTE: `java.version` is expected to be a regular property available in the project. It will be interpolated as you would expect. include::partial$goals/build-info.adoc[leveloffset=+1] --- ## File: build-plugin/spring-boot-maven-plugin/src/docs/antora/modules/maven-plugin/pages/getting-started.adoc [[getting-started]] = Getting Started To use the Spring Boot Maven Plugin, include the appropriate XML in the `plugins` section of your `pom.xml`, as shown in the following example: [source,xml,indent=0,subs="verbatim,attributes"] ---- include::example$getting-started/pom.xml[tags=getting-started] ---- ifeval::["{build-type}" == "commercial"] The plugin is published to the Spring Commercial repository. You will have to configure your build to access this repository. This is usually done through a local artifact repository that mirrors the content of the Spring Commercial repository. Alternatively, while it is not recommended, the Spring Commercial repository can also be accessed directly. In either case, see https://docs.vmware.com/en/Tanzu-Spring-Runtime/Commercial/Tanzu-Spring-Runtime/spring-enterprise-subscription.html[the Tanzu Spring Runtime documentation] for further details. endif::[] ifeval::["{build-type}" == "opensource"] If you use a milestone or snapshot release, you also need to add the appropriate `pluginRepository` elements, as shown in the following listing: [source,xml,indent=0,subs="verbatim,attributes"] ---- include::example$getting-started/plugin-repositories-pom.xml[tags=plugin-repositories] ---- endif::[] --- ## File: build-plugin/spring-boot-maven-plugin/src/docs/antora/modules/maven-plugin/pages/goals.adoc [[goals]] = Goals The Spring Boot Plugin has the following goals: include::partial$goals/overview.adoc[] --- ## File: build-plugin/spring-boot-maven-plugin/src/docs/antora/modules/maven-plugin/pages/help.adoc [[help]] = Help Information The `help` goal is a standard goal that displays information on the capabilities of the plugin. include::partial$goals/help.adoc[leveloffset=+1] --- ## File: build-plugin/spring-boot-maven-plugin/src/docs/antora/modules/maven-plugin/pages/index.adoc [[maven-plugin]] = Maven Plugin The Spring Boot Maven Plugin provides Spring Boot support in https://maven.org[Apache Maven]. It allows you to package executable jar or war archives, run Spring Boot applications, generate build information and start your Spring Boot application prior to running integration tests. To use it, you must use Maven 3.6.3 or later. In addition to this user guide, xref:api/java/index.html[API documentation] is also available. --- ## File: build-plugin/spring-boot-maven-plugin/src/docs/antora/modules/maven-plugin/pages/integration-tests.adoc [[integration-tests]] = Running Integration Tests 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: [source,xml,indent=0,subs="verbatim,attributes"] ---- include::example$integration-tests/pom.xml[tags=integration-tests] ---- Such setup can now use the https://maven.apache.org/surefire/maven-failsafe-plugin[failsafe-plugin] to run your integration tests as you would expect. NOTE: The application is started in a separate process and JMX is used to communicate with the application. By default, the plugin uses port `9001`. If you need to configure the JMX port, see xref:integration-tests.adoc#integration-tests.examples.jmx-port[the dedicated example]. You could also configure a more advanced setup to skip the integration tests when a specific property has been set, see xref:integration-tests.adoc#integration-tests.examples.skip[the dedicated example]. [[integration-tests.no-starter-parent]] == Using Failsafe Without Spring Boot's Parent POM Spring Boot's Parent POM, `spring-boot-starter-parent`, configures Failsafe's `` to be `${project.build.outputDirectory}`. Without this configuration, which causes Failsafe to use the compiled classes rather than the repackaged jar, Failsafe cannot load your application's classes. If you are not using the parent POM, you should configure Failsafe in the same way, as shown in the following example: [source,xml,indent=0,subs="verbatim,attributes"] ---- include::example$integration-tests/failsafe-pom.xml[tags=failsafe] ---- include::partial$goals/start.adoc[leveloffset=+1] include::partial$goals/stop.adoc[leveloffset=+1] [[integration-tests.examples]] == Examples [[integration-tests.examples.random-port]] === Random Port for Integration Tests One nice feature of the Spring Boot test integration is that it can allocate a free port for the web application. When the `start` goal of the plugin is used, the Spring Boot application is started separately, making it difficult to pass the actual port to the integration test itself. The example below showcases how you could achieve the same feature using the https://www.mojohaus.org/build-helper-maven-plugin[Build Helper Maven Plugin]: [source,xml,indent=0,subs="verbatim,attributes"] ---- include::example$integration-tests/random-port-pom.xml[tags=random-port] ---- You can now retrieve the `test.server.port` system property in any of your integration test to create a proper `URL` to the server. [[integration-tests.examples.jmx-port]] === Customize JMX Port The `jmxPort` property allows to customize the port the plugin uses to communicate with the Spring Boot application. This example shows how you can customize the port in case `9001` is already used: [source,xml,indent=0,subs="verbatim,attributes"] ---- include::example$integration-tests/customize-jmx-port-pom.xml[tags=customize-jmx-port] ---- TIP: If you need to configure the JMX port, make sure to do so in the global configuration as shown above so that it is shared by both goals. [[integration-tests.examples.skip]] === Skip Integration Tests The `skip` property allows to skip the execution of the Spring Boot maven plugin altogether. This example shows how you can skip integration tests with a command-line property and still make sure that the `repackage` goal runs: [source,xml,indent=0,subs="verbatim,attributes"] ---- include::example$integration-tests/skip-integration-tests-pom.xml[tags=skip-integration-tests] ---- By default, the integration tests will run but this setup allows you to easily disable them on the command-line as follows: [source,shell] ---- $ mvn verify -Dskip.it=true ----