TomEE Server

Apache TomEE

Apache TomEE is an enterprise-ready Java application server built on Apache Tomcat and extended with MicroProfile and Jakarta EE functionality. The platform provides several TomEE distributions for different enterprise application requirements.

In this article

TomEE Overview

TomEE extends Apache Tomcat with enterprise Java technologies while remaining compatible with most Tomcat-aware and Tomcat-tested tools. It can run without additional runtime components and is suitable for both lightweight and enterprise Java applications.

i

Initialization system

The current TomEE template uses the modern systemd initialization daemon.

TomEE Distributions

WebProfileProvides Jakarta EE Web Profile technologies, including Servlets, JSP, JSF, JTA, JPA, CDI, Bean Validation, and EJB Lite.
MicroProfileExtends the WebProfile distribution with complete MicroProfile support.
PlusIncludes the MicroProfile technologies and adds JAX-WS, Jakarta EE Connectors, and JMS.
PluMEIncludes all Plus functionality together with Eclipse Mojarra and EclipseLink. It is designed for organizations migrating from Eclipse GlassFish to Apache TomEE.

Create a TomEE Environment

1

Open the environment wizard

Sign in to the platform dashboard and click New Environment.

Open the New Environment wizard
Start creating a new environment from the dashboard.
2

Select TomEE

Open the Java tab and select TomEE as the application server. Configure vertical and horizontal scaling, public IP addresses, the environment name, region, and other required settings.

TomEE environment topology wizard
Select TomEE and configure the environment topology.
3

Create the environment

Review the selected topology and click Create. The platform provisions the TomEE environment automatically.

Enable Auto-Clustering

The platform provides a one-click Auto-Clustering option for TomEE. When enabled, it automatically prepares a highly available Java cluster.

Enable TomEE auto-clustering
Enable Auto-Clustering to prepare interconnected TomEE nodes automatically.
✓

Cluster result

Auto-Clustering creates a scalable set of interconnected TomEE servers with preconfigured session replication and load balancing.

Open and Verify TomEE

After provisioning completes, the TomEE environment appears in the dashboard.

Open TomEE in browser
Use Open in Browser to access the deployed TomEE server.

Click Open in Browser to open the default TomEE page and confirm that the server is running.

Apache TomEE home page
The default TomEE page confirms successful installation.

Configure HOT_DEPLOY

Tomcat and TomEE provide an optional HOT_DEPLOY environment variable that controls whether the server is restarted during application deployment.

false, disabled, or 0Restarts the server during application deployment.
true, enabled, or 1Deploys the application without restarting the server.
TomEE HOT_DEPLOY environment variable
Configure HOT_DEPLOY when the application supports deployment without a restart.
!

Hot deployment is disabled by default

Restart-free deployment is faster and can avoid downtime, but some applications do not support it. Enable HOT_DEPLOY only after verifying application compatibility.

Expected Result

A ready-to-use Apache TomEE environment is created with the selected topology. It can be opened through the browser, scaled vertically or horizontally, configured as an automatically clustered deployment, and used for Java application deployment.

Important Notes

  • Select the TomEE distribution according to the enterprise Java features required by the application.
  • Use PluME when migrating an application that depends on Eclipse Mojarra or EclipseLink.
  • Review scaling and public-IP requirements before creating the environment.
  • Enable Auto-Clustering when session replication and load balancing are required.
  • Enable HOT_DEPLOY only for applications that support deployment without server restart.
  • Review application and server logs after deployment.

Common Issues and Solutions

Required TomEE profile is unclearCompare WebProfile, MicroProfile, Plus, and PluME against the application’s Jakarta EE and MicroProfile dependencies.
TomEE home page does not openCheck the node status, environment URL, Shared Load Balancer, public IP, and firewall configuration.
Application deployment failsVerify the archive format, deployment context, TomEE version, JDK compatibility, and deployment logs.
Sessions are lost between nodesEnable Auto-Clustering or configure another supported shared-session solution.
HOT_DEPLOY causes application errorsDisable HOT_DEPLOY and allow the server to restart during deployment.