WebSphere Liberty UBI-min images for OpenShift Source To Image (S2I)

This repository contains the source for building a WebSphere Liberty Source to Image (S2I) builder using Red Hat Universal Base Image (UBI) 7 and Java 8, Java 11, Java 17 or Java 21.

More information on S2I can be found at https://github.com/openshift/source-to-image

The built S2I image can be run using Docker.

Building the images

Images are built using docker community edition and cekit version 4. Mac OSX installation and build tips.

Cloning the repository:

$ git clone https://github.com/WASdev/websphere-liberty-s2i
$ cd websphere-liberty-s2i

Building the Open Liberty S2I images:

Run the Makefile to generate all images, or generate a single image by running:

$ cd $IMAGE_DIR
$ cekit build docker

Example values for IMAGE_DIR are images/java8/builder, images/java8/runtime, images/java11/builder, images/java11/runtime, images/java17/builder, images/java17/runtime, images/java21/builder, or images/java21/runtime.

S2I Usage

To build a simple jee application using standalone S2I and then run the resulting image with Docker execute:

$ s2i build  https://github.com/WASdev/sample.ferret.git ibmcom/websphere-liberty-s2i:java8 websphere-liberty-test
$ docker run -p 9080:9080 websphere-liberty-test

Accessing the application:

$ curl 127.0.0.1:9080/ferret/

S2I Runtime Images

Use the following commands to build and test a lightweight runtime image

$ s2i build https://github.com/WASdev/sample.ferret.git ibmcom/websphere-liberty-s2i:java8 websphere-liberty-runtime-test --runtime-image ibmcom/websphere-liberty-s2i:runtime-java8 --runtime-artifact /opt/ibm/wlp/usr/servers/defaultServer/dropins
$ docker run -p 9080:9080 websphere-liberty-runtime-test

More information on the WebSphere Liberty S2I runtime image and available options is available here.

Test

The tests for this repository check basic functionality of a JEE application built on top of the Open Liberty S2I images.

$ make test

S2I Build Behavior

If a pom.xml file is found in the root of the source tree, it will be built using maven.

If the root of the source tree contains a file named Dockerfile and a directory named maven then the build will assume that the source tree is the output of the fabric8 maven plugin

If the environment variable LIBERTY_RUNNABLE_JAR is set, the build will attempt to copy that file to /opt/ol/ol-runnable.jar. At runtime, S2I will run that jar file instead of running the normal Liberty instance.

If a server.xml file exists in the directory src/main/liberty/config it will be copied to the config directory of the Liberty instance.

If the directory src/wlp/usr exists, it will be copied to the wlp directory o the Libert instance.

All WAR, JAR, EAR, and RAR files from the build will be copied to either the apps or dropins directory the Liberty instance depending on the value of the DEPLOY_TO_APPS environment variable.

Environment variables to be used at s2i build time

The following environment variables can be passed to the S2I build process to customize Open Liberty. More information on these variables and the functions they enable can be found at https://github.com/OpenLiberty/ci.docker

• MAVEN_MIRROR_URL
  • Description: Use the specified maven mirror to resolve dependencies
• DEPLOY_TO_APPS
  • Description: When true, applicaton binaries will be copied to apps instead of dropins
• TLS or SSL (SSL is deprecated)
  • Description: Enable Transport Security in Liberty by adding the transportSecurity-1.0 feature (includes support for SSL).
  • XML Snippet Location: keystore.xml.

The following environment variables are now deprecated. Support will be removed in the future.

• HTTP_ENDPOINT
  • Description: Add configuration properties for an HTTP endpoint.
  • XML Snippet Location: http-ssl-endpoint.xml when SSL is enabled. Otherwise http-endpoint.xml
• MP_HEALTH_CHECK
  • Description: Check the health of the environment using Liberty feature mpHealth-1.0 (implements MicroProfile Health).
  • XML Snippet Location: mp-health-check.xml
• MP_MONITORING
  • Description: Monitor the server runtime environment and application metrics by using Liberty features mpMetrics-1.1 (implements Microprofile Metrics) and monitor-1.0.
  • XML Snippet Location: mp-monitoring.xml
  • Note: With this option, /metrics endpoint is configured without authentication to support the environments that do not yet support scraping secured endpoints.
• IIOP_ENDPOINT
  • Description: Add configuration properties for an IIOP endpoint.
  • XML Snippet Location: iiop-ssl-endpoint.xml when SSL is enabled. Otherwise, iiop-endpoint.xml.
  • Note: If using this option, env.IIOP_ENDPOINT_HOST environment variable should be set to the server's host. See IIOP endpoint configuration for more details.
• JMS_ENDPOINT
  • Description: Add configuration properties for an JMS endpoint.
  • XML Snippet Location: jms-ssl-endpoint.xml when SSL is enabled. Otherwise, jms-endpoint.xml

Server Configuration

If you want to use your own server.xml file rather than the default, it should be present in the src/main/liberty/config directory.

OpenShift oc usage

If your openshift installation doesn't already contain the Open Liberty image:

• Adding the image streams: oc create -f imagestreams/openliberty-ubi-min.json An Open Liberty imagestream will be created.

• When adding the Open Liberty imagestream to the openshift namespace, the OpenShift catalog is automatically populated with a the template Open Liberty allowing you to create a new build and new deployment from the OpenShift Web Console.