TomEE: Fat-Jar Deployments

In this blog post, I will show you how to create a distribution of your application that ships with TomEE so you can run your application out of the box.

What is a Fat Jar?

Fat Jar, Uber Jar, Shaded Jar. These have different names, but all of them have the same meaning. It is simply a Jar file that contains all of your project class files, plus all the classes of the dependencies of the project.

This concept is not really new, it has been used for several years. However, with the growing popularity of cloud deployments and adoption of Microservices architectures, the Fat Jar has become a preferred way to distribute these applications.

How can we do it?

Building a Fat Jar with TomEE can be achieved by using the TomEE Maven Plugin. Simply add the following code to your pom.xml:

<plugin>
  <groupId>org.apache.tomee.maven</groupId>
  <artifactId>tomee-maven-plugin</artifactId>
  <version>7.0.5</version>
  <executions>
    <execution>
      <id>executable-jar</id>
      <goals>
        <goal>exec</goal>
      </goals>
      <phase>package</phase>
    </execution>
  </executions>
</plugin>

The trick here is to use the exec goal available in the plugin and associate it with the package lifecycle. When you build your application with a regular mvn clean package or install, the plugin will also generate the Fat Jar with the project name and append -exec to it into Maven target folder. Then you just need to execute the jar file and it will start up TomEE with your application in it.

Try it out!

You can find a demo sample project in this Github repository: https://github.com/tomitribe/tomee-fat-jar

You can clone the project with the command:

git clone https://github.com/tomitribe/tomee-fat-jar

Build it with:

mvn clean install

And you will notice the file tomee-fat-jar-1.0-SNAPSHOT-exec.jar in the target folder. Run it with:

java -jar tomee-fat-jar-1.0-SNAPSHOT-exec.jar

You should see the TomEE log output and the application deployment. It is just a simple echo endpoint. Use the following URL to check it out:

http://localhost:8080/tomee-fat-jar-1.0-SNAPSHOT/echo/hi

The jar is just a simple wrapper around the TomEE Catalina Runner. You can also run and stop the process in the background by executing:

java -jar tomee-fat-jar-1.0-SNAPSHOT-exec.jar start

And:

java -jar tomee-fat-jar-1.0-SNAPSHOT-exec.jar stop

Additional Configuration

While this is enough for a simple demo, additional configuration may be required for real projects. Maybe you need to add a datasource, change the TomEE flavor you are using or simply use a different port configuration. The plugin is very flexible and allows you to provide and override different configurations to suit your needs.

For instance, you can create a tomee.xml file with the required configuration needed by the application, add it to the project and have the plugin overwrite the default configuration with your own. If you use the default path and place the file in a src/main/tomee/conf directory, you won’t need to make any other changes. Otherwise, add the following to the plugin configuration:

<configuration>
  <!-- Folder where tomee.conf is stored -->
  <config>tomee/conf</config>
</configuration>

For a comprehensive list of allowed configurations, please check the tomee:exec documentation.

Conclusion

The Fat Jar is a convenient way to distribute standalone applications with the required configuration to run. In this way, operations teams or clients, don’t require extra set up steps to execute your application.

Combining Fat Jars with Docker containers, enhance the benefits even further and abstract almost 100% of your application.