/java-buildpack

Cloud Foundry buildpack for running Java applications

Primary LanguageRubyApache License 2.0Apache-2.0

Cloud Foundry Java Buildpack

The java-buildpack is a Cloud Foundry buildpack for running JVM-based applications. It is designed to run many JVM-based applications (Grails, Groovy, Java Main, Play Framework, Spring Boot, and Servlet) with no additional configuration, but supports configuration of the standard components, and extension to add custom components.

Usage

To use this buildpack specify the URI of the repository when pushing an application to Cloud Foundry:

$ cf push <APP-NAME> -p <ARTIFACT> -b https://github.com/cloudfoundry/java-buildpack.git

Examples

The following are very simple examples for deploying the artifact types that we support.

Configuration and Extension

The buildpack default configuration can be overridden with an environment variable matching the configuration file you wish to override minus the .yml extension and with a prefix of JBP_CONFIG. It is not possible to add new configuration properties and properties with nil or empty values will be ignored by the buildpack (in this case you will have to extend the buildpack, see below). The value of the variable should be valid inline yaml, referred to as "flow style" in the yaml spec (Wikipedia has a good description of this yaml syntax). For example, to change the default version of Java to 11 and adjust the memory heuristics apply this environment variable to the application.

$ cf set-env my-application JBP_CONFIG_OPEN_JDK_JRE '{ jre: { version: 11.+ }, memory_calculator: { stack_threads: 25 } }'

If the key or value contains a special character such as : it should be escaped with double quotes. For example, to change the default repository path for the buildpack.

$ cf set-env my-application JBP_CONFIG_REPOSITORY '{ default_repository_root: "http://repo.example.io" }'

If the key or value contains an environment variable that you want to bind at runtime you need to escape it from your shell. For example, to add command line arguments containing an environment variable to a Java Main application.

$ cf set-env my-application JBP_CONFIG_JAVA_MAIN '{ arguments: "--server.port=9090 --foo=bar" }'

An example of configuration is to specify a javaagent that is packaged within an application.

$ cf set-env my-application JAVA_OPTS '-javaagent:app/META-INF/myagent.jar -Dmyagent.config_file=app/META-INF/my_agent.conf'

Environment variable can also be specified in the applications manifest file. For example, to specify an environment variable in an applications manifest file that disables Auto-reconfiguration.

env:
  JBP_CONFIG_SPRING_AUTO_RECONFIGURATION: '{ enabled: false }'

This final example shows how to change the version of Tomcat that is used by the buildpack with an environment variable specified in the applications manifest file.

env:
  JBP_CONFIG_TOMCAT: '{ tomcat: { version: 8.0.+ } }'

See the Environment Variables documentation for more information.

To learn how to configure various properties of the buildpack, follow the "Configuration" links below.

The buildpack supports extension through the use of Git repository forking. The easiest way to accomplish this is to use GitHub's forking functionality to create a copy of this repository. Make the required extension changes in the copy of the repository. Then specify the URL of the new repository when pushing Cloud Foundry applications. If the modifications are generally applicable to the Cloud Foundry community, please submit a pull request with the changes. More information on extending the buildpack is available here.

Additional Documentation

Building Packages

The buildpack can be packaged up so that it can be uploaded to Cloud Foundry using the cf create-buildpack and cf update-buildpack commands. In order to create these packages, the rake package task is used.

Note that this process is not currently supported on Windows. It is possible it will work, but it is not tested, and no additional functionality has been added to make it work.

Online Package

The online package is a version of the buildpack that is as minimal as possible and is configured to connect to the network for all dependencies. This package is about 50K in size. To create the online package, run:

$ bundle install
$ bundle exec rake clean package
...
Creating build/java-buildpack-cfd6b17.zip

Offline Package

The offline package is a version of the buildpack designed to run without access to a network. It packages the latest version of each dependency (as configured in the config/ directory) and disables remote_downloads. This package is about 180M in size. To create the offline package, use the OFFLINE=true argument:

To pin the version of dependencies used by the buildpack to the ones currently resolvable use the PINNED=true argument. This will update the config/ directory to contain exact version of each dependency instead of version ranges.

$ bundle install
$ bundle exec rake clean package OFFLINE=true PINNED=true
...
Creating build/java-buildpack-offline-cfd6b17.zip

Only packages referenced in the config/components.yml file will be cached. Additional packages may be added using the ADD_TO_CACHE argument. The value of ADD_TO_CACHE should be set to the name of a .yml file in the config/ directory with the .yml file extension omitted (e.g. sap_machine_jre). Multiple file names may be separated by commas. This is useful to add additional JREs. These additional components will not be enabled by default and must be explicitly enabled in the application with the JBP_CONFIG_COMPONENTS environment variable.

$ bundle install
$ bundle exec rake clean package OFFLINE=true ADD_TO_CACHE=sap_machine_jre,ibm_jre
...
Caching https://public.dhe.ibm.com/ibmdl/export/pub/systems/cloud/runtimes/java/8.0.6.26/linux/x86_64/ibm-java-jre-8.0-6.26-x86_64-archive.bin
Caching https://github.com/SAP/SapMachine/releases/download/sapmachine-11.0.10/sapmachine-jre-11.0.10_linux-x64_bin.tar.gz
...
Creating build/java-buildpack-offline-cfd6b17.zip

Package Versioning

Keeping track of different versions of the buildpack can be difficult. To help with this, the rake package task puts a version discriminator in the name of the created package file. The default value for this discriminator is the current Git hash (e.g. cfd6b17). To change the version when creating a package, use the VERSION=<VERSION> argument:

$ bundle install
$ bundle exec rake clean package VERSION=2.1
...
Creating build/java-buildpack-2.1.zip

Packaging Caveats

  1. When pinning versions, only the default JRE version is pinned. There is special handling to package additional versions of a JRE and the way this works, it will pick the latest version at the time you package not at the time of the version's release.
  2. The index.yml file for a dependencie is packaged in the buildpack cache when building offline buildpacks. The index.yml file isn't versioned with the release, so if you package an offline buildpack for an older release, it will pull the current index.yml, not the one from the time of the release. This can result in errors if a user tells the buildpack to install the latest version of a default dependency, because the latest version is calculated from the index.yml file which has more recent versions than what are packaged in the offline buildpack. Because of #1, this only impacts the default JRE. Non-default JREs always package the most recent version, which is also the most recent version in index.yml at the time you package the offline buildpack.
  3. Because of #1 and #2, it is not present to accurately reproduce packages of the buildpack, after releases have been cut. If building pinning or offline buildpacks, it is suggested to build them as soon as possible after a release is cut and save the produced artifact.

See #892 for additional details.

Running Tests

To run the tests, do the following:

$ bundle install
$ bundle exec rake

Running Cloud Foundry locally is useful for privately testing new features.

Contributing

Pull requests are welcome; see the contributor guidelines for details.

License

This buildpack is released under version 2.0 of the Apache License.