Java Runtime Environment

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 /jre
folder inside the Spring Boot jar file.

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

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

src/main/resources/jre/* binary

Configuration

By default Boxfuse looks for an application-boxfuse.properties file inside the Spring Boot jar
file
and runs your app with the Spring profile boxfuse activated by default.

If you use Maven or Gradle, this means the application-boxfuse.properties file should be put into the
src/main/resources directory.
When the Spring Boot Maven or Gradle plugin packages the executable jar, it will include it in the root of your
class path, where Boxfuse can see it.

Boxfuse parses application-boxfuse.properties and automatically configures the
ports and the healthcheck based on the
information it contains.

If no application-boxfuse.properties is found in the jar file, Boxfuse will automatically
look for the following configuration files both at the root of the classpath and in the config package:

application-boxfuse.yml

application-default.properties

application-default.yml

application.properties

application.yml

The overriding order matches the default Spring Boot one.

Note: Other config files (including the ones for other specific Spring profiles) are not taken
into account for auto-configuration and you will have to specify the appropriate port and healthcheck configuration
settings yourself.

Ports

Boxfuse will automatically configure your application ports to be either http
or https based on the value of server.ssl.enabled. The actual port numbers are
automatically
configured according to the values of the server.port and management.port properties.

Healthchecks

Boxfuse will automatically configure the healthcheck port and path based on the discovered Spring Boot configuration.
If your application also includes the Spring Boot Actuator, Boxfuse will automatically configures its
healthcheck
to match the Spring Boot health endpoint.

Spring Profiles

By default Boxfuse activates a Spring Profile called boxfuse. You can however easily specify a different
profile by setting the SPRING_PROFILES_ACTIVE environment variable or the spring.profiles.active
JVM system property to the value you need using the
envvars and jvm.args arguments.

To use a different Spring Profile for each Boxfuse environment,
set the Spring Boot profile to the value of the BOXFUSE_ENV environment variable which contains the
name of the
current environment (dev, test, prod): -jvm.args=-Dspring.profiles.active=$BOXFUSE_ENV

Tip for Mac OSX and Linux users

The BOXFUSE_ENV environment variable is only available within the Boxfuse instance, so
you must prevent variable expansion by using single quotes:
'-jvm.args=-Dspring.profiles.active=$BOXFUSE_ENV'

Note that selecting a Spring Profile via an environment variables or any other means does not affect how Boxfuse
configures ports and healthchecks. Boxfuse will only read the files described in that
section to extract that information, regardless of which Spring profile gets selected at runtime. You can
override those auto-configured values by explicitly setting the port numbers and healthcheck paths using Boxfuse
parameters when fusing images or launching instances. At runtime those parameters will then override any other
Spring Boot configuration.

Boxfuse auto-configures Spring Boot's DataSource by setting the SPRING_DATASOURCE_URL,
SPRING_DATASOURCE_USERNAME and SPRING_DATASOURCE_PASSWORD environment variables
to the correct JDBC url, user and password for the current environment.

Tip

If your application experiences long periods of inactivity your
database connections may time out and throw errors upon checkout.

Add the following configuration to your application.properties to fix this:

This 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 TLS (SSL) certificate to the root of the classpath to ensure it is packaged
inside the Spring Boot jar file.

If you use Maven or Gradle, this means your .jks or .keystore KeyStore file should be put
into the src/main/resources directory.
When Maven or Gradle packages the jar, it will include it in the root of your Spring Boot jar file, where Boxfuse
can see it.

my-spring-boot-app
src
main
java
resources
example.jks

You can then configure the Spring Boot connector to use it. So if for example
you have a KeyStore named example.jks inside your Spring Boot jar file,
application-boxfuse.properties should look like this:

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 inside the Jar file as /cacerts.
If you use Maven or Gradle, this means your cacerts KeyStore file should be put into the src/main/resources
directory.
Boxfuse will then automatically configure the JRE to use these instead.

my-spring-boot-app
src
main
java
resources
cacerts

If you choose to secure your cacerts TrustStore with a password different than the default changeit,
you have to add the following to your Spring Boot configuration:

Using an older Boxfuse JRE

Extract both local_policy.jar and US_export_policy.jar and place them at the root of your
Jar file.
If you use Maven or Gradle, this means both policy jar files should be put into the src/main/resources
directory.
Boxfuse will then automatically configure the JRE to use these instead.

Using a custom JRE

If you use a custom JRE it is your responsibility to ensure it is configured for unlimited
strength cryptography if you need it.

Java Agents

If you wish to launch the JRE with one or more Java Agents, simply place the Java Agent files inside the Jar file
under
/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/resources/javaagents:

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 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

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 Spring Boot jar and war files. However
in most cases you're probably better off using Spring Boot's own solution, the Spring
Boot Dev Tools,
as they work great on both VirtualBox and AWS.

All that is left is to go to your IDE project for your app and run
org.springframework.boot.devtools.RemoteSpringApplication with the same classpath as your project
and one argument with the address where your app is running, for example http://127.0.0.1:8080.

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 /native/bin on the classpath 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 /native/lib on the classpath 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/resources
directory. Boxfuse will then automatically configure the PATH and LD_LIBRARY_PATH to use it.

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.

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/resources
directory.
Boxfuse will then automatically configure the New Relic Java agent to use it.

my-spring-boot-app
src
main
java
resources
newrelic.yml

Linux Kernel Tuning (experts only)

Kernel arguments

To tune the arguments passed Linux kernel from the bootloader, simply pass them using the
-linux.args setting when fusing your image.

sysctl.conf

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

my-spring-boot-app
src
main
java
resources
sysctl.conf

You can then for example tune the maximum number of file descriptors by simply including the following in sysctl.conf:

fs.file-max = 131072

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