Preparing a Clustered Application for Deployment

You can deploy a clustered application to Oracle Application Container Cloud Service with standard scaling of instances. The instances in a clustered application act as a single unit in response to client requests. Each instance replicates and thereby shares session data.

Benefits of clustered applications include:

  • Performance — Since more than one instance is available to perform a task or unit of work, response time is often faster.

  • Scaling — A clustered application can be scaled out with more and more instances to handle more and more work.

  • Load Balancing — When a request comes into a clustered application, the load balancer passes it to one of the instances. Load balancers can use anything from complex algorithms to a simple round robin approach to route traffic. Oracle Application Container Cloud Service uses Oracle Traffic Director for load balancing.

  • High Availability — Highly available systems are designed with redundancy that eliminates a single point of failure. In a clustered application, if one instance fails, the other instances continue running and take over the request processing that the failed instance was handling. From outside the application, there appears to be no change in the way it operates.

Setting the Mulitcast IP Address and Port

Your clustered instances must be able to discover each other in order to share session data. One way they can do this is to use multicasting.

To use multicasting, you must select the multicast IP address and port that your clustered application will use. For example, the default values used by Apache Tomcat are and 45564 respectively. Valid multicast IP addresses are described at the IPv4 Multicast Address Space Registry.

It is very important that the multicast IP address and port combination be unique in your identity domain. If different clusters use the same combination, they behave like a fused cluster, causing problems for all applications involved.

To avoid having to set the multicast IP address and port manually in each application instance, set them as environment variables in the deployment.json file and pass them to the application instances in the launch command. This is recommended as a best practice.

Like most Oracle Application Container Cloud Service applications, a clustered application must read the standard PORT environment variable, which is different from the multicast port.

For example, Tomcat stores the multicast IP address, multicast port, and standard PORT in the server.xml file. You can create a template of this file and use the launch command to copy this file for each instance and substitute environment variable values in each copy.

Copy the conf/server.xml file and create a new file named conf/server.template.xml. Edit the <Service name="Catalina"> section to reference the standard PORT environment variable:

<Connector port="__PORT__" protocol="HTTP/1.1" connectionTimeout="20000" ... >

Edit the <Engine name="Catalina" ... > subsection to reference the multicast IP address and port:

<Cluster className="org.apache.catalina.ha.tcp.SimpleTcpCluster">
   <Channel className="">
      <Membership className="org.apache.catalina.tribes.membership.McastService"

Use a sed command in the launch script that replaces the multicast address and port and the standard PORT with environment variables:

sed "s/__PORT__/${PORT}/g; s/__MIP__/${MIP}/g; s/__MPORT__/${MPORT}/g" conf/server.template.xml > conf/server.xml


For local testing, you can omit the sed command from the launch script and use the actual PORT, multicast IP, and multicast port values in the application.

For a full tutorial of how to create an example clustered application that uses multicasting based on Tomcat, see Tutorial icon Creating a Tomcat Cluster with TCP Session Replication.

Configuring a Web Application

For failover to work, a web application must have <distributable/> set in its web.xml file.

You can download a useful sample application based on Tomcat at

Configuring the Metadata Files and Creating the Archive

Set the following parameters in the manifest.json file using the launch command you need:

   "runtime": { 
      "majorVersion": "8"
   "command": "./", 
   "isClustered" : "true"

Set the following parameters in the deployment.json file using the values you need:

   "memory": "1G",
   "instances": "2", 
   "environment": {

For details about other possible parameters in the manifest.json and deployment.json files, see Creating Metadata Files.

You can include the manifest.json file at the root of the application archive, or you can reference it separately at deployment time. Do not include the deployment.json file, which must be referenced separately.

Deploying the Archive Using the Command-Line Interface

To deploy your cluster using the command-line interface, create your archive and place it in your Oracle Cloud Infrastructure Object Storage Classic account.

Then use the accs push command. See accs push in PSM CLI Reference.

Deploying the Archive Using the REST API

To deploy your cluster using the REST API, create your archive and place it in your Oracle Cloud Infrastructure Object Storage Classic account.

This example shows how to deploy a MyCluster by submitting a POST request using cURL. The archiveURL points to the location of your archive within your storage service account.

curl -X POST -u \
-H "X-ID-TENANT-NAME:ExampleIdentityDomain" \
-H "Content-Type: multipart/form-data" -F "name=MyCluster" \
-F "runtime=java" -F "subscription=Monthly" \
-F "deployment=@deployment.json" \
-F "archiveURL=mydomain/binaries/" \
-F "notes=notes for deployment" \

Any option on the command line (such as subscription or name) takes precedence over the same option in a metadata file, if there is a difference.

To learn more about the REST API, see REST API for Managing Applications.