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 21. The following list of image tags supplies the latest version of Java that we support.

Tag	Example	Description
`latest`	`latest`	The latest version of the image, latest supported version of JRE and latest version TomEE.
`<tomee-major-version>`	`8`	The latest version of the image, latest supported version of JRE and latest major version TomEE.
`<tomee-version>`	`8.0.20`	The latest version of the image, latest supported version of JRE and fixed version TomEE.
`<tomee-version>-<image-version>`	`8.0.20-3.17.0`	A 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 21 and 17. To use a specific JRE, a tag with a jre-qualifier can be used:

Tag	Example	Description
`latest-<qualifier>`	`latest-jre21`	The latest version of the image, fixed of JRE and latest version TomEE.
`<tomee-major-version>-<qualifier>`	`8-jre21`	The latest version of the image, fixed of JRE and latest major version TomEE.
`<tomee-version>-<qualifier>`	`8.0.20-jre21`	The latest version of the image, fixed of JRE and fixed version TomEE.
`<tomee-version>-<image-version>-<qualifier>`	`8.0.20-3.17.0-jre21`	A 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

Location	Description
`${CATALINA_HOME}/lib`	Contains the libraries and dependencies of the application server itself.
`${CATALINA_HOME}/lib-logging`	Contains dependencies to enable logging in the application server. We package Log4j here in the base images.
`${CATALINA_BASE}/app-conf`	Location to package application-specific configuration files. This folder is available on the classpath of the application.
`${CATALINA_BASE}/conf`	Contains configuration fields for the application server, related to the deployment of the application.
`${CATALINA_BASE}/deploy`	Location where the application ear file is placed and read from by the application server while deploying.
`${CATALINA_BASE}/lib`	Additional dependencies required by the application, which cannot be packaged in the application itself.
`${CATALINA_BASE}/sql`	Fixed 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):

Name	Port	Description
HTTP port	`80`	Webserver HTTP port where the application can be reached.
Debug port	`4041`	Port used for remote debugging. Only enabled when variable `${ENABLE_DEBUG}` is set to `yes`.
Shutdown port	`8005`	Port used to issue shutdown commands to the server.
HTTPS port	`443`	Webserver 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 port	`443`	Port 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!

caution

The rootless version of the docker image uses different ports!

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

Variable	Origin	Description
`JAVA_HOME`	`eclipse-temurin`	Path to the OpenJDK installation directory.
`CATALINA_HOME`	`nsx-tomee-base`	Path to the TomEE installation directory.
`CATALINA_BASE`	`nsx-tomee-base`	Path to the application base directory.
`JAVA_VERSION`	`eclipse-temurin`	Full version of the JRE distribution.
`TOMEE_VERSION`	`nsx-tomee-base`	Version of the TomEE application server.
`FLYWAY_VERSION`	`nsx-tomee-base`	Version of the bundled Flyway installation.
`NSX_BASE_VERSION`	`nsx-tomee-base`	Version of the TomEE base image itself.

Image configuration variables

Variable	Description
`APPLICATION_NAME`	The 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

Variable	Default	Description
`ENABLE_DEBUG`	Unset	Enables the debugging port for the deployed application when set to `yes`.
`JVM_INIT_HEAP_SIZE`	`512m`	Defines the initial heap size for the JVM. Equivalent to the `-Xms` argument on JVM.
`JVM_MAX_HEAP_SIZE`	`1024m`	Defines the maximum heap size for the JVM. Equivalent to the `-Xmx` argument on JVM.
`JVM_STACK_SIZE`	`512k`	Defines 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 /scripts folder in the docker image. Add /scripts/prepare.sh as a CMD instruction.

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

# instructions to package your application

COPY prepare.sh /scripts

CMD [ "/scripts/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 /scripts/wrapper.sh, or add a new script to the image at a different location and overwrite the ENTRYPOINT to call that instead.

Custom shutdown scripts

Optional bash scripts can be added that will be executed before and after the application server is stopped.

The script /scripts/pre-shutdown-script.sh will be executed before the application server is requested to stop.
The script /scripts/post-shutdown-script.sh will be executed after the application server is requested to stop.

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 /scripts
RUN dos2unix /scripts/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

Data volume

A pre-defined volume was added at the path /data to provide a fixed location for applications to read and write files. As this is a predefined volume, it will be created by Docker even if it is not explicitly mounted.

Rootless images

There's now experimental support for images to run rootless containers. All available images can be obtained for rootless by appending the suffix -rootless to the label of the image.

caution

If a build stage using nsx-tomee-builder is used in the Dockerfile, it must also use the -rootless version of that image. There is no other changes required to the build stage.

Structure

The rootless image adds a new user tomee (UID 10000) as part of a new group tomee (GID 10001). The structure of these images is the same as the regular image, with the exception that the PID file has moved from /var/run/tomee.pid to ${CATALINA_BASE}/tomee.pid.

In the rootless image, the directory ${CATALINA_BASE}/ is writeable by the tomee user. This allows the application to unpack itself correctly and write logs.

Usage

The user of the image is already set to tomee, but it may be required to switch back to the root user to provision a prepare.sh script and install additional packages.

Example

prepare.sh
USER root

COPY --chmod=755 prepare.sh /scripts/prepare.sh
RUN dos2unix /scripts/prepare.sh

USER tomee

Rootless ports

The application servers in the rootless Docker image uses different ports, because without root access, the Linux kernel will not allow an application to allocate a socket on ports below 1024. Instead of the default ports, the following ports are applicable to the rootless images:

Name	Port
HTTP port	`8080`
Debug port	`4041`
Shutdown port	`8005`
HTTPS port	`8443`
Redirect port	`8443`

Images​

Architecture​

Locations​

Default ports​

Configuration​

tomee.xml​

server.xml​

system.properties​

log4j2.xml​

Environment variables​

Informational variables​

Image configuration variables​

Runtime configuration variables​

Application specific features​

Runtime configuration​

Custom shutdown scripts​

Additional tools​

dos2unix​

wait-for-it​

envsubst​

Flyway​

Data volume​

Rootless images​

Structure​

Usage​

Rootless ports​

Images

Architecture

Locations

Default ports

Configuration

`tomee.xml`

`server.xml`

`system.properties`

`log4j2.xml`

Environment variables

Informational variables

Image configuration variables

Runtime configuration variables

Application specific features

Runtime configuration

Custom shutdown scripts

Additional tools

dos2unix

wait-for-it

envsubst

Flyway

Data volume

Rootless images

Structure

Usage

Rootless ports