Chapter 4. Tutorials
4.1. Example Workflow: Deploying BRMS Application on Decision Server xPaaS
This tutorial prepares a BRMS application to be deployed as Decision Server xPaaS image. The BRMS application may require modification to be deployed as an image.
Preparing the Application
The BRMS project must be configured to have a stateless knowledge session, use a remote repository, and have defined KIE container deployment.
Refer to the Red Hat JBoss BRMS User Guide for more information on any of these tasks.
- Log in to the BRMS console and edit the project settings in the Project Explorer.
Click Open Project Editor and in the Project Settings:
- Under Knowledge bases and sessions, ensure that the Knowledge Session is set to Stateless. OpenShift does not support stateful sessions on KIE servers.
Using Repository View, ensure the pom.xml is configured to use a remote repository by containing xml similar to the following:
... <distributionManagement> <repository> <id>deployment</id> <name>OpenShift Maven repo</name> <url>http://maven.example/content/repo/deployments/</url> </repository> <snapshotRepository> <id>deployment</id> <name>OpenShift Maven repo</name> <url>http://maven.example.xas/content/repo/snapshots/</url> </snapshotRepository> </distributionManagement> ...For more information, see the Red Hat JBoss BRMS Administration and Configuration Guide.
In the application’s repository, ensure the settings.xml and the .s2i/environment files define the Maven repository and the KIE container deployment respectively:
The Maven repository should be defined in the settings.xml so that OpenShift can download the application artefacts. It should contain xml similar to the following:
... <profiles> <profile> <id>openshift-mirror-repositories</id> <repositories> <repository> <id>openshift-mirror</id> <url>http://maven.example/content/group/public/</url> </repository> </repositories> <pluginRepositories> <pluginRepository> <id>openshift-mirror</id> <url>http://maven.example/content/group/public/</url> </pluginRepository> </pluginRepositories> </profile> </profiles> ...For more information, see the Red Hat JBoss BRMS Installation Guide.
The .s2i/environment file must define the KIE container deployment, including which KIE jars to use and the location from which to retrieve them. The pod name is derived from the deployment alias, which is defined as DemoContainer in this example:
KIE_CONTAINER_DEPLOYMENT_OVERRIDE=DemoContainer=com.example.openshift:example_workflow:1.0
4.1.1. Preparing Decision Server Deployment
Create a new project:
$ oc new-project rds-app-demo
Create a service account to be used for the deployment of the Decision Server application:
$ oc create serviceaccount rds-service-account
Add the view role to the service account. This enables the service account to view all the resources in the rds-app-demo namespace, which is necessary for managing the cluster.
$ oc policy add-role-to-user view system:serviceaccount:rds-app-demo:rds-service-account
The Decision Server template requires an SSL keystore and a JGroups keystore.
These keystores are expected even if the application will not use https.
This example uses ‘keytool’, a package included with the Java Development Kit, to generate self-signed certificates for these keystores. The following commands will prompt for passwords.Generate a secure key for the SSL keystore:
$ keytool -genkeypair -alias https -storetype JKS -keystore keystore.jks
Generate a secure key for the JGroups keystore:
$ keytool -genseckey -alias jgroups -storetype JCEKS -keystore jgroups.jceks
Use the SSL and JGroup keystore files to create the secret for the project:
$ oc create secret generic rds-app-secret --from-file=jgroups.jceks --from-file=keystore.jks
Add the secret to the service account created earlier:
$ oc secret add sa/rds-service-account secret/rds-app-secret
4.1.2. Deployment
- Log in to the OpenShift web console and select the rds-app-demo project space.
- Click Add to Project to list all of the default image streams and templates.
- Use the Filter by keyword search bar to limit the list to those that match
decisionserver. You may need to click See all to show the desired application template. - Select and configure the desired template and click Deploy.
During the build, the Maven repository is downloaded and build into the container so that no additional packages or dependencies are downloaded at runtime.
The application is available once the pod is running. To connect to the Decision Server web console, navigate to the pod and click Open Java Console button.
4.2. Example Workflow: Deploying an Upgraded Version Concurrently with Original Application
This example workflow follows on from Example Workflow: Deploying BRMS Application on Decision Server xPaaS, in which the 1.0 version of the example_workflow artifact was deployed with a deployment alias of DemoContainer. This example deploys a 1.1 version of the of the example_workflow artifact alongside the 1.0 version so that both versions of the example_workflow artifact are running simultaneously, both with the DemoContainer deployment alias.
- Update the repository with the new version of the server.
Edit the .s2i/environment file for the application:
- Change the KIE_CONTAINER_DEPLOYMENT variable to KIE_CONTAINER_DEPLOYMENT_OVERRIDE
Add the new version to the end of the value string, separated from the older version with a pipe.
KIE_CONTAINER_DEPLOYMENT_OVERRIDE=DemoContainer=com.example.openshift:example_workflow:1.0|DemoContainer=com.example.openshift:example_workflow:1.1
- Save the changes.
If the project has GitHub Webhooks configured, the new version will be deployed automatically alongside the older running applicaiton. Otherwise it can be manually built:
$ oc start-build rds-app-demo
Once the build has completed, the two different versions of the application will be running simultaneously using the same deployment alias. See Request Targeting for Multiple Versions for more information on how client requests are redirected to the correct version of the application.
4.3. Example Workflow: Deploying BRMS Application on Openshift with Webhooks Enabled for Automatic Application Updates
This workflow details how to configure BRMS, GitHub, and OpenShift to have your configuration changes automatically push to OpenShift. This example covers:
- Setting up a forked GitHub repository
- Cloning the repository
- Creating a hook in JBoss Decision Server to automatically update the GitHub repository
- Modifying the example JBoss Decision Server rules
- Creating a Decision Service on OpenShift
- Improving OpenShift build times using Maven
- Integrating the Maven Proxy
- Configuring the OpenShift webhook to automatically update the decision service OpenShift whenever a code change occurs in the GitHub repository
- Testing the configured service and hooks
Make sure you are running Red Hat JBoss BRMS on your local machine.
4.3.1. Forking the Repository
- Visit the Decision Server example page while you are logged in to GitHub.
You are redirected to your new fork.
- Copy the HTTPS clone URL for your fork.
This Decision Server example receives a name, and if it matches the user name specified as master in the rules file, then the user is recognized and greeted as the master user. If the name does not match, then the user is recognized as an intruder.
4.3.2. Cloning the Repository
From the Red Hat JBoss BRMS workbench:
- From the File Explorer, click Authoring → Administration.
- Click Repositories → Clone repository.
- Type the Repository Name
decision-services. - Select an Organizational Unit.
- Type in the HTTPS clone URL of your forked Git repository: https://github.com/<Your_Github_Username>/decisionserver.git
Click Clone.
Once cloned, the repository displays the commit history.
4.3.3. Creating a Hook to Automate GitHub Updates
To make Red Hat JBoss BRMS automatically update your GitHub repository any time a file in this project changes:
You must have SSH key access configured for GitHub before following these steps.
From the command line, navigate into the
/.niogitdirectory in the project you forked earlier:$ cd EAPHOME/bin/.niogit/decision-services.git
The path above is the default, which may differ depending on where the workbench has been configured to store its data. This location is set using the org.uberfire.nio.git.dir system property.
Set the remote URL for this project:
$ git remote set-url origin git@github.com:/decisionserver
Navigate into the hooks directory:
$ cd hooks
Create a simple post-commit file:
$ touch post-commit
Edit the file and type the following:
#!/bin/sh git push origin master
- Save your changes and exit the file.
Change the permissions on the file to allow BRMS the access it requires:
$ chmod 777 post-commit
The hook is now configured, meaning that any change to the files in this BRMS project will automatically update your forked decisionserver GitHub repository.
4.3.4. Modifying the Example Decision Server Rules
From the Red Hat JBoss BRMS workbench:
- Click Authoring → Project authoring.
Under DRL, click to load the HelloRules.drl file:
package org.openshift.quickstarts.decisionserver.hellorules query "get greeting"() greeting : Greeting() end rule "greet master" when person : Person( name == "john") then String salutation = "Hello " + person.getName() + "! What can I help you with today?"; insert(new Greeting(salutation)); end rule "greet strangers" when person : Person(name != "john") then String salutation = "Hey there " + person.getName() + ". I don't think I know you yet!"; insert(new Greeting (salutation)); end- Modify the lines with
johnby replacing them with your user name. Click Save, type a check in comment, and click Save again.
The hook you created earlier will automatically update your forked GitHub repository with these saved changes.
4.3.5. Creating a Decision Service on OpenShift
From the OpenShift web console:
- Log in using the username and password recommended to you by your administrator.
- To create a new project, click New Project.
- Type a unique name, display name, and description for the new project.
Click Create.
The web console’s welcome screen loads.
- Click Add to Project.
- In the Filter by keyword field, start typing
decisionto see the available xPaaS templates related to Decision Server. - Click the decisionserver63-basic-s2i template.
- In the Parameters section, change the KIE_SERVER_PASSWORD to the password to access the KIE Server REST or JMS interface.
Change the SOURCE_REPOSITORY_URL to the Git source URI for your forked repository. For example:
https://github.com/<your_github_username>/decisionserver.git
- Change the SOURCE_REPOSITORY_REF to
master. - Change the CONTEXT_DIR to
greeting. - Scroll to the bottom of the page and click Create.
While your application builds, you can click View Log from the Overview page to see the build progress.
4.3.6. Improving Build Time Using Maven
Follow the details in this OpenShift blog post to configure the Maven proxy, which improves the build times of java builds on OpenShift.
4.3.7. Integrating the Maven Proxy
To change the build configuration so that it uses the Maven proxy, complete the following from the OpenShift web console:
- Click Browse → Builds → <your_application>
- Click the three vertical dots next to Start Build and then click Edit (Raw).
Add the MAVEN_MIRROR_URL environment variable below the KIE_CONTAINER_DEPLOYMENT variable:
strategy sourceStrategy: env: - name: KIE_CONTAINER_DEPLOYMENT value: 'HelloRulesContainer=org.openshift.quickstarts:decisionserver-hellorules:1.2.0.Final' - name: MAVEN_MIRROR_URL value: 'http://nexus-ci.cloudapps.bos.openshift3roadshow.com/content/groups/public/'The value for MAVEN_MIRROR_URL can be found in Maven by viewing the repositories, then copying the path for the Public Repositories group.
- Click Save.
- Click the Configuration tab of your build to verify that MAVEN_MIRROR_URL is actively listed under Environment Variables.
Now that you have Maven configured for this OpenShift project, the build process will be shorter for all future builds. This is because subsequent builds only need to download updated files, which are then combined with the previously loaded files.
4.3.8. Test the Service
After integrating the Maven proxy, you can test that service is working and see how quickly the build process completes compared to previous builds. From the OpenShift web console:
- Click Browse → Builds → <your_application>
- Click Start Build.
- In the list at the bottom of the screen, click the new build you just started.
- Click the Logs tab, then click Follow.
Verify that the new build is using the new Maven proxy to download locally by finding the line in the log that references
Downloading. For example:I0130 12:32:25.664594 1 sti.go:492] Downloading: http://nexus-ci.cloudapps.openshift.com/content/groups/public/org/kie/kie-maven-plugin/6.3.0.Final-redhat-5/kie-maven-plugin-6.3.0.Final-redhat-5.pom
- When the build is complete, you can check the new build time against the previous build by clicking Browse → Builds → <your_application> and viewing the summary. The newest build will be considerably shorter with the Maven proxy in use.
- Click Overview to see the status of the pod. It displays a
Not Readystatus while it is checked with readiness probes. - Click Browse → Pods to follow its progress. The status of the Containers Ready column will change to
1/1when the pod has passed the readiness probes.
4.3.9. Configure the OpenShift Webhook
From the OpenShift web console:
- Click the Browse tab, then click Builds.
- Click your build name, then click the Configuration tab.
- Click the copy icon next to GitHub webhook URL to copy your webhook payload URL.
- Navigate to your forked repository on GitHub, then click Settings.
- Click Webhooks & Services.
- Click Add webhook.
- Paste your webhook URL into the Payload URL field.
- Click Disable SSL verification, then confirm it in the pop-up window.
- Click Add webhook to save.
Github pings the OpenShift server to ensure communication is successful. A green check mark next to the webhook URL signifies that it is configured correctly. Hover your cursor over the check mark to view the status of the last ping.
The next time you push a code change to your forked repository, your application will automatically rebuild.
4.3.10. Testing the Configured Hooks
From the Red Hat JBoss BRMS workbench:
Load the HelloRules.drl file:
package org.openshift.quickstarts.decisionserver.hellorules query "get greeting"() greeting : Greeting() end rule "greet master" when person : Person( name == "john") then String salutation = "Hello " + person.getName() + "! What can I help you with today?"; insert(new Greeting(salutation)); end rule "greet strangers" when person : Person(name != "john") then String salutation = "Hey there " + person.getName() + ". I don't think I know you yet!"; insert(new Greeting (salutation)); end- Modify the String salutation line by changing
At your service my masterto something else. - Click Save, type a check-in comment, and click Save again.
The hook that you created earlier updates your forked GitHub repository, and then the GitHub webhook triggers a new build in OpenShift.
With this configuration, you need only save your configuration changes on the Red Hat JBoss BRMS workbench, and the rest of the process is completely automated.
