Apache TomEE

Sign in to the AWS Management Console, open the EC2 service, and select Launch instance. Under Application and OS Images, choose AWS Marketplace AMIs and search for Apache TomEE. Select the SecureAnyCloud listing, choose Select, and then choose Continue on the subscription summary.

Complete the launch wizard:

• Name: give the instance a name you will recognise, for example tomee-prod-1.
• Instance type: m5.large is the recommended type. TomEE is a JVM application server, so give it at least 2 vCPU and 8 GiB of memory for anything beyond evaluation.
• Key pair: select your existing EC2 key pair. You need it for SSH.
• Network settings: choose your VPC and subnet. Create or select a security group that allows inbound TCP 22 from your management network and inbound TCP 80 from the networks your users will come from.
• Configure storage: the image defines a 30 GiB root volume and a 30 GiB data volume for /var/lib/tomee. Increase the data volume now if you expect large deployments. You can also grow it later.

Choose Launch instance and wait for the instance to reach the Running state with 2/2 status checks passed.

To launch from the command line, run the following on your own machine. Substitute your own AMI ID, key pair, subnet and security group.

aws ec2 run-instances \
  --image-id <ami-id> \
  --instance-type m5.large \
  --key-name <your-key-pair> \
  --subnet-id <your-subnet-id> \
  --security-group-ids <your-security-group-id> \
  --tag-specifications 'ResourceType=instance,Tags=[{Key=Name,Value=tomee-prod-1}]'

Connect over SSH using the key pair you selected at launch. The login user depends on the operating system variant you launched.

Connecting to your instance

Operating system variant SSH login user

Ubuntu 24.04 LTS ubuntu

Run the following on your own machine, replacing the key path and address:

ssh -i /path/to/your-key.pem ubuntu@<public-ip>

If the connection is refused, confirm that the instance has finished its status checks and that your security group allows port 22 from your current address.

On the first boot of every instance, a one-shot systemd service generates a unique administrator password and writes it into the TomEE user realm. It also records the password in /root/tomee-credentials.txt with mode 0600. Read the file with sudo:

sudo cat /root/tomee-credentials.txt

The file records the console URLs, the administrator username, and the generated password. You can confirm which fields it holds without displaying the password itself:

sudo grep -oE '^[A-Z_]+=' /root/tomee-credentials.txt

TOMEE_URL= TOMEE_MANAGER_URL= TOMEE_HOST_MANAGER_URL= TOMEE_ADMIN_USERNAME= TOMEE_ADMIN_PASSWORD=

The administrator username is admin. Store the password in your password manager. It is unique to this instance and is not recorded anywhere else.

Confirm both services are running:

systemctl is-active tomee.service nginx.service

active active

Check the version of TomEE and the JVM it is running on:

sudo CATALINA_HOME=/opt/tomee /opt/tomee/bin/version.sh 2>/dev/null | grep -E 'Server version|JVM Version'

Server version: Apache Tomcat (TomEE)/10.1.57 (10.2.0) JVM Version: 17.0.19+10-1-24.04.2-Ubuntu

Confirm the listener layout. nginx is public on port 80, while TomEE is bound to loopback on 8080:

ss -tln | grep -E ':80 |:8080 '

LISTEN 0 511 0.0.0.0:80 0.0.0.0:* LISTEN 0 511 [::]:80 [::]:* LISTEN 0 100 [::ffff:127.0.0.1]:8080 *:*

The [::ffff:127.0.0.1]:8080 form is the IPv4-mapped IPv6 address the JVM binds when listening on loopback. What matters is that 8080 is not bound to 0.0.0.0.

Confirm CATALINA_BASE is on its own EBS volume:

findmnt -no SOURCE,TARGET,FSTYPE,SIZE /var/lib/tomee

/dev/nvme1n1 /var/lib/tomee ext4 29.4G

Check the unauthenticated health endpoint that nginx serves directly:

curl -s -o /dev/null -w 'health endpoint: HTTP %{http_code}\n' http://127.0.0.1/health

health endpoint: HTTP 200

Point an Elastic Load Balancing target group or an Auto Scaling health check at this endpoint.

The Manager console rejects an incorrect password and accepts the generated one. You can check both cases without ever printing the password:

PW=$(sudo grep '^TOMEE_ADMIN_PASSWORD=' /root/tomee-credentials.txt | cut -d= -f2-)
curl -s -o /dev/null -w 'wrong password -> HTTP %{http_code}\n' -u 'admin:not-the-real-password' http://127.0.0.1/manager/text/list
curl -s -o /dev/null -w 'correct password -> HTTP %{http_code}\n' -u "admin:$PW" http://127.0.0.1/manager/text/list

wrong password -> HTTP 401 correct password -> HTTP 200

List the deployed applications through the Manager text interface:

PW=$(sudo grep '^TOMEE_ADMIN_PASSWORD=' /root/tomee-credentials.txt | cut -d= -f2-)
curl -s -u "admin:$PW" http://127.0.0.1/manager/text/list

OK - Listed applications for virtual host [localhost] /sample:running:3:sample /host-manager:running:0:host-manager /:running:0:ROOT /manager:running:2:manager /docs:running:0:docs

Open http://<public-ip>/manager/html in a browser. Your browser prompts for HTTP Basic credentials. Sign in as admin with the password from Step 4.

The Applications table lists every deployed context and lets you start, stop, reload and undeploy each one. The Deploy panel below it uploads a WAR directly from your browser. Server Information at the foot of the page confirms the TomEE version, the JVM and the operating system.

The Server Status page shows live JVM memory and connector throughput:

The JVM memory line reflects the heap settings the image applies through the systemd unit, which are an initial heap of 256 MiB and a maximum of 1024 MiB. Step 10 explains how to change them for a larger instance type.

The host-manager console at http://<public-ip>/host-manager/html manages virtual hosts and uses the same administrator credentials.

The image deploys a small Jakarta EE sample application so the Manager shows a real running deployment out of the box. Browse to http://<public-ip>/sample/:

The page renders values evaluated at request time by the server: the current time, the JVM version and the reported server identity. They confirm that JSP compilation and request handling work end to end.

The sample application is there for verification only. Once you have deployed your own application, you can remove it from the Manager's Applications table with Undeploy on the /sample row, or from the command line:

PW=$(sudo grep '^TOMEE_ADMIN_PASSWORD=' /root/tomee-credentials.txt | cut -d= -f2-)
curl -s -u "admin:$PW" 'http://127.0.0.1/manager/text/undeploy?path=/sample'

There are three ways to deploy a WAR. Run these commands when you are ready. They change the state of your server, so they are not part of the verification steps above.

From the Manager console. Open http://<public-ip>/manager/html, scroll to WAR file to deploy, choose your .war file and select Deploy. The application appears in the Applications table and is served at the context path matching the WAR filename.

By copying the WAR onto the data volume. TomEE watches CATALINA_BASE/webapps and deploys anything dropped there. Copy the file up from your machine and move it into place:

scp -i /path/to/your-key.pem myapp.war ubuntu@<public-ip>:/tmp/
sudo install -o tomee -g tomee -m 0640 /tmp/myapp.war /var/lib/tomee/webapps/myapp.war

The application is deployed within a few seconds and served at http://<public-ip>/myapp/.

Through the Manager text interface, which is convenient from a CI pipeline:

PW=$(sudo grep '^TOMEE_ADMIN_PASSWORD=' /root/tomee-credentials.txt | cut -d= -f2-)
curl -s -u "admin:$PW" -T myapp.war 'http://127.0.0.1/manager/text/deploy?path=/myapp&update=true'

Because /var/lib/tomee/webapps lives on the dedicated data volume, deployed applications survive an instance stop and start. An EBS snapshot of that volume alone captures them.

The service unit sets an initial heap of 256 MiB and a maximum of 1024 MiB, which suits evaluation and small workloads. On a larger instance type, raise the ceiling. Edit the unit and restart:

sudo systemctl edit --full tomee.service

Change the CATALINA_OPTS line, keeping the surrounding double quotes exactly as they are:

Environment="CATALINA_OPTS=-server -Xms1024m -Xmx4096m -Djava.security.egd=file:/dev/urandom"

The quotes are required. A systemd Environment= value that is not quoted is split on whitespace and only the first token survives. That would silently discard every heap flag while the service still appears to start normally.

Then apply the change:

sudo systemctl daemon-reload
sudo systemctl restart tomee.service

Confirm the new values on the Server Status page, or from the running process.

The image serves plain HTTP on port 80. Put TLS in front of it before exposing the server to production traffic.

The simplest route is a certificate from Let's Encrypt terminated at nginx. It requires a DNS name pointing at the instance and inbound port 443 open in the security group.

sudo apt-get update
sudo apt-get install -y certbot python3-certbot-nginx
sudo certbot --nginx -d tomee.example.com

Certbot edits the nginx site in place, adds the TLS listener and installs a renewal timer. The proxy configuration to TomEE is untouched, so you need no TomEE change.

If you terminate TLS at an Application Load Balancer instead, point the target group at port 80 with /health as the health check path, and leave the instance configuration as it is.

Back up the data volume. Everything that is yours, including deployed applications, configuration and logs, lives on the EBS volume mounted at /var/lib/tomee. A snapshot of that volume captures the full application state:

aws ec2 create-snapshot \
  --volume-id <data-volume-id> \
  --description "TomEE application data $(date -u +%F)"

Schedule these snapshots with Amazon Data Lifecycle Manager or AWS Backup for policy-driven retention.

Apply operating system updates on your normal patching schedule:

sudo apt-get update
sudo apt-get -y upgrade

Read the server logs. TomEE writes to CATALINA_BASE/logs on the data volume, and the systemd journal carries the service-level record:

sudo tail -n 100 /var/lib/tomee/logs/catalina.out
sudo journalctl -u tomee.service -n 100 --no-pager