The Paketo Java Buildpack allows users to create an image containing a JVM application from a precompiled artifact or directly from source.
The Java Buildpack is a composite buildpack and each step in a build is handled by one of it’s components. The following docs describe common build configurations. For a full set of configuration options and capabilities see the homepages for the component buildpacks.
All Java Buildpack examples will use the Paketo sample applications.
Examples assume that the root of this repository is the working directory:
git clone https://github.com/paketo-buildpacks/samples cd samplesCopied!
The pack CLI is used throughout the examples. pack is just one of several Cloud Native Buildpack platforms than can execute builds with the Java Buildpacks. For example, Spring Boot developers may want to explore the Spring Boot Maven Plugin or Spring Boot Gradle Plugin .
Examples assume that the Paketo Base builder is the default builder:
pack config default-builder paketobuildpacks/builder:baseCopied!
All java example images should return {"status":"UP"} from the actuator health endpoint.
docker run --rm --tty --publish 8080:8080 samples/java curl -s http://localhost:8080/actuator/health | jq .Copied!
The Java Buildpack can build from source using any of the following build tools:
The correct build tool to use will be detected based on the contents of the application directory.
The build should produce one the of supported artifact formats. After building, the buildpack will replace provided application source code with the exploded archive. The build will proceed as described in Building from a Compiled Artifact.
Example: Building with Maven
The following command creates an image from source with maven.
pack build samples/java \ --path java/mavenCopied!
Note: The following set of configuration options are not comprehensive, see the homepage for the relevant component buildpacks for a full-set of configuration options.
For a given build <TOOL>, where <TOOL> is one of MAVEN, GRADLE, LEIN or SBT, the selected artifact can be configured with one of the following environment variable at build-time:
BP_<TOOL>_BUILT_MODULE
BP_MAVEN_BUILT_MODULE=api, Paketo Maven Buildpack will look for the application artifact with the file pattern target/api/*.[jw]ar.BP_<TOOL>_BUILT_ARTIFACT
target/*.[jw]ar for Maven, build/libs/*.[jw]ar for gradle). See component buildpack homepage for details.BP_<TOOL>_BUILT_MODULE if set to a non-default value.BP_MAVEN_BUILT_ARTIFACT=out/api-*.jar, the Paketo Maven Buildpack will select a file with name out/api-1.0.0.jar.For a given build <TOOL>, where <TOOL> is one of MAVEN, GRADLE, LEIN or SBT, the build command can be configured with the following environment variable at build-time:
BP_<TOOL>_BUILD_ARGUMENTS
-Dmaven.test.skip=true package for Maven, --no-daemon -x test build for Gradle). See component buildpack homepage for details.BP_GRADLE_BUILD_ARGUMENTS=war, the Paketo Gradle Buildpack will execute ./gradlew war or gradle war (depending on the presence of the gradle wrapper).A binding with type maven and key settings.xml can be used to provide custom Maven settings.
<binding-name>
├── settings.xml
└── type
The value of settings.xml file may contain the credentials needed to connect to a private Maven repository.
Example: Providing Maven Settings
The following steps demonstrate how to use a settings.xml file from your workstation with pack.
Create a directory to contain the binding.
mkdir java/maven/bindingCopied!
Indicate that the binding is of type maven with a file called type inside the binding, containing the value maven.
echo -n "maven" > java/maven/binding/typeCopied!
Copy the settings.xml file from the workstation to the binding.
cp ~/.m2/settings.xml java/maven/binding/settings.xmlCopied!
Provide the binding to pack build.
pack build samples/java \ --path java/maven \ --volume $(pwd)/java/maven/binding:/platform/bindings/my-maven-settingsCopied!
An application developer may build an image from following archive formats:
The Java Buildpack expects the application directory to contain the extracted contents of the archive (e.g. an exploded JAR). Most platforms will automatically extract any provided archives.
If a WAR is detect the Java Buildpack will install Apache Tomcat. For exact set of supported Tomcat versions can be found in the Java Buildpack releases notes. For tomcat configuration options see the Apache Tomcat Buildpack.
The component buildpack for the provided artifact format will contribute a start command to the image.
Note: All three of the Apache Tomcat Buildpack, Executable Jar Buildpack, and DistZip Buildpack may opt-in during detection. However, only one of these buildpacks will actually contribute to the final image. This happens because the artifact type may be unknown during detection, if for example a previous buildpack compiles the artifact.
Example: Building from an Executable JAR
The following command uses Maven to compile an executable JAR and then uses pack to build an image from the JAR.
cd java/maven ./mvnw package pack build samples/java \ --path /target/demo-0.0.1-SNAPSHOT.jarCopied!
The resulting application image will be identical to that built in the Building with Maven example.
The Java Buildpack uses the BellSoft Liberica implementations of the JRE and JDK. JVM installation is handled by the BellSoft Liberica Buildpack. The JDK will be installed in the build container but only the JRE will be contributed to the application image.
See the [homepage][bp/bellsoft-liberica] for the Bellsoft Liberica Buildpackfor a full set of configuration options.
The Bellsoft Liberica Buildpack provides support for the latest patch release of all version lines supported at the time of buildpack release. The exact set of JDK/JRE versions support by a given buildpack version can be found in the Java Buildpack release notes.
The exact JRE version that was contributed to a given image can be read from the Bill-of-Materials.
Example Inspecting the JRE Version
Given an image named samples/java built from one of examples above, the following command should print the exact version of the installed JRE.
pack inspect-image samples/app --bom | jq '.local[] | select(.name=="jre") | .metadata.version'Copied!
The following environment variable configures the JVM version at build-time.
BP_JVM_VERSION
BP_JVM_VERSION=8 or BP_JVM_VERSION=8.* the buildpack will install the latest patch releases of the Java 8 JDK and JRE.The Java Buildpack configures the JVM by setting JAVA_TOOL_OPTIONS in the JVM environment.
The Java Buildpack installs a component called the Memory Calculator which will configure JVM memory based on the resources available to the container at runtime. The calculated flags will be appended to JAVA_TOOL_OPTIONS.
The runtime JVM can be configured in two ways:
JAVA_TOOL_OPTIONS flags. Examples include:
BPL_JVM_HEAD_ROOMBPL_JVM_LOADED_CLASS_COUNTBPL_JVM_THREAD_COUNTJAVA_TOOL_OPTIONS environment variable. User-provided flags will be appended to buildpack-provided flags. If the user and a buildpack set the same flag, user-provided flags take precedence.See the homepage for the Bellsoft Liberica Buildpack for a full set of configuration options.
If the application uses Spring Boot the Spring Boot Buildpack will enhance the resulting image by adding additional metadata to the image config, applying Boot-specific performance optimizations, and enabling runtime auto-configuration.
The Spring Boot Buildpack adds the following additional image labels:
org.opencontainers.image.title - set to the value of Implementation-Title from MANIFEST.MF.org.opencontainers.image.version - set to the values of Implementation-Version from MANIFEST.MF.org.springframework.boot.version - set to the value of Spring-Boot-Version from MANIFEST.MF.org.springframework.cloud.dataflow.spring-configuration-metadata.json - containing configuration metadata.org.springframework.cloud.dataflow.spring-configuration-metadata.json - containing dataflow-configuration-metadata.properties, if present.In addition, the buildpack will add an entry with name dependencies to the Bill-of-Materials listing the application dependencies.
Example: Inspecting Application Dependencies
The following command uses pack to list every dependency of a sample application.
pack inspect-image samples/java --bom | jq '.local[] | select(.name=="dependencies") | .metadata.dependencies[].name'Copied!
The Spring Boot Buildpack adds Spring Cloud Bindings to the application class path. Spring Cloud Bindings will auto-configure the application to connect to an external service when a binding of a supported type provides credentials and connection information at runtime. Runtime auto-configuration is enabled by default but can be disabled with the BPL_SPRING_CLOUD_BINDINGS_ENABLED environment variable.
The Spring Boot Buildpack can apply domain-specific knowledge to optimize the performance of Spring Boot applications. For example, if the buildpack detects that the application is a reactive web application the thread count will be reduced to 50 from a default of 250.
The Java Buildpack supports the following APM integrations:
APM integration are enabled with bindings. If a binding of the correct type is provided at build-time the corresponding java agent will be contributed to the application image. Connection credentials will be read from the binding at runtime.
Example: Connecting to Azure Application Insights
The following command builds an image with the Azure Application Insights Java Agent
pack build samples/java --volume "$(pwd)/java/application-insights/binding:/platform/bindings/application-insights"Copied!
To connect to Azure Applicaiton Insights at runtime a valid Instrumentation Key is required.
echo "<Instrumentation Key>" > java/application-insights/binding/InstrumentationKey docker run --rm --tty \ --env SERVICE_BINDING_ROOT=/bindings \ --volume "$(pwd)/java/application-insights/binding:/bindings/app-insights" \ samples/javaCopied!
If BP_DEBUG_ENABLED is set at build-time and BPL_DEBUG_ENABLED is set at runtime the Debug Buildpack will configure the application to accept debugger connections. The debug port defaults to 8000 and can be configured with BPL_DEBUG_PORT at runtime. If BPL_DEBUG_SUSPEND is set at runtime, the JVM will suspend execution until a debugger has attached.
Example: Remote Debugging
The following commands builds a debug-enabled image.
pack build samples/java \ --path java/jar \ --env BP_DEBUG_ENABLED=trueCopied!
To run the image with the debug port published:
docker run --env BPL_DEBUG_ENABLED=true --publish 8000:8000 samples/javaCopied!
Connect your IDE debugger to connect to the published port.
If BP_JMX_ENABLED is set at build-time and BPL_JMX_ENABLED is set at runtime, the JMX Buildpack will enable JMX. The JMX connector will listen on port 5000 by default. The port can be configured with the BPL_JMX_PORT environment variable at runtime.
Example: Enabling JMX
The following commands builds a JMX enabled image.
pack build samples/java \ --path java/jar \ --env BP_JMX_ENABLED=trueCopied!
To run the image with the JMX port published:
docker run --env BPL_JMX_ENABLED=true --publish 5000:5000 samples/javaCopied!
Connect JConsole to the published port.
The Java buildpack will contribute a default process type that starts the application.
Example: Running the default process
Execute the following commands to start the default process type using a samples/java image built from any previous example command.
docker run --rm --publish 8080:8080 samples/java curl -s http://localhost:8080/actuator/healthCopied!
Additional arguments can be provided to the application using the container CMD. In Kubernetes set CMD using the args field on the container resource.
Example: Setting the Server Port
Execute the following command passes an additional argument to application start command, setting the port to 8081.
docker run --rm --publish 8081:8081 samples/java --server.port=8081 curl -s http://localhost:8081/actuator/healthCopied!
To override the buildpack-provided start command with a custom command, set the container ENTRYPOINT
Example: Starting an Interactive Shell
The following command runs Bash interactively:
docker run --rm --entrypoint bash samples/javaCopied!
Every buildpack-generated image contains an executable called the launcher which can be used to execute a custom command in an environment containing buildpack-provided environment variables. The launcher will execute any buildpack provided profile scripts before running to provided command, in order to set environment variables with values that should be calculated dynamically at runtime.
To run a custom start command in the buildpack-provided environment set the ENTRYPOINT to launcher and provide the command using the container CMD.
Example: Inspecting the Buildpack-Provided JAVA_TOOL_OPTIONS
The following command will print value of $JAVA_TOOL_OPTIONS set by the buildpack:
docker run --rm --entrypoint launcher samples/java echo 'JAVA_TOOL_OPTIONS: $JAVA_TOOL_OPTIONS'Copied!
Each argument provided to the launcher will be evaluated by the shell prior to execution and the original tokenization will be preserved. Note that, in the example above 'JAVA_TOOL_OPTIONS: $JAVA_TOOL_OPTIONS' is single quoted so that $JAVA_TOOL_OPTIONS is evaluated in the container, rather than by the host shell.
The following component buildpacks compose the Java Buildpack. Buildpacks are listed in the order they are executed.
| Buildpack | Required/Optional | Responsibility |
|---|---|---|
| Paketo CA Certificates Buildpack | Optional | Adds CA certificates to the system truststore at build and runtime. |
| Paketo BellSoft Liberica Buildpack | Required | Provides the JDK and/or JRE. |
| Paketo Gradle Buildpack | Optional | Builds Gradle-based applications from source. |
| Paketo Leiningen Buildpack | Optional | Builds Leiningen-based applications from source. |
| Paketo Maven Buildpack | Optional | Builds Maven-based applications from source. |
| Paketo SBT Buildpack | Optional | Builds SBT-based applications from source. |
| Paketo Executable JAR Buildpack | Optional | Contributes a process Type that launches an executable JAR. |
| Paketo Apache Tomcat Buildpack | Optional | Contributes Apache Tomcat and a process type that launches a WAR with Tomcat. |
| Paketo DistZip Buildpack | Optional | Contributes a process type that launches a DistZip-style application. |
| Paketo Spring Boot Buildpack | Optional | Contributes configuration and metadata to Spring Boot applications. |
| Paketo Procfile Buildpack | Optional | Allows the application to define or redefine process types with a Procfile |
| Paketo Azure Application Insights Buildpack | Optional | Contributes the Application Insights Agent and configures it to connect to the service. |
| Paketo Debug Buildpack | Optional | Configures debugging for JVM applications. |
| Paketo Google Stackdriver Buildpack | Optional | Contributes Stackdriver agents and configures them to connect to the service. |
| Paketo JMX Buildpack | Optional | Configures JMX for JVM applications. |
| Paketo Encrypt At Rest Buildpack | Optional | Encrypts an application layer and contributes a profile script that decrypts it at launch time. |
| Paketo Environment Variables Buildpack | Optional | Contributes arbitrary user-provided environment variables to the image. |
| Paketo Image Labels Buildpack | Optional | Contributes OCI-specific and arbitrary user-provided labels to the image. |
Last modified: April 8, 2021
Paketo Buildpacks is a Cloud Foundry Project