Prepare a Clustered Application for Deployment

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": "./start.sh", 
   "isClustered" : "true"
}

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

{
   "memory": "1G",
   "instances": "2", 
   "environment": {
      "MIP":"228.0.0.4",
      "MPORT":"45565"
   }
}

For details about other possible parameters in the manifest.json and deployment.json files, see Create 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.

To learn more about how to deploy an application, see Deploy an Application.

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 228.0.0.4 and 45564 respectively. Valid multicast IP addresses are described at the IPv4 Multicast Address Space Registry.

It’s 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="org.apache.catalina.tribes.group.GroupChannel">
      <Membership className="org.apache.catalina.tribes.membership.McastService"
         address="__MIP__"
         port="__MPORT__"
         frequency="500"
         dropTime="3000"/>
   </Channel>
</Cluster>

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

Note:

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 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 clusterjsp.zip.