fabric8/s2i-java
S2I Builder Image for plain Java applications
50M+
This is a S2I builder image for Java builds whose result can be run directly without any further application server. It's suited ideally for microservices with a flat classpath (including "far jars").
It's based on CentOS and supports Java 8 and 11. Check the available tags to chose the proper Java version.
This image also provides an easy integration with an Jolokia agent. See below how to configure this.
The following environment variables can be used to influence the behaviour of this builder image:
package hawt-app:build -DskipTests -e
. Please be sure to run the hawt-app:build
goal (when not already bound to the package
execution phase), otherwise the startup scripts won't work.-X
or -am -pl ..
target/
where the jar files are created for multi module builds. These are added to ${MAVEN_ARGS}
-r hawt-app/*
when a hawt-app
dir is found on the build directory, otherwise jar files only will be included (*.jar
).false
This general purpose startup script is optimized for running Java application from within containers. It is called like
./run-java.sh <sub-command> <options>
run-java.sh
knows two sub-commands:
options
to print out JVM option which can be used for own invocation of Java apps (like Maven or Tomcat). It respects container constraints and includes all magic which is used by this scriptrun
executes a Java application as described below. This is also the default command so you can skip adding this command.When no subcommand is given (or when you provide the default subcommand run
), then by default this scripts starts up Java application.
The startup process is configured mostly via environment variables:
classpath
file which holds the classpath. Either as a single line classpath (colon separated) or with jar files listed line-by-line. If not set JAVA_LIB_DIR is the same as JAVA_APP_DIR.java
-Xmx
option is given in JAVA_OPTIONS
. This is used to calculate a default maximal Heap Memory based on a containers restriction. If used in a Docker container without any memory constraints for the container then this option has no effect. If there is a memory constraint then -Xmx
is set to a ratio of the container available memory as set here. The default is 25
when the maximum amount of memory available to the container is below 300M, 50
otherwise, which means in that case that 50% of the available memory is used as an upper boundary. You can skip this mechanism by setting this value to 0 in which case no -Xmx
option is added.-Xms
option is given in JAVA_OPTIONS
. This is used to calculate a default initial Heap Memory based on a containers restriction. If used in a Docker container without any memory constraints for the container then this option has no effect. If there is a memory constraint then -Xms
is set to a ratio of the container available memory as set here. By default this value is not set.java
. When this environment variable is given, all jar files in $JAVA_APP_DIR
are added to the classpath as well as $JAVA_LIB_DIR
.java -jar
if no $JAVA_MAIN_CLASS
is set. In all cases this jar file is added to the classpath, too.${JAVA_APP_DIR}/classpath
and use its content literally as classpath. If this file doesn't exists all jars in the app dir are added (classes:${JAVA_APP_DIR}/*
).http.proxyHost
and http.proxyPort
system properties.https.proxyHost
and https.proxyPort
system properties.http.nonProxyHosts
system property.If neither $JAVA_APP_JAR
nor $JAVA_MAIN_CLASS
is given, $JAVA_APP_DIR
is checked for a single JAR file which is taken as $JAVA_APP_JAR
. If no or more then one jar file is found, an error is thrown.
The classpath is build up with the following parts:
$JAVA_CLASSPATH
is set, this classpath is taken.$JAVA_APP_DIR
, $JAVA_APP_DIR
is added.$JAVA_MAIN_CLASS
is set, then
$JAVA_APP_JAR
is added if set$JAVA_APP_DIR/classpath
exists, its content is appended to the classpath. This file
can be either a single line with the jar files colon separated or a multi-line file where each line
holds the path of the jar file relative to $JAVA_LIB_DIR
(which by default is the $JAVA_APP_DIR
)${JAVA_APP_DIR}/*
is added which effectively adds all
jars in this directory in alphabetical order.These variables can be also set in a shell config file run-env.sh
, which will be sourced by the startup script. This file can be located in the directory where the startup script is located and in ${JAVA_APP_DIR}
, whereas environment variables in the latter override the ones in run-env.sh
from the script directory.
This startup script also checks for a command run-java-options
. If existent it will be called and the output is added to the environment variable $JAVA_OPTIONS
.
The startup script also exposes some environment variables describing container limits which can be used by applications:
Any arguments given to the script are given through directly as argument to the Java application.
Example:
# Set the application directory directly
export JAVA_APP_DIR=/deployments
# Set -Xmx based on container constraints
export JAVA_MAX_MEM_RATIO=40
# Start the jar in JAVA_APP_DIR with the given arguments
./run-java.sh --user maxmorlock --password secret
This script can also be used to calculate reasonable, best-practice options for starting Java apps in general. For example, when running Maven in a container it makes sense to respect container Memory constraints.
The subcommand options
can be used to print options to standard output so that is can be easily used to feed it to another, Java based application.
When no extra arguments are given, all defaults will be used, which can be influenced with the environment variables described above.
You can select specific sets of options by providing additional arguments:
--debug
: Java debug options if JAVA_DEBUG
is set--memory
: Memory settings based on the environment variables given--proxy
: Evaluate proxy environments variables--cpu
: Tuning when the number of cores is limited--gc
: GC tuning parameters--jit
: JIT options--diagnostics
: Print diagnostics options when JAVA_DIAGNOSTICS
is set--java-default
: Same as --memory --jit --diagnostic --cpu --gc
Example:
# Call Maven with the proper memory settings when running in an container
export MAVEN_OPTS="$(run-java.sh options --memory)"
mvn clean install
Jolokia configuration
/opt/jolokia/etc/jolokia.properties
will be created using the settings as defined in this document, otherwise
the reset of the settings in this document are ignored.0.0.0.0
)8778
)/opt/jolokia/etc/jolokia.pw
serverCert
configuration is given in AB_JOLOKIA_OPTS
$HOSTNAME
by default, which is the container id)Some options for integration in various environments:
/var/run/secrets/kubernetes.io/serviceaccount/ca.crt
Application arguments can be provided by setting the variable JAVA_ARGS to the corresponding value.
This image also supports detecting jars with Spring Boot devtools included, which allows automatic restarts when files on the classpath are updated. Files can be easily updated in OpenShift using command oc rsync
.
To enable automatic restarts, three things are required:
<dependencies>
<dependency>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-devtools</artifactId>
<optional>true</optional>
</dependency>
</dependencies>
excludeDevtools
configuration property to false:<build>
<plugins>
<plugin>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-maven-plugin</artifactId>
<configuration>
<excludeDevtools>false</excludeDevtools>
</configuration>
</plugin>
</plugins>
</build>
JAVA_DEBUG=true
or DEBUG=true
and optionally JAVA_DEBUG_PORT=<port-number>
or DEBUG_PORT=<port-number>
, which defaults to 5005. Since the DEBUG
variable clashes with Spring Boot's recognition of the same variable to enable Spring Boot debug logging, use SPRINGBOOT_DEBUG
instead.WARNING: Do not use devtools in production!!! This can be accomplished in Maven using a custom profile.
docker pull fabric8/s2i-java