Skip to main content

nsx-tomee-base

The nsx-tomee-base Docker image is an image based on the Eclipse Temurin distribution of OpenJDK, which contains Apache TomEE Plume and some other tooling, such as Flyway. These images can be extended to package a JEE application and its configuration or additional dependencies.

Images

All images are available under the registry docker.normalizedsystems.org/nsx-tomee-base. There are several different tags for the image, some of which are fixed versions that are never updated and some which are updated to a varying degree of frequency depending on the tag.

For production releases of applications, we recommend to always build using fixed version tags, in order to have a build that can at all times be reproduced. There are three different factors which determine what goes into a docker image for a specific label:

  • Version of the Docker image itself (each change made to the image is considered to be a new version).
  • Version of TomEE packaged in the image.
  • Version of the Java Runtime Engine that the image is based on.

Overall we recommend using the LTS release of Java. Often our technologies will also require this. At this time, that is Java 17. The following list of image tags supplies the latest version of Java that we support.

TagExampleFixedDescription
latestlatestThe latest version of the image, latest supported version of JRE and latest version TomEE.
<tomee-major-version>8The latest version of the image, latest supported version of JRE and latest major version TomEE.
<tomee-version>8.0.13The latest version of the image, latest supported version of JRE and fixed version TomEE.
<tomee-version>-<image-version>8.0.13-2.13.0A fixed version of the image, latest supported version of JRE and fixed version TomEE.

We will often keep our application code backwards compatible with older versions of Java, to keep supporting projects which have not yet upgraded. Therefor we also provide alternative versions of all images, for all versions of Java which we still officially support. That is currently Java 17 and 11. To use a specific JRE, a tag with a jre-qualifier can be used:

TagExampleFixedDescription
latest-<qualifier>latest-jre17The latest version of the image, fixed of JRE and latest version TomEE.
<tomee-major-version>-<qualifier>8-jre17The latest version of the image, fixed of JRE and latest major version TomEE.
<tomee-version>-<qualifier>8.0.13-jre17The latest version of the image, fixed of JRE and fixed version TomEE.
<tomee-version>-<image-version>-<qualifier>8.0.13-2.13.0-jre17A fixed version of the image, fixed of JRE and fixed version TomEE.
caution

We periodically release updates which are based on new minor versions of the JRE base images. These are released as new versions of our image. Existing fixed image tags will not be overwritten, so they are also bound to a specific minor version of JRE.

Architecture

TomEE is installed in the folder /usr/local/apache-tomee (use ${CATALINA_HOME} variable). The application itself, along with its dependencies and configuration are placed under a subdirectory /usr/local/apache-tomee/BASE0 (use ${CATALINE_BASE} variable).

info

The BASE0 folder is a legacy artifact that predates the use of Docker, when multiple applications would be deployed by the same application server. It is retained for backwards compatibility.

Locations

LocationDescription
${CATALINA_HOME}/libContains the libraries and dependencies of the application server itself.
${CATALINA_HOME}/lib-loggingContains dependencies to enable logging in the application server. We package Log4j here in the base images.
${CATALINA_BASE}/app-confLocation to package application-specific configuration files. This folder is available on the classpath of the application.
${CATALINA_BASE}/confContains configuration fields for the application server, related to the deployment of the application.
${CATALINA_BASE}/deployLocation where the application ear file is placed and read from by the application server while deploying.
${CATALINA_BASE}/libAdditional dependencies required by the application, which cannot be packaged in the application itself.
${CATALINA_BASE}/sqlFixed location to bundle initialization and migration scripts for the application. This is primarily intended as a location to place scripts for Flyway.
caution

All of these locations are intended to be packaged in a docker sub-image. This means that files in there will be part of the release. Never hardcode credentials or other sensitive data in these files. Variable substitution should be used here to inject those when the application starts.

Default ports

The following ports are defined by default (if ${CATALINE_BASE}/conf/server.xml is not overwritten):

NamePortDescription
HTTP port80Webserver HTTP port where the application can be reached.
Debug port4041Port used for remote debugging. Only enabled when variable ${ENABLE_DEBUG} is set to yes.
Shutdown port8005Port used to issue shutdown commands to the server.
HTTPS port443Webserver secure HTTP port where the application can be reached with SSL encryption. SSL is disabled by default and only relevant if the application server is configured with SSL certificates.
Redirect port443Port the server will redirect to if an SSL request is received on the HTTP port.
danger

Though the HTTPS port is disabled by default in the server configuration. We do not recommend ever using plain HTTP to communicate with the server. If the application server is not configured to supply SSL connections, an SSL-terminating proxy should be placed in front of the server to handle secure connections!

Configuration

tomee.xml

One configuration file that should always be supplied, is the ${CATALINA_BASE}/conf/tomee.xml file. This contains configuration for TomEE, specifically related to the application itself. This includes deployment location ( ${CATALINA_BASE}/deploy directory), transaction management configuration and configuration of datasources to connect to the underlying database.

Example tomee.xml file
<?xml version="1.0" encoding="UTF-8"?>
<tomee>
<Deployments dir="deploy" autoDeploy="true"/>

<TransactionManager id="transactionManager" type="TransactionManager">
defaultTransactionTimeout = 60 seconds
</TransactionManager>

<Resource id="jdbc_myapplication_base" type="DataSource">
JdbcDriver org.postgresql.Driver
JdbcUrl jdbc:postgresql://${DATABASE_HOST}:${DATABASE_PORT}/${DATABASE_NAME}
UserName ${DATABASE_USER}
Password ${DATABASE_PASS}
JtaManaged true
TestWhileIdle true
InitialSize ${DATABASE_INIT_CONN}
MaxActive ${DATABASE_MAX_ACTIVE_CONN}
MaxIdle ${DATABASE_MAX_IDLE_CONN}
</Resource>

<Resource id="jdbc_myapplication_applicationComponent" type="DataSource">
JdbcDriver org.postgresql.Driver
JdbcUrl jdbc:postgresql://${DATABASE_HOST}:${DATABASE_PORT}/${DATABASE_NAME}
UserName ${DATABASE_USER}
Password ${DATABASE_PASS}
JtaManaged true
TestWhileIdle true
InitialSize ${DATABASE_INIT_CONN}
MaxActive ${DATABASE_MAX_ACTIVE_CONN}
MaxIdle ${DATABASE_MAX_IDLE_CONN}
</Resource>
</tomee>

server.xml

The ${CATALINA_BASE}/conf/server.xml file contains the configuration of how the application server should serve the deployed application. This includes what ports it should be server on, connection security, thread allocation, ... Typically the default configuration of this file should suffice (if you have an SSL-terminating proxy).

system.properties

The ${CATALINA_BASE}/conf/system.properties file defines some Java system properties, that are relevant to the application server and the JEE application framework. Usually these properties should not be altered, but some applications may require additional properties or fine-tuning.

log4j2.xml

The ${CATALINA_BASE}/conf/log4j2.xml file contains the configuration for the Log4j logging framework used by the application server. If specific logging settings such as different log levels for certain packages or different log appenders are required, these can be configured here.

Environment variables

The docker image defines several environment variables. Some provide information about the software itself and some are used to provide configuration.

Informational variables

VariableOriginDescription
JAVA_HOMEeclipse-temurinPath to the OpenJDK installation directory.
CATALINA_HOMEnsx-tomee-basePath to the TomEE installation directory.
CATALINA_BASEnsx-tomee-basePath to the application base directory.
JAVA_VERSIONeclipse-temurinFull version of the JRE distribution.
TOMEE_VERSIONnsx-tomee-baseVersion of the TomEE application server.
FLYWAY_VERSIONnsx-tomee-baseVersion of the bundled Flyway installation.
NSX_BASE_VERSIONnsx-tomee-baseVersion of the TomEE base image itself.

Image configuration variables

VariableDescription
APPLICATION_NAMEThe name of the NS application (as defined in the model). Not mandatory, but strongly recommended. When supplied, the application server will redirect from the root path, to the path of the deployed application. This is also used to perform the default health check.

Runtime configuration variables

VariableDefaultDescription
ENABLE_DEBUGUnsetEnables the debugging port for the deployed application when set to yes.
JVM_INIT_HEAP_SIZE512mDefines the initial heap size for the JVM. Equivalent to the -Xms argument on JVM.
JVM_MAX_HEAP_SIZE1024mDefines the maximum heap size for the JVM. Equivalent to the -Xmx argument on JVM.
JVM_STACK_SIZE512kDefines the stack size for the JVM to store call stack information.

Application specific features

If the name of the deployed application (as it is defined in the deployment URL) is given in the environment variable APPLICATION_NAME, additional features will be enabled:

  • Health check: A check that starts at 5s, which checks every 10s whether the application is running on $baseUrl/$APPLICATION_NAME. After 6 failed checks, it will switch to unhealthy and the container will remain in the starting state until the first passed health check. The check verifies that the login page of the UI can be accessed.
  • Root URL redirect: The root URL of the application server will redirect to $baseUrl/$APPLICATION_NAME.

Runtime configuration

Runtime configuration should be applied by adding a script as a CMD instruction in a sub-image Dockerfile. This scripts will then be executed by the image, prior to starting the application server.

Example

Create a setup script prepare.sh and copy it to the /tmp folder in the docker image. Add /tmp/prepare.sh as a CMD instruction.

FROM docker.normalizedsystems.org/nsx-tomee-base:latest

# instructions to package your application

COPY prepare.sh /tmp

CMD [ "/tmp/prepare.sh" ]
caution

It is possible to overwrite the script that launches TomEE, but this is NOT recommended. You can either copy a new script over the default one at /tmp/wrapper.sh, or add a new script to the image at a different location and overwrite the ENTRYPOINT to call that instead.

Additional tools

dos2unix

The dos2unix application is packaged with the image and can be used to convert line endings of files such as shell scripts to LF in derived docker images. This will avoid issues with Windows CRLF line endings at runtime.

Example
Dockerfile
COPY prepare.sh /tmp
RUN dos2unix /tmp/prepare.sh

wait-for-it

The wait-for-it script is packaged with the image and can be used to wait for a port to become available for some service on the Docker network.

Example
prepare.sh
wait-for-it ${DATABASE_HOST}:${DATABASE_PORT} --timeout=120

envsubst

envsubst is a program part of the GNU gettext package which is used to replace all environment variables in files with the variable available in the environment at that time.

Example
prepare.sh
echo "$(envsubst < ${CATALINA_BASE}/app-conf/account.ns.properties)" > ${CATALINA_BASE}/app-conf/account.ns.properties

Flyway

The Flyway application is packaged with the image and can be used to both initialize and migrate SQL databases.

Example
prepare.sh
flyway migrate -url=jdbc:postgresql://${DATABASE_HOST}:${DATABASE_PORT}/${DATABASE_NAME} \
-user=${DATABASE_USER} \
-password=${DATABASE_PASS} \
-locations=filesystem:${CATALINA_BASE}/sql/ \
-connectRetries=5