Oracle Coherence Demonstration Application
Overview
This document describes how to build and run the Coherence Demonstration application. The application showcases Coherence general features, scalability capabilities including:
- Clustering and Data Sharding
- Scalability and High Availability
- Disk-Based Persistence
- Parallel Queries
- Efficient Aggregation
- In-Place Processing
- Federation (Grid Edition feature only)
- Lambda Support
- OpenTracing Support
You can run the application locally using mvn exec:exec
or run on Kubernetes using the Coherence Operator. See the table
of contents below for instructions.
The demonstration uses AngularJS 1.7.5, Bootstrap 3.3.4, and a number of other frameworks. The UI interacts with Coherence using the REST API.
Note: This demonstration uses the Coherence Community Edition and as a consequence the commercial-only feature "Federation" is not available by default.
Please see here if you wish to enable Federation by running using Coherence Grid Edition.
Table of Contents
- Oracle Coherence Demonstration Application
Prerequisites
General Prerequisites
To run the demonstration application, you must have the following software installed:
-
Java 11 SE Development Kit or Runtime environment.
You can download JDK 11 from Java SE Development Kit 11 Downloads
-
Maven 3.6.0 or later version installed and configured.
-
Use a web browser that supports AngularJS to run the application. The following browsers are supported:
- Safari, Chrome, Firefox, Opera 15, IE9 and mobile browsers (Android, Chrome Mobile, iOS Safari).
For more information about browser compatibility, see https://code.angularjs.org/1.7.5/docs/misc/faq.
Note: All code compiles to JDK 8 bytecode for compatibility with Coherence releases.
OpenTracing Prerequisites
If you wish to demonstrate OpenTracing, then prior to running the demo, start the Jaeger OpenTracing implementation:
docker run --rm -d --name jaeger \
-e COLLECTOR_ZIPKIN_HTTP_PORT=9411 \
-p 5775:5775/udp \
-p 6831:6831/udp \
-p 6832:6832/udp \
-p 5778:5778 \
-p 16686:16686 \
-p 14268:14268 \
-p 9411:9411 \
jaegertracing/all-in-one:1.13
Navigate to http://localhost:16686 in order to access the Jaeger UI.
Note: If Jaeger is already running in your environment locally, you can skip this step. If Jaeger is available
at a different location, specify the JAEGER_ENDPOINT
JVM property when starting the demo to override the default
location.
The following screenshot shows the Jaegar UI and a trace from a JAX-RS call to Coherence to JPA cache store, then backing up of cache entries across to another node.
Run the Application Locally
Build the application using Maven:
mvn clean install
The target
directory contains a list of files:
coherence-demo-{version}-SNAPSHOT-javadoc.jar - javadoc
coherence-demo-{version}-SNAPSHOT-sources.jar - sources
Run demo application
mvn exec:exec
The following screenshot shows the application running with 5 cache servers started.
A Coherence Cache server and HTTP server are started on port 8080 for serving REST and application data. When the Cache server starts, the application loads on the default web browser at http://127.0.0.1:8080/application/index.html.
The following features are available to demonstrate in the application:
- Dynamically add or remove cluster members and observe the data repartition and recover automatically.
- Create and recover snapshots from the Persistence menu.
- Enable real-time price updates.
- Enable or disable indexes for queries.
- Add additional data, clear the cache or populate the cache from the Tools menu.
- Show OpenTracing Support
- Open raw metrics endpoint
Federation Features - Grid Edition Only
- Start a secondary cluster from the Federation menu.
- Pause and resume replication to secondary cluster.
- Issue replicate all to secondary cluster.
- Open secondary cluster dashboard to observe changes are replicated.
- Stop Federation and shut down secondary cluster.
Note: If you wish to connect to the cluster via the VisualVM Plugin, see https://github.com/oracle/coherence-visualvm.
Note: If you recover a snapshot on a cluster, you must replicate all to resynchronize.
To shut down the application, select Shutdown option from the Tools menu. This shuts down all the processes including the secondary cluster if started.
Note: Secondary cluster will not form if you are running on a virtual private network due to security restrictions.
You can use the following to run the application with the Metrics
endpoint enabled:
mvn -Dmetrics.enabled=true exec:exec
From the Tools
menu choose Show Raw Metrics
to view the raw metrics.
Modify the Defaults
HTTP Ports and Hostname
The default HTTP hostname is 127.0.0.1 and default port is 8080. To modify these you can add the http.hostname
or http.port
properties on startup:
mvn -Dhttp.hostname=myhostname -Dhttp.port=9000 exec:exec
By changing the http.hostname
you can access the application outside of
your local machine.
Run the Application on Kubernetes
The steps to run the application on Kubernetes comprises the following:
- Oracle Coherence Operator Helm Chart
- Use
kubectl
to install the Coherence cluster which comprises of 2 roles:- storage-enabled Coherence servers
- storage-disabled application with Grizzly HTTP Server
Note: If you want to enable Federation when running on Kubernetes, see Enable Federation on Kubernetes.
-
Add Helm Repositories
You must have at least version v2.14.3 of
helm
, but these instructions are written for V3.3.+. See here for information on installing helm for your platform.Run the following to add the required helm repositories:
$ helm repo add stable https://charts.helm.sh/stable $ helm repo add coherence https://oracle.github.io/coherence-operator/charts $ helm repo update
Note: The
helm
commands below are for helm 3.3. Version 2 equivalent commands have also been included. -
Create Namespace
Run the application using the Oracle Coherence Operator in a namespace called
coherence-example
. Create the demonstration namespace:kubectl create namespace coherence-example namespace/coherence-example created
-
Build and Push Docker Image
Ensure that you have Docker running locally and execute the following command which will used the
jib-maven-plugin
to build a Docker image.mvn clean install -P docker
This creates an image named
coherence-demo:5.0.0-SNAPSHOT
which contains everything needed to run the demo.Note: If you are running against a remote Kubernetes cluster, you need to push the Docker image to your repository accessible to that cluster. You also need to prefix the image name in the
yaml
files used in thehelm
commands below. Find your Docker image id withdocker images
and tag it with your prefix:docker tag image youname/coherence-demo:5.0.0-SNAPSHOT
and them push usingdocker push youname/coherence-demo:5.0.0-SNAPSHOT
. -
Install the Oracle Coherence Operator
Install the operator using
helm
:helm install --namespace coherence-example coherence-operator coherence/coherence-operator
Confirm the creation of the chart:
helm ls --namespace coherence-example NAME NAMESPACE REVISION UPDATED STATUS CHART APP VERSION coherence-operator coherence-example 1 2021-01-12 15:25:04.409346768 +0800 AWST deployed coherence-operator-3.1.3 3.1.3 kubectl get pods --namespace coherence-example NAME READY STATUS RESTARTS AGE coherence-operator-cd9b646d5-p5xk8 1/1 Running 0 2m12s
For
helm
version 2.X:helm install --namespace coherence-example --name coherence-operator coherence/coherence-operator helm ls
-
Install the Coherence Cluster
The Coherence cluster comprises of 2 roles:
- storage - contains the storage-enabled tier which stores application data
- http - contains a storage-disabled http server which serves the application
The file demo-cluster.yaml contains the yaml to install the two Coherence cluster roles.
Issue the following command to install the Coherence cluster using the above yaml:
kubectl create --namespace coherence-example -f yaml/demo-cluster.yaml
Use
kubectl get pods --namespace coherence-example
to ensure that the pod is running. The pod primary-cluster-storage-0 must be running and ready as shown:NAME READY STATUS RESTARTS AGE coherence-operator-cd9b646d5-p5xk8 1/1 Running 0 33m primary-cluster-http-0 1/1 Running 0 3m2s primary-cluster-storage-0 1/1 Running 0 3m4s
If the pod does not show as
Running
, you can use the following command to diagnose and troubleshoot the pod:kubectl describe pod primary-cluster-storage-0 --namespace coherence-example
-
Port Forward the HTTP Port
kubectl port-forward --namespace coherence-example primary-cluster-http-0 8080:8080
-
Access the Application
Use the following URL to access the application home page:
-
Scale the Application
When running the application in Kubernetes, the Add Server and Remove Server options are not available. You need to use
kubectl
to scale the application.Scale the application to three nodes by editing
demo-cluster.yaml
and changing thereplicas
value for thestorage
role to 3. Then apply usingkubectl apply --namespace coherence-example -f yaml/demo-cluster.yaml
You can also use the following to scale the cluster:
kubectl scale --namespace coherence-example coherence/primary-cluster-storage --replicas=6
Use
kubectl --namespace coherence-example rollout status sts/primary-cluster-storage
to view the progress. -
Scale the Application down
Scale the application to one node by editing
demo-cluster.yaml
and changing thereplicas
value for thestorage
role to 1. Then apply usingkubectl apply --namespace coherence-example -f yaml/demo-cluster.yaml
Use
kubectl -n coherence-example rollout status sts/primary-cluster-storage
to view the progress.Note: The Coherence Operator ensures that all scale operations are carried out in a safe manner (checking service statusHA values) to ensure no data is lost. You can confirm this by checking the number of positions are the same as before the scale-down was initiated.
-
Uninstall the Coherence Cluster
Use the following to uninstall the Coherence cluster.
kubectl delete --namespace coherence-example -f yaml/demo-cluster.yaml
Enable Federation on Kubernetes (Grid Edition Only)
You must use Oracle Coherence 12.2.1.4.0 or later for Federation to work within Kubernetes.
The setup for this example uses two Coherence clusters in the same Kubernetes cluster. If you want to use Federation across Kubernetes cluster, see the Oracle Coherence Operator Samples.
- Primary Cluster
- Cluster name: primary-cluster
- Secondary Cluster
- Cluster name: secondary-cluster
Note: For this Federation example, the installation is simplified by using the storage-enabled pods to also serve the HTTP requests.
-
Create Namespace
Run the application using the Oracle Coherence Operator in a namespace called
coherence-example
. Create the demonstration namespace:kubectl create namespace coherence-example namespace/coherence-example created
-
Build the Docker image:
mvn clean install -P docker,grid-edition -Dcoherence.version={coherence-version}
Note: The
coherence.version
property must be set to your installed Coherence Grid Edition version. -
Install the Primary cluster:
The file primary-cluster.yaml contains the yaml to install the
primary-cluster
Coherence cluster.Issue the following command to install the Coherence cluster using the above yaml:
kubectl create --namespace coherence-example -f yaml/primary-cluster.yaml
Use
kubectl get pods --namespace coherence-example
to ensure that the pods are running.NAME READY STATUS RESTARTS AGE coherence-operator-cd9b646d5-tzf2j 1/1 Running 0 58m primary-cluster-http-0 1/1 Running 0 74s primary-cluster-storage-0 1/1 Running 0 76s
-
Port forward the Primary Cluster - Port 8088
kubectl port-forward --namespace coherence-example primary-cluster-http-0 8080:8080
Note: You may wish to run the above command in a separate terminal as it will block to process the HTTP requests.
Use the following URL to access the application home page:
-
Install the Secondary cluster
The file secondary-cluster.yaml contains the yaml to install the
secondary-cluster
Coherence cluster.Issue the following command to install the Coherence cluster using the above yaml:
kubectl create --namespace coherence-example -f yaml/secondary-cluster.yaml
Use
kubectl get pods --namespace coherence-example
to ensure that the pods are running.NAME READY STATUS RESTARTS AGE coherence-operator-cd9b646d5-tzf2j 1/1 Running 0 78m primary-cluster-http-0 1/1 Running 0 2m primary-cluster-storage-0 1/1 Running 0 2m primary-cluster-storage-1 1/1 Running 0 2ms secondary-cluster-http-0 1/1 Running 0 70s secondary-cluster-storage-0 1/1 Running 0 72s secondary-cluster-storage-1 1/1 Running 0 72s
-
Port forward the Secondary Cluster - Port 8090
kubectl port-forward --namespace coherence-example secondary-cluster-http-0 8090:8080
Use the following URL to access the application home page:
http://127.0.0.1:8090/application/index.html
You can see that there is no data in the Secondary cluster as the Federation is not yet started.
-
Start Federation on the Primary Cluster
In the Primary Cluster, select Start Federation from Federation menu. Access the Secondary Cluster dashboard and you can see the data appearing from the Primary Cluster.
-
Uninstall the Coherence Clusters
kubectl delete --namespace coherence-example -f yaml/primary-cluster.yaml kubectl delete --namespace coherence-example -f yaml/secondary-cluster.yaml
Before starting another sample, ensure that all the pods are removed from the previous sample.
Uninstalling the Coherence Operator
To remove the coherence-operator
, the use the following:
helm delete coherence-operator --namespace coherence-example
For helm
version 2.X:
helm delete coherence-operator --purge
Run the Demonstration using Coherence Grid Edition
If you wish to demonstrate the Federation feature, which is only available in Coherence Grid Edition, you must carry out the following steps.
Download Oracle Coherence 14.1.1.0.0 or later.
You can download Coherence from http://www.oracle.com/technetwork/middleware/coherence/downloads/index.html.
If you want to demonstrate the Coherence VisualVM plug-in, follow the instructions to install: https://docs.oracle.com/en/middleware/standalone/coherence/14.1.1.0/manage/using-jmx-manage-oracle-coherence.html
Set the Environment Variables
Ensure that the following environment variables are set in your configuration:
JAVA_HOME
-- This variable must point to the location of the JDK version supported by the Oracle Coherence version that you use. Ensure that the path is set accordingly:
For Linux/UNIX OS:
export PATH=$JAVA_HOME/bin:$PATH
For Windows OS:
set PATH=%JAVA_HOME%\bin;%PATH%
-
COHERENCE_HOME
-- This variable must point to the\coherence
directory of your Coherence installation. This is required for the Maveninstall-file
commands. -
MAVEN_HOME
-- Ifmvn
command is not set in your PATH variable, then setMAVEN_HOME
directed to thebin
folder of Maven installation and then addMAVEN_HOME\bin
to your PATH variable list.
Install Coherence JARs into your Maven repository
Install Coherence, Coherence-REST, Coherence Management and Coherence HTTP Netty installed into your local maven repository.
For Linux/UNIX/Mac OS:
mvn install:install-file -Dfile=$COHERENCE_HOME/lib/coherence.jar -DpomFile=$COHERENCE_HOME/plugins/maven/com/oracle/coherence/coherence/14.1.1/coherence.14.1.1.pom
mvn install:install-file -Dfile=$COHERENCE_HOME/lib/coherence-management.jar -DpomFile=$COHERENCE_HOME/plugins/maven/com/oracle/coherence/coherence-management/14.1.1/coherence-management.14.1.1.pom
mvn install:install-file -Dfile=$COHERENCE_HOME/lib/coherence-metrics.jar -DpomFile=$COHERENCE_HOME/plugins/maven/com/oracle/coherence/coherence-metrics/14.1.1/coherence-metrics.14.1.1.pom
mvn install:install-file -Dfile=$COHERENCE_HOME/lib/coherence-rest.jar -DpomFile=$COHERENCE_HOME/plugins/maven/com/oracle/coherence/coherence-rest/14.1.1/coherence-rest.14.1.1.pom
mvn install:install-file -Dfile=$COHERENCE_HOME/lib/coherence-http-netty.jar -DpomFile=$COHERENCE_HOME/plugins/maven/com/oracle/coherence/coherence-http-netty/14.1.1/coherence-http-netty.14.1.1.pom
For Windows OS:
mvn install:install-file -Dfile=%COHERENCE_HOME%\lib\coherence.jar -DpomFile=%COHERENCE_HOME%\plugins\maven\com\oracle\coherence\coherence\14.1.1\coherence.14.1.1.pom
mvn install:install-file -Dfile=%COHERENCE_HOME%\lib\coherence-management.jar -DpomFile=%COHERENCE_HOME%\plugins\maven\com\oracle\coherence\coherence-management\14.1.1\coherence-management.14.1.1.pom
mvn install:install-file -Dfile=%COHERENCE_HOME%\lib\coherence-metrics.jar -DpomFile=%COHERENCE_HOME%\plugins\maven\com\oracle\coherence\coherence-metrics\14.1.1\coherence-metrics.14.1.1.pom
mvn install:install-file -Dfile=%COHERENCE_HOME%\lib\coherence-rest.jar -DpomFile=%COHERENCE_HOME%\plugins\maven\com\oracle\coherence\coherence-rest\14.1.1\coherence-rest.14.1.1.pom
mvn install:install-file -Dfile=%COHERENCE_HOME%\lib\coherence-http-netty.jar -DpomFile=%COHERENCE_HOME%\plugins\maven\com\oracle\coherence\coherence-http-netty\14.1.1\coherence-http-netty.14.1.1.pom
grid-edition
profile
Build using the When you issue any maven commands, ensure you include the grid-edition
profile as below:
mvn clean install -P grid-edition -Dcoherence.version=14.1.1-0-0
Note: The
coherence.version
property must be set to your installed Coherence Grid Edition version.
Run the application using:
mvn exec:exec -Pgrid-edition -Dcoherence.version=14.1.1-0-0
View Cluster Metrics via Grafana
If you wish to view metrics via Grafana, please carry out the steps here before you install any of the examples above.
Note: Before you run the above, you must change the namespace in
src/main/yaml/prometheus-rbac.yaml
in the coherence-operator cloned repository fromcoherence-example
tocoherence-example
.
The following screenshot shows the application running within Oracle's Cloud Infrastructure (OCI) under Kubernetes.
References
For more information about Oracle Coherence, see the following links:
- Download Coherence - http://www.oracle.com/technetwork/middleware/coherence/downloads/index.html
- Coherence Documentation - https://docs.oracle.com/en/middleware/fusion-middleware/coherence/14.1.1.0/index.html
- Coherence Community - https://coherence.community/
- Coherence CE - https://github.com/oracle/coherence