Getting started with OpenShift Java S2I

Introduction

The OpenShift Java S2I image, which allows you to automatically build and deploy your Java microservices, has just been released and is now publicly available. This article describes how to get started with the Java S2I container image, but first, let’s discuss why having a Java S2I image is so important.

Why Java S2I?

The Java S2I image enables developers to automatically build, deploy and run java applications on demand, in OpenShift Container Platform, by simply specifying the location of their application source code or compiled java binaries. In many cases, these java applications are bootable “fat jars” that include an embedded version of an application server and other frameworks. An example of such open source projects is Spring Boot, Eclipse Vert.x, and WildFly Swarm. Having a common Java S2I image that is designed specifically for OpenShift makes the development of bootable fat jars easier by including a number of useful features such as:

• Simple yet flexible: The Java S2I image can handle complex build structures, but default it will assume that the JAR to run will be available in the /target directory after a successful build. If that is not the case you can use the environment variable ARTIFACT_DIR. Also if a build produces multiple JAR files (which is the case in the Eclipse Vert.x example used later in this article) then it’s possible to specify which JAR file to run using the environment variable JAVA_APP_JAR. However, in most cases, all you have to do is to point directly at you source repository and the Java S2I image will work.
• Automatic JVM memory configuration: In OpenShift, resources may be limited by quotas, etc. If such a limitation is in place, the Java S2I image will automatically adopt the JVM memory settings so that the JVM doesn’t use more memory than it’s allowed to use which in turns helps to avoid OutOfMemory exceptions. This feature is enabled by default but can be disabled by setting a fixed value for the heap using -Xmx in the environment variable JAVA_OPTIONS.
• Expose JMX statistics via Jolokia: By default, the Java S2I image will enable Jolokia which exposes JMX statistics and operations via HTTP. This enables more detailed monitoring capabilities of applications. This feature is enabled by default but can be disabled by setting the environment variable AB_JOLOKIA_OFF to true.
• Reduce the container image size: To keep the size of the container image to a minimum it’s possible to have the Java S2I image delete any maven repo data before building the final image. This feature is disabled by default to support incremental builds. To enable the removal of maven artifacts from the final container image set the environment variable MAVEN_CLEAR_REPO to true.

Getting started with Java S2I

Below are step-by-step instructions that exemplify one way to use the Java S2I image.

1. Create a new project or use an existing one.

oc new-project myproject

2. Before we start using the Java S2I image we need to tell OpenShift how to find it. This is done by creating an image stream. I’ve created an image stream definition here that you can download and use. To add the image stream to your project run the following command:

oc create -f openjdk-s2i-imagestream.json

3. Open the openshift console and navigate to the project you created and click on Add to Project.

4. In the Browse Catalog window type openjdk in the search field.

5. Click select and give the application a name and point to a git repo containing the application source code.

For a WildFly Swarm example you can use:
https://github.com/redhat-helloworld-msa/hola.git ^[1]

For an Eclipse Vert.x example you can use:
https://github.com/redhat-helloworld-msa/aloha.git ^[2]

For a Spring Boot example you can use:
https://github.com/redhat-helloworld-msa/ola.git

6. Wait for the build to finish and click on the route (the URL in the upper right corner of the dashboard).

7. For the WildFly example application, the swagger console should now be displayed.

8. Try adding /api/hola to the address bar (or /api/ola for the Spring Boot example) and the outcome should be similar to the picture below.

9. DONE

I hope you have enjoyed this getting started with Java S2I guide.

^[1]=Please note that because of a known issue with WildFly Swarm and Jolokia you should also click on Show advanced … and add an environment variable to the Deployment Configuration with name AB_JOLOKIA_OFF and value true.

^[2]=The example project for Eclipse Vert.x produces two JAR files so we need to tell the Java S2I image which one to use by clicking on Show advanced … and add an environment variable to the Deployment Configuration with name JAVA_APP_JAR and value aloha-fat.jar.