TomEE

Boxfuse supports Java EE apps written in Java or any other language and packaged as a .war file running on TomEE 1.7.x or TomEE 7.0.x using either OpenJDK 7.x or 8.x.

If your .war file contains a WEB-INF/resources.xml file, Boxfuse will automatically run it using TomEE instead of Tomcat. By default it uses TomEE Web Profile, but it will automatically select TomEE Plus if you have defined any JMS resources.

 my-tomee-app
   src
     main
       java
       resources
       webapp
         WEB-INF
           resources.xml

You can override the automatic behavior and force a particular TomEE edition to be used by passing in -components.tomee-webprofile=1.7.4 (for TomEE Web Profile) or -components.tomee-plus=1.7.4 (for TomEE Plus).

Sample App

Tip: Check out our blog post on how to deploy TomEE Java EE applications on AWS using Boxfuse

You can find a TomEE sample app for Boxfuse on GitHub at boxfuse/boxfuse-samples/tomee.

Java Runtime Environment

By default Boxfuse uses the latest OpenJDK 8.x version (headless JRE).

OpenJDK version

If you want to switch to OpenJDK 7.x or simply an older version, you can do so using the -components.openjdk configuration setting:

> boxfuse run my-app-1.0.jar -components.openjdk=7.80.32

To find out which OpenJDK versions are available from the Boxfuse Inventory you can simply issue:

> boxfuse inventory openjdk

Custom JRE

If you prefer to use a different JRE, including the Oracle JRE, rather than the default OpenJDK one, you can do so by including the Linux x64 JRE distribution of your choice in a /WEB-INF/jre folder inside the war file.

If you use Maven or Gradle, this means the jre folder should be put into the src/main/webapp/WEB-INF directory:

 my-tomee-app
   src
     main
       java
       resources
       webapp
         WEB-INF
           jre
   bin
     java
     ...
   lib
     amd64
     ...
     rt.jar
     ...
   COPYRIGHT
   LICENSE
   ...

Tip for Git users

To avoid file corruption due to Git line-ending normalization, add the following line to .gitattributes

src/main/webapp/WEB-INF/jre/* binary

TomEE version

By default Boxfuse uses the latest TomEE 1.7.x version. If you want to switch to TomEE 7.0.x or simply an older version, you can do so using the -components.tomee-webprofile and -components.tomee-plus configuration settings:

> boxfuse run my-webapp-1.0.war -components.tomee-webprofile=7.0.0-M3

To find out which TomEE versions are available from the Boxfuse Inventory you can simply issue:

> boxfuse inventory tomee-webprofile

HTTP

By default, Boxfuse will automatically configure TomEE to listen to HTTP traffic on port 80.

TLS (SSL) Certificates / HTTPS

Automatic TLS (SSL) Certificate management

To expose your app via HTTPS make sure you have a custom domain configured for the environment where you want to run it. Also make sure that you have obtained a valid TLS (SSL) certificate and that your app has been created with app.type set to load-balanced and tls.type set to acm (AWS Certificate Manager).

With that in place your TomEE app will be automatically configured to run with HTTPS and a green lock will appear in the browser.

Boxfuse will ensure that all network traffic between the ELB and your instances will be encrypted as well.

Manual TLS (SSL) Certificate management

To use HTTPS with your own certificate, you first have to obtain a valid certificate from a Certificate Authority and add a KeyStore containing your SSL certificate inside the .war file as /WEB-INF/keystore.jks. It must contain a certificate with the alias tomcat and be secured with the standard password changeit. Boxfuse will then automatically configure Tomcat to start serving traffic via HTTPS on port 443, as well as automatically redirect any insecure HTTP traffic to the secure HTTPS connection.

If you use Maven or Gradle this means you have to put the keystore.jks file under src/main/webapp/WEB-INF:

 my-tomee-app
   src
     main
       java
       resources
       webapp
         WEB-INF
           keystore.jks

Root Certificates

By default, Boxfuse uses the same root certificate bundle as the latest version of Firefox. Additionally Boxfuse also includes the root certificates for Amazon RDS, so you can connect securely to RDS databases out of the box.

You can, however, ship your own set of root certificates, by placing them in a KeyStore at /WEB-INF/cacerts. Boxfuse will then automatically configure both the JRE and Tomcat to use these instead.

If you use Maven or Gradle this means you have to put the cacerts file under src/main/webapp/WEB-INF:

 my-tomee-app
   src
     main
       java
       resources
       webapp
         WEB-INF
           cacerts

JCE unlimited strength cryptography

To enable JCE unlimited cryptography (for AES-256, RSA-4096, ...), download the policy zip from the Oracle website for either Java 7 or Java 8.

Extract both local_policy.jar and US_export_policy.jar and place them under /WEB-INF inside your war file. If you use Maven or Gradle, this means both policy jar files should be put into the src/main/webapp/WEB-INF directory. Boxfuse will then automatically configure the JRE to use these instead.

 my-dropwizard-app
   src
     main
       java
       resources
       webapp
         WEB-INF
           local_policy.jar
 US_export_policy.jar

Databases

Database auto-provisioning

If your app includes the PostgreSQL or MySQL JDBC driver, Boxfuse will automatically provision the necessary PostgreSQL or MySQL database in each environment.

When using the Boxfuse database auto-provisioning support, Boxfuse automatically injects environment variables in your instance with the correct details: BOXFUSE_DATABASE_URL (jdbc url), BOXFUSE_DATABASE_USER (database user) and BOXFUSE_DATABASE_PASSWORD (database password).

To make this easy to use, Boxfuse also automatically creates a TomEE JDBC DataSource called boxfuseDatabase that you can then easily reference in your application.

When using persistence.xml, integration looks like this:

<persistence ... >
  <persistence-unit name="...">
    <jta-data-source>boxfuseDatabase</jta-data-source>
    ...
  </persistence-unit>
</persistence>

This works identically in all environments and Boxfuse ensures you always get the correct settings.

Using an existing database

To disable database auto-provisioning and use an existing database set db.type to none when creating your app.

Java Agents

By default Boxfuse will activate the OpenEJB Java Agent.

If you wish to launch the JRE with one or more additional Java Agents, simply place the Java Agent files inside the war file under /WEB-INF/javaagents/. In a Maven or Gradle project this means you have to put your agent jar and whatever other files it requires under src/main/webapp/WEB-INF/javaagents:

 my-tomee-app
   src
     main
       java
       resources
       webapp
         WEB-INF
           javaagents
   myjavaagent.jar
   myjavaagent.properties

Boxfuse will then automatically configure the JRE to use these Java Agents

JVM Memory

By default Boxfuse will dynamically configure your JVM heap to use 85% of the available memory in the instance. All other settings use the JVM defaults. You can override this by specifying the required JVM arguments like -Xmx via the jvm.args configuration setting.

Temporary Files

Boxfuse configures the JVM and the TomEE ActiveMQ Broker to use /tmp as the directory to store temporary files and provisions 1 GB of space by default.

To increase this (up to a maximum of 16 TB), simply set the tmp configuration setting to the number of GB of temp space you need. To prevent Boxfuse from provisioning any temp space set tmp to 0.

Debugging

Remote debugging (including hot-code replace) with your favorite IDE is fully supported. Details and setup instructions on our debugging page.

Profiling

Profiling with tools like JVisualVM and Java Flight Recorder is fully supported. Details and setup instructions on our profiling page.

Live Reloading

Boxfuse supports Live Reloading of exploded war files.

Time Zone

By default all Boxfuse instance use the UTC time zone.

We don't recommend changing this as this greatly simplifies time zone issues in machine to machine communication and cleanly relegates all time zones related aspects to a pure presentation layer concern.

If however you still do want to change this, you can override the default time zone of the instance using the TZ environment variable. For example to change the time zone of your instance to America/Los_Angeles you would do so like this:

> boxfuse fuse -envvars.TZ=America/Los_Angeles

Native binaries and libs

Some JVM applications also depend on native Linux x64 binaries and libs to do their work. Boxfuse makes it easy to integrate them into your image.

Simply place your binaries under WEB-INF/native/bin inside your war file and Boxfuse will automatically add them to the PATH at runtime in your instances.

If those binaries also depend on additional shared libraries beyond the C library, place the .so files of your libraries under WEB-INF/native/lib inside your war file and Boxfuse will automatically add them to the LD_LIBRARY_PATH at runtime in your instances.

Tip

To list all the shared libraries your Linux x64 binary requires, you can use the following command on a Linux system:

$ ldd -v my-native-binary

If you use Maven or Gradle, the native directory should be put into the src/main/webapp/WEB-INF directory. Boxfuse will then automatically configure the PATH and LD_LIBRARY_PATH to use it.

 my-tomee-app
   src
     main
       java
       webapp
         WEB-INF
           native
   bin
     my-native-binary
     other-linux-x64-binary
   lib
     my-shared-lib.so
     other-shared-lib.so

You can then simply invoke them in your code using

Runtime.getRuntime().exec("my-native-binary arg1 arg2 arg3");

New Relic support

To monitor your app using New Relic simply pass in your New Relic license key when fusing your image and Boxfuse will automatically install and configure the New Relic Servers Linux x64 and New Relic Java agents for you.

> boxfuse fuse -newrelic.licensekey=0123456789abcdef0123456789abcdef01234567

Alternatively you can also supply a newrelic.yml configuration file for the Java agent and Boxfuse will automatically use that instead. Boxfuse will then install the agent for you, but won't override any application name you may have configured. If you haven't configured a New Relic license key as described above, Boxfuse will use the license key contained in your newrelic.yml configuration file instead.

If you use Maven or Gradle, the newrelic.yml file should be put into the src/main/webapp/WEB-INF directory. Boxfuse will then automatically configure the New Relic Java agent to use it.

 my-tomee-app
   src
     main
       java
       resources
       webapp
         WEB-INF
           newrelic.yml

Linux Kernel Tuning (experts only)

If you need to tune the Linux kernel running in your instance, simply place a sysctl.conf file inside your war file under /WEB-INF. In a Maven or Gradle project this means you have to put it under src/main/webapp/WEB-INF:

 my-tomee-app
   src
     main
       java
       resources
       webapp
         WEB-INF
           sysctl.conf

Boxfuse will then automatically configure the Linux kernel to use these settings.

Executable Jar