Using Cloud Foundry Java buildpack

You can use the Java buildpack with Cloud Foundry.

You can deploy a number of different JVM-based artifact types. For a more detailed explanation of what the Cloud Foundry Java Builpack supports, see Additional Documentation in the repository on GitHub.

Java buildpack

For information about using, configuring, and extending the Cloud Foundry Java buildpack, see the Cloud Foundry Java Buildpack repository on GitHub.

Java buildpack design

The Java buildpack can convert artifacts that run on the JVM into executable apps. It does this by identifying one of the supported artifact types (Grails, Groovy, Java, Play Framework, Spring Boot, and Servlet) and downloading all additional dependencies needed to run. It also analyzes the collection of services bound to the app and downloads any dependencies related to those services.

For example, pushing a WAR file that is bound to a PostgreSQL database and New Relic for performance monitoring shows output like this:

-----> Java Buildpack v4.50 | https://github.com/cloudfoundry/java-buildpack#e1d6dbc
-----> Downloading Jvmkill Agent 1.16.0_RELEASE from https://java-buildpack.cloudfoundry.org/jvmkill/bionic/x86_64/jvmkill-1.16.0-RELEASE.so (0.1s)
-----> Downloading Open Jdk JRE 1.8.0_342 from https://java-buildpack.cloudfoundry.org/openjdk/bionic/x86_64/bellsoft-jre8u342%2B7-linux-amd64.tar.gz (0.6s)
Expanding Open Jdk JRE to .java-buildpack/open_jdk_jre (1.3s)
JVM DNS caching deactivated in lieu of BOSH DNS caching
-----> Downloading Open JDK Like Memory Calculator 3.13.0_RELEASE from https://java-buildpack.cloudfoundry.org/memory-calculator/bionic/x86_64/memory-calculator-3.13.0-RELEASE.tar.gz (0.1s)
Loaded Classes: 21014, Threads: 250
-----> Downloading Client Certificate Mapper 1.11.0_RELEASE from https://java-buildpack.cloudfoundry.org/client-certificate-mapper/client-certificate-mapper-1.11.0-RELEASE.jar (0.0s)
-----> Downloading Container Security Provider 1.19.0_RELEASE from https://java-buildpack.cloudfoundry.org/container-security-provider/container-security-provider-1.19.0-RELEASE.jar (0.1s)
Exit status 0

Configuration

In most cases, the buildpack can work without any configuration. If you are new to Cloud Foundry, VMware recommends that you make your first attempts without modifying the buildpack configuration. The buildpack is flexible, though, and you can configure it through environment variables. For more information, see Configuration and Extension in the Cloud Foundry Java Buildpack repository on GitHub.

Java Client Library

The Cloud Foundry Client Library provides a Java API for interacting with an instance. This library, cloudfoundry-client, can be used by Java based tools to interact with the platform.

For information about using this library, see Java Cloud Foundry Library.

Grails

Grails packages apps into WAR files for deployment into a Servlet container. To build the WAR file and deploy it, run:

grails prod war
cf push YOUR-APP -p target/YOUR-APP-VERSION.war

Where:

YOUR-APP is the name of your app.
YOUR-APP-VERSION is the name of the WAR file you want to build and deploy.

Groovy

TAS for VMs supports Groovy apps based on both Ratpack and a simple collection of files.

Ratpack

Ratpack packages apps into two different styles. TAS for VMs supports the distZip style. To build the ZIP file and deploy it, run:

gradle distZip
cf push YOUR-APP -p build/distributions/YOUR-ZIP-FILE.zip

Where:

YOUR-APP is the name of your app.
YOUR-ZIP-FILE is the name of the ZIP file you want to build and deploy.

For more information, see the Ratpack website.

Raw Groovy

You can run Groovy apps that are made up of a single entry point and any supporting files without any other work. To deploy them, run:

cf push YOUR-APP

Where YOUR-APP is the name of your app.

For more information, see Groovy Container in the Cloud Foundry Java Buildpack repository on GitHub.

HTTP/2

To deploy Java apps that use HTTP/2, you must have:

A Cloud Floundry foundation that has HTTP/2 support enabled. For information about configuring support for HTTP/2 in TAS for VMs, see Configuring HTTP/2 Support.
Cloud Foundry Command-Line Interface (cf CLI) v8 or later. See Upgrading to cf CLI v8.

You can deploy any Java app and get automatic support for the HTTP/2 protocol without making any changes to your app. When a client connects through a route mapped to your Java apps over HTTP/2, the foundation transparently downgrades the protocol and communicates with your app over HTTP/1.1.

If you require end-to-end HTTP/2, for example, because of gRPC, do the following:

Enable HTTP/2 support in the app:
- See Configure HTTP/2 in the Spring Boot documentation.
- If you are deploying a standard non-executable WAR file, you only need to make sure that you are using Java buildpack v4.43 or later. Starting with v4.43, the Java buildpack configures Apache Tomcat to accept HTTP/2 connections.
- Other frameworks, including Play, Ratpack, and apps that use the distZip format, embed an HTTP server. You must configure these apps to enable HTTP/2, specifically H2C, clear-text. See your framework’s documentation for enabling HTTP/2 and H2C. H2C is required because TAS for VMs uses Envoy to secure communications into the app container.
Configure the route to use the HTTP/2 protocol using either the cf CLI or the app manifest:
- Using the cf CLI: cf map-route MY-APP EXAMPLE.COM --hostname host --destination-protocol http2.
- Using a manifest.yml file:
```
---
applications:
- name: MY-APP
  routes:
    - route: MY-APP.EXAMPLE.COM
      protocol: http2
```

HTTP/2 example

For example:

Fetch the Spring Music app:

git clone https://github.com/cloudfoundry-samples/spring-music.git

Build the app:
```
./gradle assemble
```
Push the app without assigning a route:
```
cf push --no-route
```

Map a route:

cf map-route spring-music EXAMPLE.COM --hostname spring-music --destination-protocol http2

Validate:

curl https://spring-music.EXAMPLE.COM/request --http2 -s | jq .

A successful response looks like the following:

{
  "protocol": "HTTP/2.0",
  "remote-addr": "198.51.100.100",
  "method": "GET",
  "scheme": "https",
  "session-id": "1A891C614AB6B6CB59A56D7F520BBCBD"
}

Java main

Java apps with a main() method can be run provided that they are packaged as self-executable JARs. For more information, see Java Main Container in the Cloud Foundry Java Buildpack repository on GitHub.

If your app is not web enabled, you must suppress route creation to avoid a failed to start accepting connections error. To suppress route creation, add no-route: true to the app manifest or use the –no-route flag with the cf push command.

For more information about the no-route attribute, see Deploying with App Manifests.

Maven

A Maven build can create a self-executable JAR. To build and deploy the JAR, run:

mvn package
cf push YOUR-APP -p target/YOUR-APP-VERSION.jar

Where:

YOUR-APP is the name of your app.
YOUR-APP-VERSION is the name of the JAR you want to build and deploy.

Gradle

A Gradle build can create a self-executable JAR. To build and deploy the JAR, run:

gradle build
cf push YOUR-APP -p build/libs/YOUR-APP-VERSION.jar

Where:

YOUR-APP is the name of your app.
YOUR-APP-VERSION is the name of the JAR you want to build and deploy.

Play Framework

The Play Framework packages apps into two different styles. TAS for VMs supports both the staged and dist styles. To build the dist style and deploy it, run:

play dist
cf push YOUR-APP -p target/universal/YOUR-APP-VERSION.zip

Where:

YOUR-APP is the name of your app.
YOUR-APP-VERSION is the name of the dist style ZIP you want to build and deploy.

For more information, see the Play Framework website.

Spring Boot CLI

Spring Boot can run apps comprised entirely of POGOs. To deploy them, run:

spring grab *.groovy
cf push YOUR-APP

Where YOUR-APP is the name of your app.

For more information, see Spring Boot on the Spring website and Spring Boot CLI Container in the Cloud Foundry Java Buildpack repository on GitHub.

Servlet

Java apps can be packaged as Servlet apps.

Maven

A Maven build can create a Servlet WAR. To build and deploy the WAR, run:

mvn package
cf push YOUR-APP -p target/YOUR-APP-VERSION.war

Where:

YOUR-APP is the name of your app.
YOUR-APP-VERSION is the name of the WAR you want to build and deploy.

Gradle

A Gradle build can create a Servlet WAR. To build and deploy the WAR, run:

gradle build
cf push YOUR-APP -p build/libs/YOUR-APP-VERSION.war

Where:

YOUR-APP is the name of your app.
YOUR-APP-VERSION is the name of the WAR you want to build and deploy.

Binding to services

For more information about binding apps to services, see Configuring Service Connections.

Java and Grails best practices

Provide a JDBC driver

The Java buildpack does not bundle a JDBC driver with your app. If you want your app to access a SQL RDBMS, include the appropriate driver in your app.

Allocate sufficient memory

If you do not allocate sufficient memory to a Java app when you deploy it, it may fail to start, or TAS for VMs may terminate it. You must allocate enough memory to allow for:

Java heap
Metaspace
Stack size per Thread
JVM overhead

The config/open_jdk_jre.yml file of the Java buildpack contains default memory size and weighting settings for the JRE. For an explanation of JRE memory sizes and weightings and how the Java buildpack calculates and allocates memory to the JRE for your app, see Open JDK JRE in the Cloud Foundry Java Buildpack on GitHub.

To configure memory-related JRE options for your app, you can override the default memory settings of your buildpack as described in Configuration and Extension with the properties listed in the Open JDK JRE README in the Cloud Foundry Java Buildpack on GitHub. For more information about configuring manifests, see Deploying with App Manifests.

To see memory utilization when your app is running, run:

cf app YOUR-APP

Where YOUR-APP is the name of your app.

Troubleshoot out of memory

A Java app may crash because of insufficient memory on the Garden container or the JVM on which it runs. The sections below provide guidance for help diagnosing and resolving such issues.

JVM

Error: java.lang.OutOfMemoryError. For example:

$ cf logs YOUR-APP --recent
2016-06-20T09:18:51.00+0100 [APP/0] OUT java.lang.OutOfMemoryError: Metaspace

Where `YOUR-APP` is the name of your app.

Cause: If the JVM cannot garbage-collect enough space to ensure the allocation of a data-structure, it fails with java.lang.OutOfMemoryError. In the example above, JVM has an under-sized metaspace. You may see failures in other memory pools, such as heap.
Solution: Configure the JVM correctly for your app. For more information, see Allocate Sufficient Memory.

Garden container

The solutions in this section require configuring the memory calculator, which is a sub project of the Java buildpack that calculates suitable memory settings for Java apps when you push them. For more information, see the java-buildpack-memory-calculator repository on GitHub. If you have questions about the memory calculator, you can ask them in the #java-buildpack channel of the Cloud Foundry Slack organization.

Error: The Garden container terminates the Java process with the out of memory event. For example:
```
$ cf events YOUR-APP
time                          event         actor         description
2016-06-20T09:18:51.00+0100   app.crash     app-name      index: 0, reason: CRASHED, exit_description: out of memory, exit_status: 255
```
Where YOUR-APP is the name of your app.

This error appears when the JVM allocates more OS-level memory than the quota requested by the app, such as through the manifest.
Cause 1 - Insufficient native memory: This error commonly means that the JVM requires more native memory. In the scope of the Java buildpack and the memory calculator, the term “native” means the memory required for the JVM to work, along with forms of memory not covered in the other classifications of the memory calculator. This includes the memory footprint of OS-level threads, program counters, when an app forks and runs subprocesses, or when an app uses JNI to allocate memory.
Solution 1: Determine how much native memory a Java app needs by measuring it with realistic workloads and fine-tuning it accordingly. You can then configure the Java buildpack using the native setting of the memory calculator, as in the example below:
```
---
applications:
- name: YOUR-APP
  memory: 1G
  env:
    JBP_CONFIG_OPEN_JDK_JRE: '[memory_calculator: {headroom: 10}}]'
```
Where YOUR-APP is the name of your app.

This example shows that 10% of the overall available 1G is reserved for anything that is not heap, metaspace, direct, code cache or threads. In less common cases, this may come from companion processes started by the JVM, such as the Process API.

For more information about measuring how much native memory a Java app needs, see Native Memory Tracking in the Java documentation. For more information about configuring the Java buildpack using the native setting, see OpenJDK JRE in the Cloud Foundry Java Buildpack on GitHub. For more information about the Process API, see Class Process in the Java documentation.
Cause 2 - High thread count: Java threads in the JVM can cause memory errors at the Garden level. When an app is under heavy load, it uses a high number of threads. Each thread consumes some memory, and, if there are enough threads, they consume a significant amount of memory.
Solution 2: Set the reserved memory for stack traces to the correct value for your app.

You can use the -Xss setting of the JVM to configure the amount of space the JVM reserves for each Java thread. You must multiply this value by the number of threads your app requires. Specify the number of threads in the stack_threads setting of the memory calculator. For example, if you estimate the max thread count for an app at 800 and the amount of memory needed to represent the deepest stacktrace of a Java thread is 512KB, configure the memory calculator as follows:
```
---
applications:
- name: YOUR-APP
  memory: 1G
  env:
    JBP_CONFIG_OPEN_JDK_JRE: '[memory_calculator: {stack_threads: 800}]'
    JAVA_OPTS: '-Xss512k'
```
Where YOUR-APP is the name of your app.

In this example, the overall memory amount reserved by the JVM for representing the stacks of Java threads is 800 * 512k = 400m.

The correct settings for -Xss and stack_threads depend on your app code, including the libraries it uses. Your app may technically have no upper limit, such as in the case of cavalier usage of CachedThreadPool executors. However, you still must calculate the depth of the thread stacks, and the amount of space the JVM reserves for each of them. For more information, see Executors.newCachedThreadPool() considered harmful on the Bizo website and the newCachedThreadPool section of the Class Executors topic in the Java documentation.

Troubleshoot failed upload

If your app fails to upload when you push it to TAS for VMs, it may be for one of the following reasons:

WAR is too large: An upload may fail due to the size of the WAR file. TAS for VMs testing indicates WAR files as large as 250 MB upload successfully. If a WAR file larger than that fails to upload, it may be a result of the file size.
Connection issues: App uploads can fail if you have a slow Internet connection, or if you upload from a location that is very remote from the target TAS for VMs instance. If an app upload takes a long time, your authorization token can expire before the upload completes. A workaround is to copy the WAR to a server that is closer to the TAS for VMs instance, and then push it from there.
Out-of-date cf CLI client: Upload of a large WAR is faster and therefore less likely to fail if you are using a recent version of the cf CLI. If you are using an older version of the cf CLI client to upload a large WAR, and having problems, try updating to the latest version of the cf CLI.
Incorrect WAR targeting: By default, cf push uploads everything in the current directory. For a Java app, cf push with no option flags uploads source code and other unnecessary files, in addition to the WAR. When you push a Java app, specify the path to the WAR by running:
```
cf push YOUR-APP -p PATH/TO/WAR-FILE
```
Where:
- YOUR-APP is the name of your app.
- PATH/TO/WAR-FILE is the path to the WAR. You can determine whether or not the path was specified for a previously pushed app by examining the app deployment manifest, manifest.yml. If the path attribute specifies the current directory, the manifest includes a line like:
```
path: .
```
  To re-push just the WAR, do one of the following:
  - Delete manifest.yml and run cf push again, specifying the location of the WAR using the -p flag.
  - Edit the path argument in manifest.yml to point to the WAR, and re-push the app.

Debuging Java apps

Because of the way TAS for VMs deploys your apps and isolates them, it is not possible to connect to your app with the remote Java debugger. Instead, instruct the app to connect to the Java debugger on your local machine.

To set up remote debugging when using BOSH Lite or a TAS for VMs installation:

Open your project in Eclipse.
Right-click your project, go to Debug as and pick Debug Configurations.
Create a new Remote Java Application.
Make sure your project is selected, pick Standard (Socket Listen) from the Connection Type drop down and set a port. Make sure this port is open if you are running a firewall.
Click Debug.

The debugger is running. If you switch to the Debug perspective, you see your app listed in the Debug panel, and it says Waiting for vm to connect at port.

Next, to push your app to TAS for VMs and instruct TAS for VMs to connect to the debugger running on your local machine:

Edit your manifest.yml file. Set the instances count to 1. If you set this greater than one, multiple apps try to connect to your debugger.
Also in manifest.yml, add an env block and create a variable named JAVA_OPTS. For more information about the env block, see Deploying with App Manifests.
Add the remote debugger configuration to the JAVA_OPTS variable: -agentlib:jdwp=transport=dt_socket,address=YOUR-IP-ADDRESS:YOUR-PORT.
Save the manifest.yml file.
Run:
```
cf push
```

Upon completion, you can see that your app has started and is now connected to the debugger running in your IDE. You can now add breakpoints and interrogate the app just as you would if it were running locally.

Slow starting Java or Grails apps

Some Java and Grails apps do not start quickly, and the health check for an app can fail if an app starts too slowly.

The current Java buildpack implementation sets the Tomcat bindOnInit property to false. This prevents Tomcat from listening for HTTP requests until an app has fully deployed.

If your app does not start quickly, the health check might fail because it checks the health of the app before the app can accept requests. By default, the health check fails after a timeout threshold of 60 seconds.

To resolve this issue, run cf push with the -t TIMEOUT-THRESHOLD option to increase the timeout threshold. Run:

$ cf push YOUR-APP -t TIMEOUT-THRESHOLD

$ cf push YOUR-APP --app-start-timeout TIMEOUT-THRESHOLD

Where:

YOUR-APP is the name of your app.
TIMEOUT-THRESHOLD is the number of seconds to which you want to increase the timeout threshold.

The timeout threshold cannot exceed 180 seconds. Specifying a timeout threshold greater than 180 seconds causes the following error:

Server error, status code: 400, error code: 100001, message: The app is invalid: health_check_timeout maximum_exceeded</code>

Extension

The Java buildpack can also be easily extended. It creates abstractions for three types of components (containers, frameworks, and JREs) to allow users to easily add functionality. In addition to these abstractions, there are a number of utility classes for simplifying typical buildpack behaviors.

As an example, the New Relic framework looks like this:

class NewRelicAgent < JavaBuildpack::Component::VersionedDependencyComponent

  # @macro base_component_compile
  def compile
    FileUtils.mkdir_p logs_dir

    download_jar
    @droplet.copy_resources
  end

  # @macro base_component_release
  def release
    @droplet.java_opts
    .add_javaagent(@droplet.sandbox + jar_name)
    .add_system_property('newrelic.home', @droplet.sandbox)
    .add_system_property('newrelic.config.license_key', license_key)
    .add_system_property('newrelic.config.app_name', "'#{application_name}'")
    .add_system_property('newrelic.config.log_file_path', logs_dir)
  end

  protected

  # @macro versioned_dependency_component_supports
  def supports?
    @application.services.one_service? FILTER, 'licenseKey'
  end

  private

  FILTER = /newrelic/.freeze

  def application_name
    @application.details['application_name']
  end

  def license_key
    @application.services.find_service(FILTER)['credentials']['licenseKey']
  end

  def logs_dir
    @droplet.sandbox + 'logs'
  end

end

For more information, see Design, Extending, and Configuration and Extension in the Cloud Foundry Java Buildpack repository on GitHub.

Environment variables

You can access environments variable programmatically.

For example, you can obtain VCAP_SERVICES by running:

System.getenv("VCAP_SERVICES");

For more information, see TAS for VMs Environment Variables.