gcr.io/paketo-buildpacks/libertyThe Paketo Buildpack for Liberty is a Cloud-Native Buildpack that contributes Open Liberty or WebSphere Liberty for Java EE support.
The buildpack will participate when building any of the following:
server package commandWhen building a web application, this buildpack will participate if all the following conditions are met:
$BP_JAVA_APP_SERVER is liberty or if $BP_JAVA_APP_SERVER is unset or empty and this is the first buildpack to provide a Java application server.Main-Class is NOT defined in the manifest<APPLICATION_ROOT>/META-INF/application.xml or <APPLICATION_ROOT>/WEB-INF existWhen building from a packaged Liberty server or from a Liberty root directory, the buildpack will participate if all the following conditions are met:
<APPLICATION_ROOT>/wlp/usr/servers/$BP_LIBERTY_SERVER_NAME/server.xml exists<APPLICATION_ROOT>/wlp/usr/servers/$BP_LIBERTY_SERVER_NAME/apps or
<APPLICATION_ROOT>/wlp/usr/servers/$BP_LIBERTY_SERVER_NAME/dropinsThe buildpack will do the following:
defaultServerweb process type<APPLICATION_ROOT> to <WLP_USR_DIR>/servers/<SERVER_NAME>/apps/app<APPLICATION_ROOT> to <WLP_USR_DIR>The buildpack will support all available profiles of the most recent versions of the Liberty runtime. Because the Liberty versioning scheme is not conformant to semantic versioning, a Liberty version like 22.0.0.2 is defined here as 22.0.2, and should be referenced as such.
| Environment Variable | Description |
|---|---|
$BP_JAVA_APP_SERVER |
The application server to use. It defaults to `` (empty string) which means that order dictates which Java application server is installed. The first Java application server buildpack to run will be picked. |
$BP_LIBERTY_INSTALL_TYPE |
Install type of Liberty. Valid options: ol, wlp, and none. Defaults to ol. |
$BP_LIBERTY_VERSION |
The version of Liberty to install. Defaults to the latest version of the runtime. To see what version is available with your version of the buildpack, please see the release notes. At present, only the latest version is supported, and you need to use an older version of the buildpack if you want an older version of Liberty. |
$BP_LIBERTY_PROFILE |
The Liberty profile to use. Defaults to kernel. |
$BP_LIBERTY_SERVER_NAME |
Name of the server to use. Defaults to defaultServer when building an application. If building a packaged server and there is only one bundled server present, then the buildpack will use that. |
$BP_LIBERTY_CONTEXT_ROOT |
The context root to use for the application. Defaults to the context root for the application if defined in the server.xml. Otherwise, it defaults to /. |
$BP_LIBERTY_FEATURES |
Space separated list of Liberty features to be installed with the Liberty runtime. Supports any valid Liberty feature. See the Liberty Documentation for available features. |
BP_LIBERTY_FEATURE_INSTALL_DISABLED |
Disable running the feature installer. Defaults to false. |
$BPL_LIBERTY_LOG_LEVEL |
Sets the logging level. If not set, attempts to get the buildpack's log level. If unable, defaults to INFO |
Valid profiles for Open Liberty are:
Valid profiles for WebSphere Liberty are:
By default, the Liberty buildpack will log in json format. This will aid in log ingestion. Due to design decisions from the Liberty team, setting this format to any other value will prevent all log types from being sent to stdout and will instead go to messages.log. In addition, the log sources that will go to stdout are message,trace,accessLog,ffdc,audit.
All of these defaults can be overridden by setting the appropriate properties found in Liberty's documentation. They can be set as environment variables, or in bootstrap.properties.
The following server configuration files can be included in the application image:
IMPORTANT NOTE: Do not put secrets in any of these configuration files! The files will be included in the resulting image and can leak your secrets. See Configuring Secrets for information on how to provide secrets in your configuration.
At the moment, these files can only be included in the build by telling the Maven or Gradle buildpacks to provide them. Thus this method of including server configuration can only be performed when building from source code, it will not work when building with a pre-compiled WAR file.
For example, to provide server configuration in the src/main/liberty/config, set one of the following environment
variables in your pack build command.
--env BP_MAVEN_BUILT_ARTIFACT="target/*.[ejw]ar src/main/liberty/config/*"--env BP_GRADLE_BUILT_ARTIFACT="build/libs/*.[ejw]ar src/main/liberty/config/*"Any application configuration provided in the server.xml must have an id set. This is required for the Liberty buildpack to provide additional configuration (e.g., updating the application's location).
For example:
<application id="myapp" name="myapp" context-root="/my-app">
<classloader commonLibraryRef="my-lib-ref"/>
</application>Sensitive data should not be included in any of the configuration files provided during the build. The files will be included in the application image which can leak your secrets.
Instead, set the secrets in your bootstrap.properties file and provide it to the application container as a binding.
For example, to configure a custom password for Liberty's default keystore, you can add the following line to your
server.xml:
<keyStore id="defaultKeyStore" password="${keystore.password}" />The property keystore.password can then be configured in the application image via a binding of type liberty under
the bootstrap.properties key.
The different installation types that can be configured are:
ol: This will download an Open Liberty runtime and use it when deploying the container.wlp: This will download a WebSphere Liberty runtime and use it when deploying the container.none: This will use the Liberty runtime provided in the stack run image. Requires a custom builder.The buildpack accepts the following bindings:
liberty| Key | Value | Description |
|---|---|---|
server.xml |
<file-contents> |
This file will replace the defaultServer's server.xml and is not subject to any post-processing; therefore, any variable references therein must be resolvable. Optional. |
bootstrap.properties |
<file-contents> |
This file will replace the defaultServer's bootstrap.properties. This is one place to define variables used by server.xml. Optional. |
dependency-mapping| Key | Value | Description |
|---|---|---|
<dependency-digest> |
<uri> |
If needed, the buildpack will fetch the dependency with digest <dependency-digest> from <uri> |
You can install features by setting $BP_LIBERTY_FEATURES to be a space separate list of the features you want to install. For example, BP_LIBERTY_FEATURES='jdbc-4.3 el-3.0'. You can see a full list of available features in the Liberty documentation on Features.
Features are by default downloaded from Maven Central. You can control this behavior using the standard environment variables for controlling featureUtility. For example, FEATURE_REPO_URL, http_proxy and https_proxy.
Custom features can be configured on the server as well using a volume mount to /features that contains the feature JARs and manifests along with a feature descriptor.
The feature manifest is a TOML file called features.toml containing a list of features that should be installed on the server.
A feature has the properties:
name: Name of the feature to enable. Use the symbolic name of the feature that you would use when enabling the feature in the server.xml.uri: URI of where to find the feature. The file scheme is the only supported scheme at the moment.version: Version of the feature.dependencies: List of features that the custom feature depends on, if any.This example shows how to configure a feature called dummyCache that has a dependency on the distributedMap-1.0
feature.
First create the feature descriptor features.toml with the following content:
[[features]]
name = "dummyCache"
uri = "file:///features/cache.dummy_1.0.0.jar"
version = "1.0.0"
dependencies = ["distributedMap-1.0"]Using this feature description, the Liberty buildpack will look for the feature JAR in the volume mounted on
/features at the path features/cache.dummy_1.0.0.jar. The buildpack also assumes that the feature manifest file will
be at the path features/cache.dummy_1.0.0.mf.
After creating the feature descriptor, tar and gzip the feature.toml and features directory so that it has the
contents similar to the following:
$ tar tzf liberty-conf.tar.gz
./
./features/
./features.toml
./features/cache.dummy_1.0.0.mf
./features/cache.dummy_1.0.0.jarThe custom features can then be provided to the build by mounting the feature directory to /features:
pack build --path myapp --env BP_JAVA_APP_SERVER=liberty --volume /Users/hwibell/Development/paketo-buildpacks/liberty-e2e.bak/data/conf/features:/features myappThe buildpack can build from Liberty server installation directory or from a packaged server that was created using the
server package command.
To build from a Liberty server installation, change your working directory to the installation root containing the wlp
directory and run
pack build --env BP_JAVA_APP_SERVER=liberty myappA packaged server is created using the server package command of the Liberty runtime. To create a packaged server,
run this command from your Liberty installation's wlp directory:
bin/server package defaultServer --include=usrThe packaged server can then be supplied to the build by using the --path argument like so:
pack build --env BP_JAVA_APP_SERVER=liberty --path <packaged-server-zip-path> myappLiberty iFixes can be applied using a volume mount to /ifixes. See the additional docs for details.
This buildpack is released under version 2.0 of the Apache License.