This document describes how to build and run the Coherence Demonstration application. The application showcases Coherence general features, scalability capabilities, and new features of 12.2.1 version including:
- Cache Persistence
- Federation
- Java 8 Support
You can run the Coherence demonstration application either locally or through Kubernetes using the Oracle Coherence Operator.
When you run the application locally, it results in a single self-contained JAR, javadoc and source.
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: To run this demonstration locally, you require Oracle Coherence 12.2.1.3.0 version.
- Oracle Coherence Demonstration Application
To run the demonstration application, you must have the following software installed:
-
Java 8 or 11 SE Development Kit or Runtime environment.
You can download JDK 8 from:
You can download JDK 11 from:
-
Maven 3.5.4 or later version installed and configured.
-
Oracle Coherence 12.2.1.3.0 or later version installed.
You can download it 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/middleware/12213/coherence/manage/using-jmx-manage-oracle-coherence.htm#COHMG5583
-
VisualVM is not included in JDK 11. You can download and install VisualVM from https://visualvm.github.io. You must provide
-Dvisualvm.executable
to point to the VisualVM executable. -
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.4.1/docs/misc/faq.
Note: All code compiles to JDK 8 bytecode for compatibility with Coherence releases.
Ensure that the following environment variables are set in your configuation:
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.
You must have Coherence and Coherence-REST installed into your local maven repository. If not, execute the following commands with the version number of Coherence that you have installed in your configuration.
For Linux/UNIX/Mac OS:
mvn install:install-file -Dfile=$COHERENCE_HOME/lib/coherence.jar -DpomFile=$COHERENCE_HOME/plugins/maven/com/oracle/coherence/coherence/12.2.1/coherence.12.2.1.pom
mvn install:install-file -Dfile=$COHERENCE_HOME/lib/coherence-rest.jar -DpomFile=$COHERENCE_HOME/plugins/maven/com/oracle/coherence/coherence-rest/12.2.1/coherence-rest.12.2.1.pom
If you are using Coherence 12.2.1.4.0 or later version, run the following commands:
$ mvn install:install-file -Dfile=$COHERENCE_HOME/lib/coherence-http-grizzly.jar -DpomFile=$COHERENCE_HOME/plugins/maven/com/oracle/coherence/coherence-http-grizzly/12.2.1/coherence-http-grizzly.12.2.1.pom
For Windows OS:
mvn install:install-file -Dfile=%COHERENCE_HOME%\lib\coherence.jar -DpomFile=%COHERENCE_HOME%\plugins\maven\com\oracle\coherence\coherence\12.2.1\coherence.12.2.1.pom
mvn install:install-file -Dfile=%COHERENCE_HOME%\lib\coherence-rest.jar -DpomFile=%COHERENCE_HOME%\plugins\maven\com\oracle\coherence\coherence-rest\12.2.1\coherence-rest.12.2.1.pom
To run the application in Kubernetes using the Coherence Operator, you must ensure the following requirements:
-
Check Software Requirements and Runtime Environment Requirements in the Quick Start Guide.
-
Add the Helm repository. Execute the following commands to create a
coherence
helm repository:$ helm repo add coherence https://oracle.github.io/coherence-operator/charts $ helm repo update
Get the Coherence Docker image from the Oracle Container Registry:
- In a web browser, navigate to Oracle Container Registry and click Sign In.
- Enter your Oracle credentials or create an account if you don't have one.
- Search for coherence in the Search Oracle Container Registry field.
- Click
coherence
in the search result list. - On the Oracle Coherence page, select the language from the drop-down list and click Continue.
- Click Accept on the Oracle Standard Terms and Conditions page.
This action is required to allow the image to be pulled automatically when required using the Kubernetes secret.
Ensure that your local Kubernetes is enabled. If you are running Docker using Docker Desktop, select Enable Kubernetes in the Settings menu.
The Coherence Demonstration Application can be run locally or through Kubernetes using the Oracle Coherence Operator.
Build the application using Maven:
$ mvn clean install
The target
directory contains a list of files:
coherence-demo-{version}-SNAPSHOT.jar - Executable JAR file, see instructions below
coherence-demo-{version}-SNAPSHOT-javadoc.jar - javadoc
coherence-demo-{version}-SNAPSHOT-sources.jar - sources
Run the JAR file in the target
directory:
$ java -jar target/coherence-demo-3.0.0-SNAPSHOT.jar
If you are using JDK 11, use the following argument to start the VisualVM while running the JAR file:
java -Dvisualvm.executable=/u01/oracle/product/visualvm/visualvm_143/bin/visualvm -jar target/coherence-demo-3.0.0-SNAPSHOT.jar
-Dvisualvm.executable=/u01/oracle/product/visualvm/visualvm_143/bin/visualvm
in the command points to the path of the VisualVM executable.
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.
- Start VisualVM from the Tools menu.
- 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 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.
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:
$ java -Dhttp.hostname=myhostname -Dhttp.port=9000 -jar coherence-demo-3.0.0-SNAPSHOT.jar
By changing the http.hostname
you can access the application outside of
your local machine.
Default Cluster Names
When starting up the application, the timezone is analyzed and default names are selected for the primary and secondary cluster (see Launcher.java). If you want to customize the name, do the following:
$ java -Dprimary.cluster=NewYork -Dsecondary.cluster=Boston -jar coherence-demo-3.0.0-SNAPSHOT.jar
If you want to use a cluster name with a space, you must enclose it in quotes.
The steps to run the application on Kubernetes comprises the following Helm chart installs:
- Oracle Coherence Operator
- Coherence Cluster - storage-enabled Coherence servers
- Coherence Application Tier - storage-disabled with Grizzly HTTP Server
Note: If you want to enable Federation when running on Kubernetes, see Enable Federation on Kubernetes.
-
Create Namespace
Run the application using the Oracle Coherence Operator in a namespace calledcoherence-demo-ns
. Create the demonstration namespace:$ kubectl create namespace coherence-demo-ns namespace/sample-coherence-ns created
-
Create Secret
Create a secret for pulling the images from private repositories. For this application, create a secret namedcoehrence-demo-secret
in the namespacecoherence-demo-ns
.$ kubectl create secret docker-registry coherence-demo-secret \ --namespace coherence-demo-ns \ --docker-server=your-docker-server \ --docker-username=your-docker-username \ --docker-email=your-email-address \ --docker-password=your-docker-password
Note: By default, the Docker details must be your Oracle Container Registry details.
See https://kubernetes.io/docs/tasks/configure-pod-container/pull-image-private-registry/ for more information.
-
Build and Push Sidecar Docker Image
Build and push the sidecar Docker image(optional). The Oracle Coherence Operator requires a sidecar Docker image to be built containing the classes and configuration files required by the application.
Ensure that you have Docker running locally and execute the following command:
$ mvn clean install -P docker
This creates an image named coherence-demo-sidecar:3.0.0-SNAPSHOT
which contains cache configuration and Java classes to be added to the classpath at runtime.
Note: If you are running against a remote Kubernetes cluster, you need to push the sidecar Docker image to your repository accessible to that cluster. You also need to prefix the image name in your
helm
commands below.
-
Install the Oracle Coherence Operator
Install the operator usinghelm
:$ helm install \ --namespace coherence-demo-ns \ --set imagePullSecrets=coherence-demo-secret \ --name coherence-operator \ --set "targetNamespaces={coherence-demo-ns}" \ coherence/coherence-operator
Confirm the creation of the chart:
$ helm ls NAME REVISION UPDATED STATUS CHART APP VERSION NAMESPACE coherence-operator 1 Fri May 24 14:39:15 2019 DEPLOYED coherence-operator-0.9.4 0.9.4 coherence-demo-ns $ kubectl get pods -n coherence-demo-ns NAME READY STATUS RESTARTS AGE coherence-operator-5d4dc4546c-4c925 1/1 Running 0 50s
To enable log capture or metrics, see here for the list of samples.
-
Install the Coherence Cluster
Install the Coherence cluster:$ helm install \ --namespace coherence-demo-ns \ --name coherence-demo-storage \ --set clusterSize=1 \ --set cluster=PrimaryCluster \ --set imagePullSecrets=coherence-demo-secret \ --set store.cacheConfig=cache-config.xml \ --set store.pof.config=pof-config.xml \ --set store.javaOpts="-Dwith.http=false" \ --set store.maxHeap=512m \ --set userArtifacts.image=coherence-demo-sidecar:3.0.0-SNAPSHOT \ coherence/coherence
Note: By default, the latest version of the chart is used. You can add
--version 1.0.0
to select a specific version. For example, 1.0.0 is used in the command.You can also choose a specific version of the Coherence Docker image by specifying the following in the
helm install
command:--set coherence.image=container-registry.oracle.com/middleware/coherence:12.2.1.4.0
Use
kubectl get pods -n coherence-demo-ns
to ensure that the pod is running. The pod storage-coherence-0 must be running and ready as shown:NAME READY STATUS RESTARTS AGE coherence-demo-storage-0 1/1 Running 0 4m
If the pod does not show as
Running
, you can use the following command to diagnose and troubleshoot the pod:$ kubectl describe pod coherence-demo-storage-0 -n coherence-demo-ns
-
Install the Application Tier
Install the application tier using the following command:$ helm install \ --namespace coherence-demo-ns \ --name coherence-demo-app \ --set clusterSize=1 \ --set cluster=PrimaryCluster \ --set imagePullSecrets=coherence-demo-secret \ --set store.cacheConfig=cache-config.xml \ --set store.pof.config=pof-config.xml \ --set store.wka=coherence-demo-storage-headless \ --set store.javaOpts="-Dcoherence.distributed.localstorage=false" \ --set store.maxHeap=512m \ --set userArtifacts.image=coherence-demo-sidecar:3.0.0-SNAPSHOT \ coherence/coherence
-
Port Forward the HTTP Port
$ kubectl port-forward --namespace coherence-demo-ns coherence-demo-app-0 8080:8080
-
Access the Application
Use the following URL to access the application home page:
-
Scale the Appication
Scale the application usingkubectl
. When running the application in Kubernetes, the Add Server and Remove Server options are not available. You need to usekubectl
to scale the application.Scale the application to two nodes:
$ kubectl scale statefulsets coherence-demo --namespace coherence-demo-ns --replicas=2
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
- Release name: cluster-1
- Cluster name: PrimaryCluster
- Secondary Cluster
- Release name: cluster-2
- Cluster name: SecondaryCluster
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 calledcoherence-demo-ns
. Create the demonstration namespace:$ kubectl create namespace coherence-demo-ns namespace/sample-coherence-ns created
-
Create Secret
Create a secret for pulling the images from private repositories. For this application, create a secret namedcoherence-demo-secret
in the namespacecoherence-demo-ns
.$ kubectl create secret docker-registry coherence-demo-secret \ --namespace coherence-demo-ns \ --docker-server=your-docker-server \ --docker-username=your-docker-username \ --docker-email=your-email-address \ --docker-password=your-docker-password
Note: By default, the Docker details must be your Oracle Container Registry details. See https://kubernetes.io/docs/tasks/configure-pod-container/pull-image-private-registry/ for more information.
-
Build the sidecar image:
$ mvn clean install -P coherence12214,docker -Dcoherence.version=12.2.1-4-0
Note: The
coherence.version
must be set to your installed Coherence version. -
Install the Primary cluster:
$ helm install \ --namespace coherence-demo-ns \ --name cluster-1 \ --set clusterSize=1 \ --set cluster=PrimaryCluster \ --set imagePullSecrets=coherence-demo-secret \ --set store.cacheConfig=cache-config-12214.xml \ --set store.overrideConfig=tangosol-coherence-override-12214.xml \ --set store.pof.config=pof-config.xml \ --set store.maxHeap=512m \ --set store.javaOpts="-Dprimary.cluster=PrimaryCluster -Dprimary.cluster.port=40000 -Dprimary.cluster.host=cluster-1-coherence-headless -Dsecondary.cluster=SecondaryCluster -Dsecondary.cluster.port=40000 -Dsecondary.cluster.host=cluster-2-coherence-headless" \ --set store.ports.federation=40000 \ --set userArtifacts.image=coherence-demo-sidecar:3.0.0-SNAPSHOT \ --set coherence.image=your-12.2.1.4.0-Coherence-image \ coherence/coherence
Replace
your-12.2.1.4.0-Coherence-image
with a Coherence 12.2.1.4.0 image such ascontainer-registry.oracle.com/middleware/coherence:12.2.1.4.0
when it is released. -
Port forward the Primary Cluster - Port 8088
$ kubectl port-forward --namespace coherence-demo-ns cluster-1-coherence-0 8080:8080
Use the following URL to access the application home page:
-
Install the Secondary cluster
$ helm install \ --namespace coherence-demo-ns \ --name cluster-2 \ --set clusterSize=1 \ --set cluster=SecondaryCluster \ --set imagePullSecrets=coherence-demo-secret \ --set store.cacheConfig=cache-config-12214.xml \ --set store.overrideConfig=tangosol-coherence-override-12214.xml \ --set store.pof.config=pof-config.xml \ --set store.javaOpts="-Dwith.data=false -Dprimary.cluster=PrimaryCluster -Dprimary.cluster.port=40000 -Dprimary.cluster.host=cluster-1-coherence-headless -Dsecondary.cluster=SecondaryCluster -Dsecondary.cluster.port=40000 -Dsecondary.cluster.host=cluster-2-coherence-headless" \ --set store.ports.federation=40000 \ --set userArtifacts.image=coherence-demo-sidecar:3.0.0-SNAPSHOT \ --set coherence.image=your-12.2.1.4.0-Coherence-image \ coherence/coherence
-
Port forward the Secondary Cluster - Port 8090
$ kubectl port-forward --namespace coherence-demo-ns cluster-2-coherence-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.
Execute the following commands to delete the chart installed in this sample:
Without Federation
$ helm delete coherence-operator coherence-demo-storage coherence-demo-app --purge
With Federation
$ helm delete coherence-operator cluster-1 cluster-2 --purge
Before starting another sample, ensure that all the pods are removed from the previous sample.
If you want to remove the coherence-operator
, then include it in the helm delete
command.
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/middleware/12213/coherence/docs.htm
- Coherence Community - http://coherence.oracle.com/
- Coherence Operator GitHub Page - https://github.com/oracle/coherence-operator
- Coherence Operator Documentation - https://oracle.github.io/coherence-operator/