TomEE: Upgrading is Easy!

Apache TomEE has been designed from the ground up to be very easy to upgrade. This allows the open source project to innovate quickly and update often without major disruptions to our communities deployments. What follows are some simple tips that will help you upgrade when the time comes.

Drag and Drop Jars

Keeping a simple structure and remaining true to its Tomcat roots is a guiding principle for Apache TomEE. As a result, the folder structure for TomEE is simple, and easy to understand. Adding additional libraries, for example, a JDBC jar for a datasource defined in TomEE’s main configuration file, is usually a matter of simply adding the relevant jar file to the lib directory.

Upgrading Minor Versions

Upgrading between minor versions of TomEE only requires upgrading jars in the lib folder or extracting a fresh copy of TomEE and copying over your existing configuration from the conf directory and your applications from the webapps folder over.

Dealing with CLASSPATH issues

Keeping track of the libraries that come with TomEE and libraries added can be a little tricky, however, and we do occasionally see problems where a library hasn’t been copied over in an upgrade. Here’s a little tip that can help with this.

You can create additional lib directories and add them to the classpath. Doing this will enable you to separate out the jars you add for things like JDBC data sources from the jars that ship with TomEE. Catalina, a component of TomEE, helps with this.

Using Catalina to Update CLASSPATH

To do this, first of all, create the new directory you wish to use. In this example, I’ll call my new directory custom-lib, and I’ll create it under $CATALINA_HOME.

Next, the new folder needs to be added to the classpath, which you can do by editing the catalina.properties file in the conf directory. Look for the line that starts with common.loader=

For example:

common.loader=${catalina.base}/lib,${catalina.base}/lib/*.jar,
  ${catalina.home}/lib,${catalina.home}/lib/*.jar

This is a comma separated list of elements to include on the classpath. Note that the ${catalina.home}/lib folder and *.jar within that folder are both included on that line. Add entries for the new folder created, for example:

common.loader=${catalina.base}/lib,${catalina.base}/lib/*.jar,
  ${catalina.home}/lib,${catalina.home}/lib/*.jar,
  ${catalina.home}/custom-lib,${catalina.home}/custom-lib/*.jar

And that’s it – you can now deploy any additional jars in the new directory.

It’s also worth remembering that you can use the directories specified in CATALINA_HOME and CATALINA_BASE with TomEE in the same way as you can with a vanilla Tomcat installation, which may also help structure installations, particularly if you use multiple TomEE installations on the same server.