Wildfly - CentOS Docker images for Openshift
NOTE: The WildFly S2I image is now developed in this repository. It replaces the repository https://github.com/openshift-s2i/s2i-wildfly that can still be used to build older images.
This repository contains the source for building 2 different WildFly docker images:
WildFly runtime image. An image that contains the minimal dependencies needed to run WildFly with deployed application. This image is not runnable, it is to be used to chain a docker build with an image created by the WildFly S2I builder image.
NB: The image created by chaining an s2i build and a docker build is a good candidate to be managed by the WildFly Operator
CentOS versions currently provided are:
Building the images
Cloning the repository:
$ git clone https://github.com/wildfly/wildfly-s2i $ cd wildfly-s2i
Building WildFly s2i builder image from scratch:
$ cd wildfly-builder-image $ cekit build docker
Building WildFly runtime image from scratch:
$ cd wildfly-runtime-image $ cekit build docker
$ s2i build git://github.com/openshift/openshift-jee-sample wildfly/wildfly-centos7:latest wildflytest $ docker run -p 8080:8080 wildflytest
Accessing the application:
$ curl 127.0.0.1:8080
Chaining s2i build with runtime image
The following Dockerfile uses multi-stage build to chain builds to create a lightweight image.
FROM wildfly/wildfly-runtime-centos7:latest COPY --from=wildflytest:latest /s2i-output/server $JBOSS_HOME USER root RUN chown -R jboss:root $JBOSS_HOME && chmod -R ug+rwX $JBOSS_HOME RUN ln -s $JBOSS_HOME /wildfly USER jboss CMD $JBOSS_HOME/bin/openshift-launch.sh
To build the docker image:
- Copy the Dockerfile content into a
- Adjust the
--fromargument to reference the image you first built with s2i
- In the directory that contains the
docker build --squash -t wildflytest-rt .
This repository also provides a S2I test framework, which launches tests to check functionality of a simple WildFly application built on top of the wildfly image. The tests also create a chained build to build a WildFly application runtime image from an s2i build.
$ make test
When running tests, the WildFly docker images are first built.
doc/ some documentation content referenced from this README file.
make/ contains make scripts
templates templates you can add to a local openshift cluster (eg:
oc create -f templates/wildfly-s2i-chained-build-template.yml)
wildfly-builder-image-stream.ymlbuilder image stream
wildfly-runtime-image-stream.ymlruntime image stream
wildfly-s2i-chained-build-template.ymltemplate that build an application using s2i and copy the WildFly server and deployed app inside the WildFly runtime image.
test/ contains test applications and make test
wildfly-builder-image/ contains builder image yaml file
wildfly-runtime-image contains runtime image yaml file
Hot deploy is enabled by default for all WildFly versions. To deploy a new version of your web application without restarting, you will need to either rsync or scp your war/ear/rar/jar file to the /wildfly/standalone/deployments directory within your pod.
Image name structure
- Platform name (lowercase) -
- Base builder image -
- WildFly version or
Environment variables to be used at s2i build time
To set environment variables, you can place them as a key value pair into a
file inside your source code repository.
The image contains a set of pre-defined galleon definitions that you can use to provision a custom WildFly server during s2i build. The set of built-in descriptions you can use as value of the env var are:
- full-profile (Vanilla WildFly configuration for standalone and domain)
- os-standalone-profile (The default server present in the builder image)
- standalone-profile (Vanilla WildFly configuration for standalone)
Maven env variables
The maven env variables you can set are documented in this document
Contains JVM parameters to maven. Will be appended to JVM arguments that are calculated by the image itself (e.g. heap size), so values provided here will take precedence.
Environment variables to be used when running application
Java env variables
- The Java env variables you can set are documented in this document
ENABLE_JPDA, set to true to enable debug on port 8787, disabled by default.
JAVA_OPTS_EXT, to append to options to
WildFly server env variables
When set to
true, Wildfly will automatically deploy exploded war content. When unset or set to
.dodeployfile must be touched to trigger deployment of exploded war content.
CLI_GRACEFUL_SHUTDOWNset to true to disable shutdown.
ENABLE_JSON_LOGGING, set to
trueto enable JSON formatted logging. By default it is false.
If set, WildFly will attempt to define a MySQL datasource based on the assumption you have an OpenShift service named "mysql" defined. It will attempt to reference the following environment variables which are automatically defined if the "mysql" service exists:
MYSQL_DATASOURCE, default to MySQLDS, is used as the JNDI name of the datasource
If set, WildFly will attempt to define a PostgreSQL datasource based on the assumption you have an OpenShift service named "postgresql" defined. It will attempt to reference the following environment variables which are automatically defined if the "postgresql" service exists:
POSTGRESQL_DATASOURCE, default to PostgreSQLDS, is used as the JNDI name of the datasource
SCRIPT_DEBUGset to true to enable launch script debug.
SERVER_CONFIGURATIONname of standalone XML configuration file. Default to
WILDFLY_PUBLIC_BIND_ADDRESSdefault to the value returned by
WILDFLY_TRACING_ENABLEDin default server configuration microprofile opentracing is not enabled. Set this env variable to
trueto enable it. In case your configuration contains opentracing (eg: cloud-profile), you can disable it by setting this env variable to
Adding new datasources can be done by using env variables defined in this document
Jolokia env variables
- The Jolokia env variables you can set are documented in this document
The s2i builder image comes with a set of pre-defined galleon maven projects that you can reference from your s2i build
(thanks to the
GALLEON_PROVISION_SERVER env variable in the default template or Galleon parameter
in the chained build template). Names of directories located in this directory
can be value of the template parameter or env variable.
Note: You can use these maven projects as a starting point to define your own WildFly server.
If you want to define your own WildFly server, create a directory named
galleon at the root of your application sources project. This directory must
contains a maven project. During s2i build
mvn install is called and expects the directory
target/server to be created in
galleon directory containing a galleon provisioned WildFly server.
This server is used to replace the one present in the s2i builder image (located in $JBOSS_HOME).
In your maven project you must use the Galleon maven plugin.
The Galleon feature-pack to use is
org.wildfly.galleon.s2i:wildfly-s2i-galleon-pack:<Wildfly version of the image>, it is only available from the WildFly s2i builder image
(located in .m2/repository).
This feature-pack contains the default standalone.xml configuration required for OpenShift. In addition it exposes the following Galleon layers that you can combine with WildFly defined galleon layers:
Note: These Galleon layers are defined and documented in wildfly-extras Galleon feature-pack.
S2i build time WildFly server customization hooks
Wildfly configuration files from the
<application source>/<cfg|configuration>are copied into the wildfly configuration directory.
Pre-built war files from the
<application source>/deploymentsare moved into the wildfly deployment directory.
Wildfly modules from the
<application source>/modulesare copied into the wildfly modules directory.
Execute WildFly CLI scripts by using
install.shscripts as documented in s2i core documentation
Datasource drivers deployment thanks to S2I hooks. This document covers the drivers deployment and configuration.
This test application highlight the usage of these customization hooks (in combination of galleon provisioning a cloud-profile server).
In case your openshift installation doesn't contain the images and templates:
Adding the image streams:
oc create -f imagestreams/wildfly-centos7.ymland
oc create -f imagestreams/wildfly-runtime-centos7.yml.
wildfly-runtimeimagestreams are created.
Adding the template:
oc create -f templates/wildfly-s2i-chained-build-template.yml. Template
The imagestreams and templates are added to the namespace (project) currently selected. It is recommended to add the imagestreams to the
openshiftnamespace. In case you don't have access to the openshift namespace, you can still add the imagestreams to your project. You will need to use
IMAGE_STREAM_NAMESPACE=<my project>parameter when using the
wildfly-s2i-chained-build-templatetemplate to create an application.
When adding the
wildflyimagestream to the
openshiftnamespace, the OpenShift catalog is automatically populated with a the template
WildFlyallowing you to create new build and new deployment from the OpenShift Web Console.
Building a new application image from the
wildfly-s2i-chained-build-template (to be then managed by WildFly Operator):
oc new-app wildfly-s2i-chained-build-template
Building a new application image from the
wildfly-s2i-chained-build-template and provision a
cloud-profile WildFly server (to be then managed by WildFly Operator):
oc new-app wildfly-s2i-chained-build-template -p GALLEON_PROVISION_SERVER=cloud-profile
Building a new application image from the
wildfly-runtime imagestreams registered in
myproject (to be then managed by WildFly Operator):
oc new-app wildfly-s2i-chained-build-template -p IMAGE_STREAM_NAMESPACE=myproject
Starting a new deployment from an image created using
wildfly-s2i-chained-build-template template (NB: it is advised to use the WildFly Operator instead):
oc new-app <namespace>/<image name> -n <namespace>
Create a new application from the
wildfly imagestream (s2i build and OpenShift deployment) with a
jaxrs provisioned server:
oc new-app --name=my-app wildfly~https://github.com/openshiftdemos/os-sample-java-web.git --build-env GALLEON_PROVISION_SERVER=jaxrs
Jolokia known issues
- On some minishift versions (at least on v1/33.0) you need to disable security to allow Java console to connect to WildFly server Jolokia agent set
S2I build known issues
If UTF-8 characters are not displayed (or displayed as
This can be solved by providing to the JVM the file encoding. Set variable
MAVEN_OPTS=-Dfile.encoding=UTF-8 into the build variables
Released under the Apache License 2.0. See the LICENSE file.