Chapter 7. Running and Configuring the Intelligent Process Server xPaas Image

You can make changes to the Intelligent Process Server configuration in the xPaaS image using either the S2I templates, or by using a modified Intelligent Process Server image.

7.1. Using the Intelligent Process Server xPaaS Image Source-to-Image (S2I) Process

The recommended method to run and configure the OpenShift Intelligent Process Server xPaaS image is to use the OpenShift S2I process together with the application template parameters and environment variables.

The S2I process for the Intelligent Process Server xPaaS 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.

    • 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).
  2. The results of a successful Maven build are installed into the local Maven repository, /home/jboss/.m2/repository/, along with all dependencies for offline usage. The Intelligent Process Server xPaaS Image will load the created kjars from this local repository.

    • In addition to kjars resulting from the Maven build, any kjars found in the deployments source directory will also be installed into the local Maven repository. Kjars do not end up in the EAP_HOME/standalone/deployments/ directory.
  3. Any JAR (that is not a kjar), WAR, and EAR in the deployments source repository directory will be copied to the EAP_HOME/standalone/deployments directory and subsequently deployed using the JBoss EAP deployment scanner.
  4. All files in the configuration source repository directory are copied to EAP_HOME/standalone/configuration.
Note

If you want to use a custom JBoss EAP configuration file, it should be named standalone-openshift.xml. . All files in the modules source repository directory are copied to EAP_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.

7.2. Binary Builds

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

Prerequisite:

  1. Get the application archive or build the application locally.

    The following example uses both the library and library-client quickstarts.

    • Clone the source code.

      $ git clone https://github.com/jboss-openshift/openshift-quickstarts.git
    • Configure the Red Hat JBoss Middleware Maven repository.
    • Build the application — both the library and library-client quickstarts.

      Note

      The mvn clean package command output below has been shortened to contain just selected information.

      $ cd openshift-quickstarts/processserver/
      $ mvn clean package
      [INFO] Scanning for projects...
      ...
      [INFO]
      [INFO] --- maven-jar-plugin:2.4:jar (default-jar) @ processserver-timerprocess ---
      [INFO] Building jar: /tmp/openshift-quickstarts/processserver/timerprocess/target/processserver-timerprocess-1.4.0.Final.jar
      [INFO]
      [INFO] ------------------------------------------------------------------------
      [INFO] Building OpenShift Quickstarts: Intelligent Process Server: Parent 1.4.0.Final
      [INFO] ------------------------------------------------------------------------
      [INFO]
      [INFO] --- maven-clean-plugin:2.5:clean (default-clean) @ processserver-parent ---
      [INFO] ------------------------------------------------------------------------
      [INFO] Reactor Summary:
      [INFO]
      [INFO] OpenShift Quickstarts: Intelligent Process Server: Library SUCCESS [  1.212 s]
      [INFO] OpenShift Quickstarts: Intelligent Process Server: Library - Client SUCCESS [  7.827 s]
      [INFO] OpenShift Quickstarts: Intelligent Process Server: Timer Process SUCCESS [  1.965 s]
      [INFO] OpenShift Quickstarts: Intelligent Process Server: Parent SUCCESS [  0.002 s]
      [INFO] ------------------------------------------------------------------------
      [INFO] BUILD SUCCESS
      [INFO] ------------------------------------------------------------------------
      [INFO] Total time: 11.759 s
      [INFO] Finished at: 2017-06-05T10:26:06+02:00
      [INFO] Final Memory: 57M/598M
      [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 both the previously built JAR archive for the library quickstart (processserver-library-1.4.0.Final.jar), and WAR archive for the library-client quickstart (processserver-library-client-1.4.0.Final.war) to the deployments/ subdirectory:

    $ ls
    library  library-client  pom.xml  timerprocess
    $ mkdir -p ps-bin-demo/deployments
    $ cp library/target/processserver-library-1.4.0.Final.jar ps-bin-demo/deployments/
    $ cp library-client/target/processserver-library-client-1.4.0.Final.war ps-bin-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 7.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

Perform the following steps to run application consisting of binary input on OpenShift:

  1. Login into OpenShift instance.

    $ oc login
  2. Create a new project.

    $ oc new-project ps-bin-demo
  3. (Optional) Identify the image stream for the particular image.

    $ oc get is -n openshift | grep ^jboss-process | cut -f1 -d ' '
    jboss-processserver63-openshift
  4. Create new binary build, specifying image stream and application name.

    Note

    You can change the default user name and password to access the REST interface of the KIE server by providing custom values for KIE_SERVER_USER and KIE_SERVER_PASSWORD environment variables.

    $ oc new-build --binary=true \
    --name=ps-l-app \
    --image-stream=jboss-processserver63-openshift \
    -e KIE_SERVER_USER=kieserveruser \
    -e KIE_SERVER_PASSWORD=kieserverPwd1!
    --> Found image 78c88f3 (2 months old) in image stream "openshift/jboss-processserver63-openshift" under tag "latest" for "jboss-processserver63-openshift"
    
        JBoss BPMS Intelligent Process Server 6.3
        -----------------------------------------
        Platform for executing business rules on JBoss BPMS Intelligent Process Server 6.3.
    
        Tags: builder, processserver, processserver6
    
        * A source build using binary input will be created
          * The resulting image will be pushed to image stream "ps-l-app:latest"
          * A binary build was created, use 'start-build --from-dir' to trigger a new build
    
    --> Creating resources with label build=ps-l-app ...
        imagestream "ps-l-app" created
        buildconfig "ps-l-app" created
    --> Success
  5. 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.

    Note

    The output of the next command has been shortened for brevity.

    $ oc start-build ps-l-app \
    --from-dir=./ps-bin-demo/ \
    --follow
    Uploading directory "ps-bin-demo" as binary input for the build ...
    build "ps-l-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/processserver-library-client-1.4.0.Final.war' -> '/opt/eap/standalone/deployments/processserver-library-client-1.4.0.Final.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...
    '/home/jboss/source/deployments/processserver-library-1.4.0.Final.jar' -> '/opt/eap/standalone/deployments/processserver-library-1.4.0.Final.jar'
    /opt/eap/standalone/deployments/processserver-library-1.4.0.Final.jar is a kjar
    ...
    INFO: org.openshift.quickstarts:processserver-library:1.4.0.Final verified.
    Pushing image 172.30.82.129:5000/ps-bin-demo/ps-l-app:latest ...
    Pushed 0/9 layers, 0% complete
    Pushed 1/9 layers, 12% complete
    Pushed 2/9 layers, 33% complete
    Pushed 3/9 layers, 45% complete
    Pushed 4/9 layers, 64% complete
    Pushed 5/9 layers, 71% complete
    Pushed 6/9 layers, 80% complete
    Pushed 7/9 layers, 88% complete
    Pushed 8/9 layers, 100% complete
    Pushed 9/9 layers, 100% complete
    Push successful
  6. Create a new OpenShift application based on the build.

    $ oc new-app ps-l-app
    --> Found image 65a8367 (About a minute old) in image stream "ps-bin-demo/ps-l-app" under tag "latest" for "ps-l-app"
    
        ps-bin-demo/ps-l-app-1:0af8685b
        -------------------------------
        Platform for executing business rules on JBoss BPMS Intelligent Process Server 6.3.
    
        Tags: builder, processserver, processserver6
    
        * This image will be deployed in deployment config "ps-l-app"
        * Ports 8080/tcp, 8443/tcp, 8778/tcp will be load balanced by service "ps-l-app"
          * Other containers can access this service through the hostname "ps-l-app"
    
    --> Creating resources ...
        deploymentconfig "ps-l-app" created
        service "ps-l-app" created
    --> Success
        Run 'oc status' to view your app.
  7. Expose the service as route.

    $ oc get svc -o name
    service/ps-l-app
    $ oc expose svc/ps-l-app
    route "ps-l-app" exposed
    $ oc get route
    NAME       HOST/PORT                                    PATH      SERVICES   PORT       TERMINATION   WILDCARD
    ps-l-app   ps-l-app-ps-bin-demo.openshift.example.com             ps-l-app   8080-tcp                 None
  8. Access the application.

    You can get the list of available query string arguments of the library application by accessing the URL http://ps-l-app-ps-bin-demo.openshift.example.com/library.

    Run the library-client servlet using the URL http://ps-l-app-ps-bin-demo.openshift.example.com/library?command=runLocal.

    Note

    You may verify the current KIE server state by accessing dedicated server/ page of the REST API: http://ps-l-app-ps-bin-demo.openshift.example.com/kie-server/services/rest/server. Use aforementioned user name and password to access this page (or any REST API method of the server in general).