Chapter 3. Get Started

The Red Hat JBoss Data Grid images were automatically created during the installation of OpenShift along with the other default image streams and templates.

You can make changes to the JBoss Data Grid configuration in the image using either the S2I templates, or by using a modified JDG for OpenShift image.

3.1. Using the JDG for OpenShift image Source-to-Image (S2I) Process

The recommended method to run and configure the OpenShift JDG for OpenShift image is to use the OpenShift S2I process together with the application template parameters and environment variables.

The S2I process for the JDG for OpenShift image works as follows:

  1. If there is a pom.xml file in the source repository, a Maven build is triggered with the contents of $MAVEN_ARGS environment variable.
  2. By default the package goal is used with the openshift profile, including the system properties for skipping tests (-DskipTests) and enabling the Red Hat GA repository (-Dcom.redhat.xpaas.repo.redhatga).

  3. The results of a successful Maven build are copied to JDG_HOME/standalone/deployments. This includes all JAR, WAR, and EAR files from the directory within the source repository specified by $ARTIFACT_DIR environment variable. The default value of $ARTIFACT_DIR is the target directory.

    • Any JAR, WAR, and EAR in the deployments source repository directory are copied to the JDG_HOME/standalone/deployments directory.

    • All files in the configuration source repository directory are copied to JDG_HOME/standalone/configuration.

      Note

      If you want to use a custom JBoss Data Grid configuration file, it should be named clustered-openshift.xml.

  4. All files in the modules source repository directory are copied to JDG_HOME/modules.

Refer to the Artifact Repository Mirrors section for additional guidance on how to instruct the S2I process to utilize the custom Maven artifacts repository mirror.

3.1.1. Using a Different JDK Version in the JDG for OpenShift image

The JDG for OpenShift image may come with multiple versions of OpenJDK installed, but only one is the default. For example, the JDG for OpenShift image comes with OpenJDK 1.7 and 1.8 installed, but OpenJDK 1.8 is the default.

If you want the JDG for OpenShift image to use a different JDK version than the default, you must:

  • Ensure that your pom.xml specifies to build your code using the intended JDK version.

  • In the S2I application template, configure the image’s JAVA_HOME environment variable to point to the intended JDK version. For example: 

    {
  "name": "JAVA_HOME",
  "value": "/usr/lib/jvm/java-1.7.0"
}

3.2. Using a Modified JDG for OpenShift image

An alternative method is to make changes to the image, and then use that modified image in OpenShift.

The JBoss Data Grid configuration file that OpenShift uses inside the JDG for OpenShift image is JDG_HOME/standalone/configuration/clustered-openshift.xml, and the JBoss Data Grid startup script is JDG_HOME/bin/openshift-launch.sh.

You can run the JDG for OpenShift image in Docker, make the required configuration changes using the JBoss Data Grid Management CLI (JDG_HOME/bin/jboss-cli.sh), and then commit the changed container as a new image. You can then use that modified image in OpenShift.

Important

It is recommended that you do not replace the OpenShift placeholders in the JDG for OpenShift image configuration file, as they are used to automatically configure services (such as messaging, datastores, HTTPS) during a container’s deployment. These configuration values are intended to be set using environment variables.

Note

Ensure that you follow the guidelines for creating images.

3.3. Binary Builds

To deploy existing applications on OpenShift, you can use the binary source capability.

3.3.1. Deploy binary build of EAP 6.4 / EAP 7.0 Infinispan application together with JDG for OpenShift image

The following example uses CarMart quickstart to deploy EAP 6.4 / EAP 7.0 Infinispan application, accessing a remote JBoss Data Grid server running in the same OpenShift project.

Prerequisite:

  1. Create a new project. 

    $ oc new-project jdg-bin-demo
    Note

    For brevity this example will not configure clustering. See dedicated section if data replication across the cluster is desired.

Deploy JBoss Data Grid 6.5 server:

  1. Identify the image stream for the JBoss Data Grid 6.5 image. 

    $ oc get is -n openshift | grep grid | cut -d ' ' -f 1
jboss-datagrid65-openshift

  2. Deploy the server. Also specify the following:

    1. carcache as the name of application,
    2. A Hot Rod based connector, and

    3. carcache as the name of the Infinispan cache to configure. 

      $ oc new-app --name=carcache \
--image-stream=jboss-datagrid65-openshift \
-e INFINISPAN_CONNECTORS=hotrod \
-e CACHE_NAMES=carcache
--> Found image d83b4b2 (3 months old) in image stream "openshift/jboss-datagrid65-openshift" under tag "latest" for "jboss-datagrid65-openshift"

    JBoss Data Grid 6.5
    -------------------
    Provides a scalable in-memory distributed database designed for fast access to large volumes of data.

    Tags: datagrid, java, jboss, xpaas

    * This image will be deployed in deployment config "carcache"
    * Ports 11211/tcp, 11222/tcp, 8080/tcp, 8443/tcp, 8778/tcp will be load balanced by service "carcache"
      * Other containers can access this service through the hostname "carcache"

--> Creating resources ...
    deploymentconfig "carcache" created
    service "carcache" created
--> Success
    Run 'oc status' to view your app.

Deploy binary build of EAP 6.4 / EAP 7.0 CarMart application:

  1. Clone the source code. 

    $ git clone https://github.com/jboss-openshift/openshift-quickstarts.git
  2. Configure the Red Hat JBoss Middleware Maven repository.

  3. Build the datagrid/carmart application. 

    $ cd openshift-quickstarts/datagrid/carmart/
    $ mvn clean package
[INFO] Scanning for projects...
[INFO]
[INFO] ------------------------------------------------------------------------
[INFO] Building JBoss JDG Quickstart: carmart 1.2.0.Final
[INFO] ------------------------------------------------------------------------
...
[INFO] Building war: /tmp/openshift-quickstarts/datagrid/carmart/target/jboss-carmart.war
[INFO] ------------------------------------------------------------------------
[INFO] BUILD SUCCESS
[INFO] ------------------------------------------------------------------------
[INFO] Total time: 3.360 s
[INFO] Finished at: 2017-06-27T19:11:46+02:00
[INFO] Final Memory: 34M/310M
[INFO] ------------------------------------------------------------------------

  1. Prepare the directory structure on the local file system.

    Application archives in the deployments/ subdirectory of the main binary build directory are copied directly to the standard deployments folder of the image being built on OpenShift. For the application to deploy, the directory hierarchy containing the web application data must be correctly structured.

    Create main directory for the binary build on the local file system and deployments/ subdirectory within it. Copy the previously built WAR archive for the carmart quickstart to the deployments/ subdirectory: 

    $ ls
pom.xml  README.md  README-openshift.md  README-tomcat.md  src  target
    $ mkdir -p jdg-binary-demo/deployments
    $ cp target/jboss-carmart.war jdg-binary-demo/deployments/
    Note

    Location of the standard deployments directory depends on the underlying base image, that was used to deploy the application. See the following table:

    Table 3.1. Standard Location of the Deployments Directory

    Name of the Underlying Base Image(s)Standard Location of the Deployments Directory

    EAP for OpenShift 6.4 and 7.0

    $JBOSS_HOME/standalone/deployments

    Java S2I for OpenShift

    /deployments

    JWS for OpenShift

    $JWS_HOME/webapps

  2. Identify the image stream for EAP 6.4 / EAP 7.0 image. 

    $ oc get is -n openshift | grep eap | cut -d ' ' -f 1
jboss-eap64-openshift
jboss-eap70-openshift

  1. Create new binary build, specifying image stream and application name. 

    $ oc new-build --binary=true \
--image-stream=jboss-eap64-openshift \
--name=eap-app
--> Found image 8fbf0f7 (2 months old) in image stream "openshift/jboss-eap64-openshift" under tag "latest" for "jboss-eap64-openshift"

    JBoss EAP 6.4
    -------------
    Platform for building and running JavaEE applications on JBoss EAP 6.4

    Tags: builder, javaee, eap, eap6

    * A source build using binary input will be created
      * The resulting image will be pushed to image stream "eap-app:latest"
      * A binary build was created, use 'start-build --from-dir' to trigger a new build

--> Creating resources with label build=eap-app ...
    imagestream "eap-app" created
    buildconfig "eap-app" created
--> Success
    Note

    Specify jboss-eap70-openshift as the image stream name in the aforementioned command to use EAP 7.0 image for the application.

  2. Start the binary build. Instruct oc executable to use main directory of the binary build we created in previous step as the directory containing binary input for the OpenShift build. 

    $ oc start-build eap-app --from-dir=jdg-binary-demo/ --follow
Uploading directory "jdg-binary-demo" as binary input for the build ...
build "eap-app-1" started
Receiving source from STDIN as archive ...
Copying all war artifacts from /home/jboss/source/. directory into /opt/eap/standalone/deployments for later deployment...
Copying all ear artifacts from /home/jboss/source/. directory into /opt/eap/standalone/deployments for later deployment...
Copying all rar artifacts from /home/jboss/source/. directory into /opt/eap/standalone/deployments for later deployment...
Copying all jar artifacts from /home/jboss/source/. directory into /opt/eap/standalone/deployments for later deployment...
Copying all war artifacts from /home/jboss/source/deployments directory into /opt/eap/standalone/deployments for later deployment...
'/home/jboss/source/deployments/jboss-carmart.war' -> '/opt/eap/standalone/deployments/jboss-carmart.war'
Copying all ear artifacts from /home/jboss/source/deployments directory into /opt/eap/standalone/deployments for later deployment...
Copying all rar artifacts from /home/jboss/source/deployments directory into /opt/eap/standalone/deployments for later deployment...
Copying all jar artifacts from /home/jboss/source/deployments directory into /opt/eap/standalone/deployments for later deployment...
Pushing image 172.30.82.129:5000/jdg-bin-demo/eap-app:latest ...
Pushed 0/7 layers, 1% complete
Pushed 1/7 layers, 17% complete
Pushed 2/7 layers, 31% complete
Pushed 3/7 layers, 46% complete
Pushed 4/7 layers, 81% complete
Pushed 5/7 layers, 84% complete
Pushed 6/7 layers, 99% complete
Pushed 7/7 layers, 100% complete
Push successful

  3. Create a new OpenShift application based on the build. 

    $ oc new-app eap-app
--> Found image ee25340 (3 minutes old) in image stream "jdg-bin-demo/eap-app" under tag "latest" for "eap-app"

    jdg-bin-demo/eap-app-1:4bab3f63
    -------------------------------
    Platform for building and running JavaEE applications on JBoss EAP 6.4

    Tags: builder, javaee, eap, eap6

    * This image will be deployed in deployment config "eap-app"
    * Ports 8080/tcp, 8443/tcp, 8778/tcp will be load balanced by service "eap-app"
      * Other containers can access this service through the hostname "eap-app"

--> Creating resources ...
    deploymentconfig "eap-app" created
    service "eap-app" created
--> Success
    Run 'oc status' to view your app.

  4. Expose the service as route. 

    $ oc get svc -o name
service/carcache
service/eap-app
    $ oc get route
No resources found.
    $ oc expose svc/eap-app
route "eap-app" exposed
    $ oc get route
NAME      HOST/PORT                                    PATH      SERVICES   PORT       TERMINATION   WILDCARD
eap-app   eap-app-jdg-bin-demo.openshift.example.com             eap-app    8080-tcp                 None

  5. Access the application.

    Access the CarMart application in your browser using the URL http://eap-app-jdg-bin-demo.openshift.example.com/jboss-carmart. You can view / remove existing cars (Home tab), or add a new car (New car tab).