Java

Info

This documentation is adapted for Miget purposes and is based on information from the Paketo Java Buildpack documentation.

This documentation explains how to use the Paketo buildpacks with Miget to build Java applications for several common use-cases. For more in-depth description of the buildpacks’ behavior and configuration see the Paketo Java Buildpack and Paketo Java Native Image Buildpack reference documentation.

If your intention is to deploy an app using a Dockerfile, please refer to the Dockerfile page for guidance and best practices.

Prerequisites

The pack CLI is used throughout the examples.

Examples assume that the Paketo Base builder is the default builder:

$ pack config default-builder paketobuildpacks/builder-jammy-base

Example App

Info

A demo instance of this app is hosted at java.onmiget.com.

Build

$ git clone git@github.com:migetapp/java-hello-world.git
$ cd java-hello-world
$ pack build java-hello-world

Run

$ docker run -p 5000:5000 java-hello-world

The example app should now be running on localhost:5000.

Build an App as a Traditional Java WAR or JAR

Building from Source

The Java Buildpack can compile your application from source using any of the following build tools:

Gradle - Support is provided by the Gradle Buildpack.
Leiningen - Support is provided by the Leiningen Buildpack.
Maven - Support is provided by the Maven Buildpack.
SBT - Support is provided by the SBT Buildpack.

The appropriate build tool will be automatically detected based on the contents of your application directory.

The build process should produce one of the supported artifact formats. After the build, the buildpack will replace the provided application source code with the exploded archive.

Configure the Build Tool

Info

If you wish to change Miget's Java Builder settings, apply the envronment variables in your Application Settings -> Config Vars.

Select a Module or Artifact

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
- Defaults to the root module.
- Configures the module in a multi-module build from which the buildpack will select the application artifact.
- Example: Given 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
- Defaults to a tool-specific pattern (e.g. target/*.[jw]ar for Maven, build/libs/*.[jw]ar for gradle). See component buildpack homepage for details.
- Configures the built application artifact path, using Bash Pattern Matching(opens in a new tab).
- Supersedes BP_<TOOL>_BUILT_MODULE if set to a non-default value.
- Example: Given BP_MAVEN_BUILT_ARTIFACT=out/api-*.jar, the Paketo Maven Buildpack will select a file with name out/api-1.0.0.jar.

Specify the Build Command

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_
_BUILD_ARGUMENTS
- Defaults to a tool-specific value (e.g. -Dmaven.test.skip=true package for Maven, --no-daemon assemble for Gradle). See component buildpack homepage for details.
- Configures the arguments to pass to the build tool.
- Example: Given BP_GRADLE_BUILD_ARGUMENTS=war, the Paketo Gradle Buildpack will execute ./gradlew war or gradle war (depending on the presence of the gradle wrapper).

Additionally, for MAVEN, we support two other environment variables at build-time:

BP_MAVEN_ADDITIONAL_BUILD_ARGUMENTS
- Configures additional arguments to pass to the maven build tool; it defaults to empty string and can be handy when you want to keep the default BP_MAVEN_BUILD_ARGUMENTS but just need one additional argument.
- Example: Given BP_MAVEN_ADDITIONAL_BUILD_ARGUMENTS=-DskipTool, you could disable a plugin, without changing BP_MAVEN_BUILD_ARGUMENTS.
BP_MAVEN_ACTIVE_PROFILES
- Configures active profiles to pass to the maven build tool; it defaults to empty string and can be handy when you want to keep the default BP_MAVEN_BUILD_ARGUMENTS but just need several profiles (de)activated.
- Example: Given BP_MAVEN_ACTIVE_PROFILES=p1,!p2,?p3, you could activate the p1 profile, deactivate the p2 profile, and optionally activate the p3 profile, without changing BP_MAVEN_BUILD_ARGUMENTS.

And similarly, for GRADLE, we support one other environment variable at build-time:

BP_GRADLE_ADDITIONAL_BUILD_ARGUMENTS
- Configures additional arguments to pass to the gradle build tool; it defaults to empty string and can be handy when you want to keep the default BP_GRADLE_BUILD_ARGUMENTS but just need one additional argument.
- Example: Given BP_GRADLE_ADDITIONAL_BUILD_ARGUMENTS=--no-build-cache, you could disable build cache without changing BP_GRADLE_BUILD_ARGUMENTS.

Include or Exclude Custom Files

When building your application from source code, the Java buildpacks will capture the output artifact from your build process, typically a JAR/WAR file, and include that in the image that is generated. If you need to include/exclude additional files you may do so by setting the BP_INCLUDE_FILES or BP_EXCLUDE_FILES environment variables. Each can be set with a colon separated list of glob patterns. If a file or directory matches then it’ll be included or excluded. If both include and exclude patterns are specified then the include patterns are applied first, followed by the exclude patterns second. By default, no additional files are included or excluded.

Any files added to the image through this process are rooted at the application directory, which is /workspace in the generated image. Files will reside under the same sub directories there as under the application source code root. If you have files under src/main/resources/foo and you use an include pattern of src/main/resources/foo/* then those files will be in the image at /workspace/src/main/resources/foo. There is not presently any way to transform the file locations, so if you require files at a specific location in the generated image you will need to use the same sub directory structure in your application source code.

Note

It is important to properly quote values for BP_INCLUDE_FILES and BP_EXCLUDE_FILES as they may contain wild card characters like * which the shell may interpret. Proper quoting ensures the actual characters are passed through to the buildpack.

Enable Maven or Gradle to build Javascript assets with Node/Yarn

Build tools such as Maven & Gradle can configure plugins & tasks that build Javascript assets for the frontend part of an app. The Java Buildpack can now install the node and yarn binaries for build tools to use in such tasks.

When building from source with the Maven or Gradle buildpacks, you can enable installation of Node and/or Yarn using the following environment variable:

BP_JAVA_INSTALL_NODE - set to true to enable, defaults to false.

When this is set to true, the buildpack will check for the following files:

yarn.lock - both Yarn and Node will be installed via the Yarn Buildpack & Node Engine Buildpack
package.json - only Node will be installed via the Node Engine Buildpack

By default, the above files are expected to be in the application root directory. You can configure a specific sub-directory for these files using the environment variable supported by the node-engine buildpack:

BP_NODE_PROJECT_PATH - see nodejs - Build an App from Source

Sample Maven Plugin configuration (pom.xml):

<plugin>
<groupId>org.codehaus.mojo</groupId>
<artifactId>exec-maven-plugin</artifactId>
<version>${exec-maven.version}</version>
  <executions>
      <execution>
      <id>exec-yarn-install</id>
      <phase>generate-sources</phase>
          <goals>
              <goal>exec</goal>
          </goals>
          <configuration>
              <executable>yarn</executable>
              <arguments>
                  <argument>install</argument>
              </arguments>
          </configuration>
      </execution>
  </executions>
</plugin>

Environment Variable set under Settings -> Config Vars:

BP_JAVA_INSTALL_NODE=true

Building from a Compiled Artifact

An application developer may build an image from following archive formats:

Executable JAR - Support provided by the Executable Jar Buildpack
WAR - Support provided by the Apache Tomcat Buildpack
Distribution ZIP - Support provided by the DistZip Buildpack 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.

Install a Specific JVM Version

The following environment variable configures the JVM version at build-time.

BP_JVM_VERSION
- Defaults to the latest 17.x version at the time of release.
- Configures a specific JDK or JRE version (specify only the major version).
- Example: Given BP_JVM_VERSION=8 or BP_JVM_VERSION=8.* the buildpack will install the latest patch releases of the Java 8 JDK and JRE.

JVM Default Version

The Java buildpack’s default version will change periodically. The Paketo buildpack will change the default version of Java once the most recently released LTS version of Java is at least one year old. For example, Java 21 was released in September 2023. It was added to the Paketo buildpacks immediately, but will not become the default until September 2024.

Exceptions are permitted for a shorter change cycle when deemed sufficiently urgent by a majority vote of Java sub-team contributors and maintainers.

When the default version of Java changes, the team will bump the major version of the Java buildpack and include details of the change in the release notes. In addition, the team will write a blog post and update our Slack channels prior to the change to alert community members of the upcoming change.

Install a Specific JVM Type

The following environment variable configures whether a JDK or a JRE is installed at runtime.

BP_JVM_TYPE
- Defaults to JRE - a JDK will be used at build-time and a JRE will be used at runtime. If no JRE dependency is found, a JDK will be installed for use as the JRE.
- If JDK is specified, the buildpack will attempt to install a JDK for use at runtime. The security implications of using a JDK at runtime should be considered.

Install a Minimal JRE with JLink

JLink is a tool included with the JDK that allows for the generation of a customized JRE. This is supported for Java versions 9 and above, where the Java Module system is available. To run the JLink tool and install a minimal JRE for runtime, simply use the following environment variable:

BP_JVM_JLINK_ENABLED - this defaults to false, set to true to enable JLink. This will run JLink with the following default arguments:
--no-man-pages - this excludes man pages from the generated JRE
--no-header-files - this excludes header files from the generated JRE
--strip-debug - this strips debug information from the generated JRE
--compress=1 - this enables “Constant string sharing” level compression

The JRE generated by default will include only Java modules prefixed with java.*. If you wish to fully customize all arguments passed to JLink including which modules should be added to the generated JRE, you can use the following environment variable:

BP_JVM_JLINK_ARGS - not set by default - if any value(s) are specified here, none of the defaults listed above will be set. The variable should contain the arguments you wish to pass to the JLink tool, including the list of required modules with the argument --add-modules <comma-separated-list>.

Example generating a minimal JRE via JLink, with custom arguments

Environment Variable set under Settings -> Config Vars:

BP_JVM_JLINK_ENABLED=true
BP_JVM_JLINK_ARGS="--no-header-files --compress=1 --add-modules java.base,java.se"

Configure the JVM at Runtime

The Java Buildpack configures the JVM by setting JAVA_TOOL_OPTIONS in the JVM environment.

The runtime JVM can be configured in two ways:

Buildpack-provided runtime components including the Memory Calculator accept semantically named environment variables(opens in a new tab) which are then used to derive JAVA_TOOL_OPTIONS flags. Examples include:
BPL_JVM_HEAD_ROOM
BPL_JVM_LOADED_CLASS_COUNT
BPL_JVM_THREAD_COUNT
BPL_JVM_CLASS_ADJUSTMENT
Flags can be set directly at runtime with the JAVA_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.

Info

By default, the Paketo Java buildpack (used by Miget) is using the Liberica JVM.

Use an Alternative JVM

Info

Miget currently doesn't support any of the alternate JVM implementations available as Paketo JVM buildpacks. We are working on it.

Use an Alternative Java Application Server

When deploying your Java application to an application server, the default application server installed by the Paketo Java buildpack is Apache Tomcat. If you require a different application server, possibly one that supports JavaEE or JakartaEE, you may select an alternative Java application server by setting BP_JAVA_APP_SERVER when building your application.

BP_JAVA_APP_SERVER=tomcat - will switch to using Apache Tomcat
BP_JAVA_APP_SERVER=tomee - will switch to using Apache Tomee
BP_JAVA_APP_SERVER=liberty - will switch to using Open Liberty

Build a Spring Boot Application

Disable Spring Boot Auto-Configuration

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_DISABLED=true environment variable at runtime or the BP_SPRING_CLOUD_BINDINGS_DISABLED=true environment variable at build time.

Enable Process Reloading

Warning

This isn't currently available at Miget. We are working on it.

Enable `DEBUG` logging

Users of the Java buildpack can access extra debug logs during the image build process by setting the BP_LOG_LEVEL environment variable to DEBUG at build time. Additional debug logs will appear in build logs if the relevant buildpacks have debug log lines.

Environment Variable set under Settings -> Config Vars: BP_LOG_LEVEL=DEBUG

Enable Remote Debugging

Warning

This isn't currently available at Miget. We are working on it.

Enable JMX

Warning

This isn't currently available at Miget. We are working on it.

Enable Java Native Memory Tracking (NMT)

By default for Java 11+, the JVM will be configured to track internal memory usage. The JVM will print its last memory usage data when it exits, the level of detail can be configured at runtime by setting the environment variable BPL_JAVA_NMT_LEVEL, which supports both summary (default) and detail. Since there is a small amount of overhead required to support NMT, it can be disabled by setting the environment variable BPL_JAVA_NMT_ENABLED=false.

Enable Java Flight Recorder (JFR)

If BPL_JFR_ENABLED is set to true at runtime, Java Flight Recording features will be enabled by the JVM. To configure JFR via its supported arguments, add them to the optional environment variable BPL_JFR_ARGS at runtime.

Two default arguments are configured for JFR as follows:

dumponexit - this is set to true to write the recording data to a file when the JVM exits
filename - this is set to <system-temp-dir>/recording.jfr (i.e. /tmp/recording.jfr) and is the location where the recording data will be written on JVM exit

If any args are provided via BPL_JFR_ARGS, these defaults will not be configured.

Java

Prerequisites

Example App

Build

Run

Build an App as a Traditional Java WAR or JAR

Building from Source

Configure the Build Tool

Select a Module or Artifact

Specify the Build Command

Include or Exclude Custom Files

Enable Maven or Gradle to build Javascript assets with Node/Yarn

Building from a Compiled Artifact

Install a Specific JVM Version

JVM Default Version

Install a Specific JVM Type

Install a Minimal JRE with JLink

Example generating a minimal JRE via JLink, with custom arguments

Configure the JVM at Runtime

Use an Alternative JVM

Use an Alternative Java Application Server

Build a Spring Boot Application

Disable Spring Boot Auto-Configuration

Enable Process Reloading

Enable DEBUG logging

Enable Remote Debugging

Enable JMX

Enable Java Native Memory Tracking (NMT)

Enable Java Flight Recorder (JFR)

Enable `DEBUG` logging