Tomcat/TomEE Cluster

Tomcat/TomEE Cluster

Tomcat and TomEE auto-clustering provides a highly available Java hosting topology designed for performance, horizontal scalability, and fault tolerance. The platform automates cluster creation, session replication, load balancing, firewall configuration, and scaling integration.

In this article

Cluster Goals and Overview

Apache Tomcat is a lightweight and widely used Java application server. TomEE extends Tomcat with enterprise technologies required by Jakarta EE applications. The automated cluster solution is designed around three main requirements:

PerformanceEfficient processing of a large number of requests.
ScalabilityHorizontal expansion when the application workload grows.
Fault toleranceContinued application availability when a compute node fails.
✓

Automated configuration

The platform reduces a complex manual Tomcat clustering setup to a topology option that can be enabled during environment creation.

Tomcat/TomEE Auto-Cluster Installation

1

Open the environment wizard

Sign in to the platform dashboard and click New Environment.

New Environment button
Open the environment topology wizard from the dashboard.
2

Select Tomcat or TomEE

Open the Java application-server list, select Tomcat or TomEE, enable the Auto-Clustering switch, configure the remaining topology options, and click Create.

Tomcat auto-clustering topology
Enable Auto-Clustering for the selected Tomcat or TomEE application server.
3

Wait for automatic provisioning

The platform creates the clustered environment and displays it in the dashboard after provisioning finishes.

Tomcat cluster created
The automatically configured Tomcat/TomEE cluster appears in the dashboard.

Tomcat/TomEE Cluster Topology

The default topology uses an NGINX load balancer in front of multiple Tomcat or TomEE application-server nodes. The balancer distributes requests and automatically tracks nodes added, removed, or unavailable.

Tomcat and TomEE cluster scheme
NGINX distributes application traffic between the clustered Tomcat or TomEE nodes.
NGINX load balancerDistributes incoming traffic and reacts to compute-node changes or failures.
Application nodesMultiple Tomcat or TomEE instances process requests and participate in replication.
Automatic discoveryThe cluster configuration is updated as nodes are added or removed.
High availabilityRemaining nodes continue serving the application when one instance becomes unavailable.

Session Replication and Cluster Configuration

Auto-Clustering creates a simple TCP cluster that connects Tomcat servers and transfers session changes between instances. Sender and receiver channels are established after the nodes connect.

  • Session replication between application-server instances
  • Context attribute replication
  • Cluster-wide WAR file deployment
  • Data-transfer interceptors
  • Automatic membership and firewall configuration

Cluster-specific settings are stored in:

/opt/tomcat/conf/tomcat-cluster.xml
Tomcat cluster configuration file
Cluster-specific settings are grouped in tomcat-cluster.xml.
Channel send optionsThe simple TCP cluster uses channelSendOptions="6", equivalent to synchronous transfer with acknowledgement.
Static membershipEach node stores the complete cluster-member list, including member IP addresses and unique IDs.
TCP port 4004Cluster nodes communicate through TCP port 4004, and the required firewall rule is added automatically.
Replicated contextThe context configuration uses org.apache.catalina.ha.context.ReplicatedContext.
Tomcat static cluster members
Static cluster membership lists the participating nodes by IP address and unique ID.
Tomcat replicated context configuration
The replicated context implementation is configured in context.xml.
i

No routine manual maintenance required

The platform applies these settings during cluster creation and updates the cluster configuration automatically during its lifecycle.

Tomcat/TomEE Cluster Horizontal Scaling

Automatic horizontal-scaling triggers can add or remove worker nodes according to changing application load.

1

Open Auto Horizontal Scaling

Go to Settings > Auto Horizontal Scaling for the Tomcat or TomEE cluster environment.

Tomcat cluster automatic horizontal scaling
Configure automatic scaling rules for the Tomcat/TomEE worker nodes.
2

Configure scaling triggers

Create triggers for the required resource type, such as RAM, CPU, network traffic, or disk usage. Define the thresholds, monitoring duration, node adjustment, and scaling limits.

!

Minimum worker-node count

The cluster must keep at least two worker nodes. Configure the scale-in limit so automatic scaling cannot reduce the application layer below this minimum.

Expected Result

A highly available Tomcat or TomEE environment is created with an NGINX load balancer, multiple application-server nodes, automatic session replication, cluster-wide deployment support, firewall configuration, and optional resource-based horizontal scaling.

Important Notes

  • Use TomEE for applications that require Jakarta EE enterprise technologies not included in standard Tomcat.
  • The cluster communicates internally through TCP port 4004.
  • Static membership is maintained automatically as cluster nodes change.
  • Session replication requires applications to use compatible serializable session data.
  • Keep at least two worker nodes in the cluster.
  • Review load-balancer and application logs after deployment or scaling changes.

Common Issues and Solutions

Sessions are not replicatedVerify that the application uses compatible session objects and review the Tomcat cluster configuration and logs.
Cluster members do not connectConfirm that TCP port 4004 is allowed and that each node contains the correct static membership information.
Traffic is not balancedCheck the NGINX node status, upstream configuration, application-node health, and load-balancer logs.
Scale-in removes too many nodesSet the minimum node limit to two or more in the automatic scaling configuration.
Application deployment differs between nodesUse the platform deployment workflow and review cluster-wide WAR deployment and application logs.