Chapter 4. Tutorials

4.1. Example Workflow: Using Maven to build and run Uber JAR on Java S2I for OpenShift Image

This tutorial focuses on building and running Maven applications on OpenShift using the Java S2I for OpenShift image.

4.1.1. Prepare for Deployment

  1. Log in to the OpenShift instance by running following command and providing credentials. 

    $ oc login

  2. Create a new project. 

    $ oc new-project js2i-demo

  3. Create a service account to be used for this deployment. 

    $ oc create serviceaccount js2i-service-account

  4. Add the view role to the service account. This enables the service account to view all the resources in the js2i-demo namespace, which is necessary for managing the cluster. 

    $ oc policy add-role-to-user view system:serviceaccount:js2i-demo:js2i-service-account

  5. Generate a self-signed certificate keystore. This example uses ‘keytool’, a package included with the Java Development Kit, to generate dummy credentials for use with the keystore: 

    $ keytool -genkey -keyalg RSA -alias selfsigned -keystore keystore.jks -validity 360 -keysize 2048
    Note

    OpenShift does not permit login authentication from self-signed certificates. For demonstration purposes, this example uses ‘openssl‘ to generate a CA certificate to sign the SSL keystore and create a truststore. This truststore is also included in the creation of the secret, and specified in the SSO template.

    Warning

    For production environments, its recommended that you use your own SSL certificate purchased from a verified Certificate Authority (CA) for SSL-encrypted connections (HTTPS).

  6. Use the generated keystore file to create the secret. 

    $ oc secrets new js2i-app-secret keystore.jks

  7. Add the secret to the service account created earlier. 

    $ oc secrets link js2i-service-account js2i-app-secret

4.1.2. Deployment

  1. Create a new application using the Java S2I for OpenShift image and Java source code. 

    $ oc new-app redhat-openjdk18-openshift~https://github.com/jboss-openshift/openshift-quickstarts.git --context-dir=undertow-servlet

  2. View the Maven build logs for the example repository by running the following command: 

    $ oc logs -f bc/openshift-quickstarts

4.1.3. Post-Deployment

4.1.3.1. Creating a Route

After deployment is finished create a route for the application so that clients outside of OpenShift can connect using SSL.

  1. Create a route. 

    $ oc create route edge --service=openshift-quickstarts

  2. Get route. 

    $ oc get route
  3. Access the application in your browser using the URL (value of HOST/PORT field from previous command output).

  4. Optionally, you can also scale up the application instance by running the following command: 

    $ oc scale dc js2i-demo --replicas=3

4.2. Example Workflow: Remote Debugging a Java Application running on Java S2I for OpenShift Image

This tutorial describes remote debugging of a Java application deployed on OpenShift using the Java S2I for OpenShift image. The capability can be enabled by setting the value of the environment variables JAVA_DEBUG to true and JAVA_DEBUG_PORT to 9009, respectively.

Note

If the JAVA_DEBUG variable is set to true and no value is provided for the JAVA_DEBUG_PORT variable, JAVA_DEBUG_PORT is set to 5005 by default.

4.2.1. Prepare for Deployment

  1. Log in to the OpenShift instance by running following command and providing credentials. 

    $ oc login

  2. Create a new project: 

    $ oc new-project js2i-remote-debug-demo

4.2.2. Deployment

4.2.2.1. Enabling Remote Debugging for a New Application

  1. Create a new application using the Java S2I for OpenShift image and example Java source code. Ensure that JAVA_DEBUG and JAVA_DEBUG_PORT environment variables are set properly when creating the application. 

    $ oc new-app redhat-openjdk18-openshift~https://github.com/jboss-openshift/openshift-quickstarts.git \
  --context-dir=undertow-servlet \
  -e JAVA_DEBUG=true \
  -e JAVA_DEBUG_PORT=9009

    Proceed to Connect local debugging port to a port on the pod.

4.2.2.2. Enabling Remote Debugging for an Existing Application

  1. Switch to the appropriate OpenShift project. 

     $ oc project js2i-remote-debug-demo

  2. Retrieve the name of the deployment config. 

     $ oc get dc -o name
 deploymentconfig/openshift-quickstarts

  3. Edit the deployment config with the proper setting of JAVA_DEBUG and JAVA_DEBUG_PORT variables. 

    $ oc env dc/openshift-quickstarts -e JAVA_DEBUG=true -e JAVA_DEBUG_PORT=9009

    Proceed to Connect local debugging port to a port on the pod.

4.2.2.3. Connect Local Debugging Port to a Port on the Pod

  1. Get the name of the pod running the application. 

    $ oc get pods
NAME                            READY     STATUS      RESTARTS   AGE
openshift-quickstarts-1-1uymm   1/1       Running     0          3m
openshift-quickstarts-1-build   0/1       Completed   0          6m

  2. Use the OpenShift / Kubernetes port forwarding feature to listen on a local port and forward to a port on the OpenShift pod. 

    $ oc port-forward openshift-quickstarts-1-1uymm 5005:9009
Forwarding from 127.0.0.1:5005 -> 9009
Forwarding from [::1]:5005 -> 9009
Note

In the preceding example, 5005 is the port number on the local system, while 9009 is the remote port number of the OpenShift pod running the Java S2I for OpenShift image. Therefore, future debugging connections made to local port 5005 are forwarded to port 9009 of the OpenShift pod, running the Java Virtual Machine (JVM).

4.2.3. Post-Deployment

  1. Attach the debugger on the local system to the remote JVM running on the Java S2I for OpenShift image using the following command: 

    $ jdb -attach 5005
Set uncaught java.lang.Throwable
Set deferred uncaught java.lang.Throwable
Initializing jdb ...
>
...
    Note

    Once the local debugger to the remote OpenShift pod debugging connection is initiated, an entry similar to Handling connection for 5005 is shown in the console where the previous oc port-forward command was issued.

  2. Debug the application. 

    $ jdb -attach 5005
Set uncaught java.lang.Throwable
Set deferred uncaught java.lang.Throwable
Initializing jdb ...
> threads
Group system:
  (java.lang.ref.Reference$ReferenceHandler)0x79e Reference Handler            cond. waiting
  (java.lang.ref.Finalizer$FinalizerThread)0x79f  Finalizer                    cond. waiting
  (java.lang.Thread)0x7a0                         Signal Dispatcher            running
Group main:
  (java.util.TimerThread)0x7a2                    server-timer                 cond. waiting
  (org.jolokia.jvmagent.CleanupThread)0x7a3       Jolokia Agent Cleanup Thread cond. waiting
  (org.xnio.nio.WorkerThread)0x7a4                XNIO-1 I/O-1                 running
  (org.xnio.nio.WorkerThread)0x7a5                XNIO-1 I/O-2                 running
  (org.xnio.nio.WorkerThread)0x7a6                XNIO-1 I/O-3                 running
  (org.xnio.nio.WorkerThread)0x7a7                XNIO-1 Accept                running
  (java.lang.Thread)0x7a8                         DestroyJavaVM                running
Group jolokia:
  (java.lang.Thread)0x7aa                         Thread-3                     running
>
    Note

    For more information on connecting the IDE debugger of the Red Hat JBoss Developer Studio to the OpenShift pod running the Java S2I for OpenShift image, refer to Configuring and Connecting the IDE Debugger.

4.3. Example Workflow: Running Flat Classpath JAR on Java S2I for OpenShift

This tutorial describes the process of running flat classpath java applications on Java S2I for OpenShift.

4.3.1. Prepare for Deployment

  1. Log in to the OpenShift instance by running following command and providing credentials. 

    $ oc login

  2. Create a new project. 

    $ oc new-project js2i-flatclasspath-demo

4.3.2. Deployment

  1. Create a new application using the Java S2I for OpenShift image and Java source code. 

    $ oc new-app redhat-openjdk18-openshift~https://github.com/jboss-openshift/openshift-quickstarts.git --context-dir=undertow-servlet

  2. Retrieve the name of the build config. 

    $ oc get bc -o name
buildconfig/openshift-quickstarts

  3. Edit the build config by specifying values for the JAVA_MAIN_CLASS, MAVEN_ARGS, ARTIFACT_COPY_ARGS, JAVA_LIB_DIR, JAVA_APP_JAR, and JAVA_APP_DIR environment variables. 

    $ oc env bc/openshift-quickstarts \
-e JAVA_MAIN_CLASS=org.openshift.quickstarts.undertow.servlet.ServletServer \
-e MAVEN_ARGS="package -P flat-classpath-jar -Dcom.redhat.xpaas.repo.redhatga" \
-e ARTIFACT_COPY_ARGS="-r lib *.jar" \
-e JAVA_LIB_DIR=lib \
-e JAVA_APP_JAR=undertow-servlet.jar \
-e JAVA_APP_DIR=/deployments

  4. Rebuild the application using the updated build config. 

    $ oc start-build openshift-quickstarts --follow
    Note

    The --follow tag retrieves the build logs and shows them in the console.

4.3.3. Post Deployment

  1. Get the service name. 

    $ oc get service

  2. Expose the service as a route to be able to use it from the browser. 

    $ oc expose svc/openshift-quickstarts --port=8080

  3. Get the route. 

    $ oc get route
  4. Access the application in your browser using the URL (value of HOST/PORT field from previous command output).