TomEE cartridge for openshift
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Failed to load latest commit information.

OpenShift TomEE Community Cartridge

The tomee cartridge provides TomEE on OpenShift via a manual tomee install.

This cartridge has special functionality to enable integration with OpenShift and with other cartridges. See the Cartridge Integrations and Environment Variable Replacement Support sections for details.

Template Repository Layout

webapps/           Location for built WARs (details below)
.openshift/        Location for OpenShift specific files
  config/          Location for configuration files such as server.xml, tomee.xml
  action_hooks/    See the Action Hooks documentation [1]
  markers/         See the Markers section [2]

[1] Action Hooks documentation [2] Markers

Note: Every time you push, everything in your remote repo directory is recreated. Please store long term items (like an sqlite database) in the OpenShift data directory, which will persist between pushes of your repo. The OpenShift data directory is accessible via an environment variable OPENSHIFT_DATA_DIR.

Layout and deployment option details

Contrary to the tomcat community cartridge, the prefered way to deploy your application is to put your wars in the webapps directory.

  1. You can commit pre-built wars into webapps.

Basic workflows for deploying pre-built content (each operation will require associated Git add/commit/push operations to take effect):

  1. Add new zipped content and deploy it:
  • cp target/example.war webapps/
  1. Undeploy currently deployed content:
  • git rm webapps/example.war
  1. Replace currently deployed zipped content with a new version and deploy it:
  • cp target/example.war webapps/

Note: You can get the information in the uri above from running rhc domain show

Note 2: To deploy at /, name your war ROOT.war

If you have already committed large files to your Git repo, you rewrite or reset the history of those files in Git to an earlier point in time and then git push --force to apply those changes on the remote OpenShift server. A git gc on the remote OpenShift repo can be forced with (Note: tidy also does other cleanup including clearing log files and tmp dirs):

rhc app tidy -a appname

The webapps directory is the location end users can place their deployment content (e.g. war, ear, jar, sar files) to have it automatically deployed into the server runtime.

Environment Variables

The Tomcat cartridge provides several environment variables to reference for ease of use:

OPENSHIFT_TOMEE_IP                   The IP address used to bind TOMEE
OPENSHIFT_TOMEE_HTTP_PORT            The TOMEE listening port
OPENSHIFT_TOMEE_CLUSTER_PORT         The listening private port used for clustering
OPENSHIFT_TOMEE_CLUSTER_PROXY_PORT   The public port used for clustering
OPENSHIFT_TOMEE_JPDA_PORT            The TOMEE JPDA listening port

For more information about environment variables, consult the OpenShift Application Author Guide.

Environment Variable Replacement Support

The tomee cart provides special environment variable replacement functionality for some of the Tomcat configuration files. For the following configuration files:

  • .openshift/config/server.xml
  • .openshift/config/server.xml.cluster
  • .openshift/config/context.xml

Ant-style environment replacements are supported for all OPENSHIFT_-prefixed environment variables in the application. For example, the following replacements are valid in server.xml:

  <Connector address="${OPENSHIFT_TOMEE_IP}"
             redirectPort="8443" />

During server startup, the configuration files in the source repository are processed to replace OPENSHIFT_* values, and the resulting processed file is copied to the live Tomcat configuration directory.


Adding marker files to .openshift/markers will have the following effects:

enable_jpda          Will enable the JPDA socket based transport on the java virtual
                     machine running the Tomcat server. This enables
                     you to remotely debug code running inside Tomcat.

java7                Will run Tomcat with Java7 if present. If no marker is present
                     then the baseline Java version will be used (currently Java6)


Tomcat clustering is not enable by default. To enable it, use the server.xml.cluster:

cp .openshift/config/server.xml.cluster .openshift/config/server.xml
git commit -am "use tomcat clustering"
git push

To run session replication in the tomee cart, the following steps should be completed:

  • All your session attributes must implement
  • Make sure your web.xml has the element

Clustering is done thanks to

Install system dependecies

$ yum install bc java-1.6.0-openjdk-devel java-1.7.0-openjdk-devel

Download TomEE 1.5 and TomEE 1.6 and install them in /opt/apache-tomee-X.Y

$ cd /opt
$ wget
$ tar xvzf apache-tomee-1.5.1-jaxrs.tar.gz
$ ln -s /opt/apache-tomee-jaxrs-1.5.1 /opt/apache-tomee-1.5
$ wget
$ tar xvzf apache-tomee-1.6.0-20130703.041224-115-jaxrs.tar.gz
$ ln -s /opt/apache-tomee-jaxrs-1.6.0-SNAPSHOT apache-tomee-1.6

Test as a download cartridge

Make sure this option is enable the the broker config.


Then create a cartridge with this URL:

Install as a RPM

Build the RPM.

$ yum install tito
$ tito init # only the first time you use tito for this cartridge
$ tito tag
$ tito build --rpm --test
Successfully built: /tmp/tito/openshift-origin-cartridge-tomee-0.6.7-1.git.0.3ad7ce3.el6.src.rpm /tmp/tito/noarch/openshift-origin-cartridge-tomee-0.6.7-1.git.0.3ad7ce3.el6.noarch.rpm

On the node

$ yum install /tmp/tito/noarch/openshift-origin-cartridge-tomee-0.6.7-1.git.0.3ad7ce3.el6.noarch.rpm

On the broker

$ oo-admin-broker-cache --clear --console