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:
-
S2I WildFly builder image. Build a WildFly application as a reproducible Docker image using source-to-image. The resulting image can be run using Docker.
-
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:
- CentOS7
Images are built using docker community edition and cekit version 3. You will also need the docker-squash module Mac OSX installation and build tips.
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
Building WildFly s2i builder image with a locally built WildFly server
First, you must update WILDFLY_VERSION
value in wildfly-modules/jboss/container/wildfly/base/module.yaml to the WildFly version you want to use.
build-s2i-image.sh
script steps:
- Builds WildFly (
clean install -DskipTests -Drelease
) if--no-wildfly-build
is not set. If you have already build WildFly be sure to have used the-Drelease
maven argument. - Constructs and zip a local maven repository that contains all maven artifacts required by WildFly (JBoss module jars). NB during this phase an http server is started on port 7777.
- Creates the
wildfly/wildfly-centos7:dev-snapshot
s2i builder docker image using the zipped repository.
$ cd tools
$ ./build-s2i-image.sh <path to wildfly directory> [--no-wildfly-build]
Building your own application image
The script tools/build-app-image.sh
uses s2i command line tool and docker to create an image from your application src.
-
By default it uses
quay.io/wildfly/wildfly-centos7
andquay.io/wildfly/wildfly-runtime-centos7
images. You can provide your own wildfly s2i builder and runtime images. -
If no application name is provided, the image name is derived from the application src directory.
-
You can provide Galleon layers in order to build a trimmed-down server.
$ cd tools
$ ./build-app-image.sh <path to your app maven project> [--app-name=<application name>] [--galleon-layers=<comma separated list of layers>] [--wildfly-builder-image=<wildfly s2i builder image>] [--wildfly-runtime-image=<wildfly runtime image>]
To build a simple jee application using standalone S2I and then run the resulting image with Docker execute:
$ 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
The following Dockerfile uses multi-stage build to chain builds to create a lightweight image.
NB: In order to be able to copy the server to the runtime image, the server must have been provisioned using galleon during s2i build.
This is done by using one of the Galleon env variables or by defining a galleon/provisioning.xml
file at the root of the application src.
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
Dockerfile
file - Adjust the
--from
argument to reference the image you first built with s2i - In the directory that contains the
Dockerfile
run: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.
-
imagestreams/ contains image streams registered in openshift library
-
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.yml
builder image streamwildfly-runtime-image-stream.yml
runtime image streamwildfly-s2i-chained-build-template.yml
template 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
run
script -
wildfly-builder-image/ contains builder image yaml file
-
wildfly-modules/ contains cekit modules specific to wildfly. NB: These modules are progressively removed and added to the wildfly-cekit-modules repository.
-
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.
- Platform name (lowercase) -
wildfly
- Base builder image -
centos7
- WildFly version or
latest
Example: wildfly/wildfly-centos7:17.0
To set environment variables, you can place them as a key value pair into a .s2i/environment
file inside your source code repository.
-
GALLEON_PROVISION_SERVER
[DEPRECATED, Use ofGALLEON_PROVISION_LAYERS
is the way to provision custom server]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)
- slim-default-server. The default server present in the builder image. JBoss module artifacts are retrieved from local maven repository.
- fat-default-server. Same server configuration as the slim-default-server) but artifacts are retrieved from $JBOSS_HOME/modules.
- standalone-profile (Vanilla WildFly configuration for standalone)
Can't be used when
GALLEON_PROVISION_LAYERS
is used. -
GALLEON_PROVISION_LAYERS
A comma separated list of layer names to compose a WildFly server. Any layer name starting with-
(eg:-jpa
) will be excluded from the provisioning. Can't be used whenGALLEON_PROVISION_SERVER
is used.-
Openshift Base layers:
-
datasources-web-server
: Web + DB + core server (logging, management, elytron, ...). A servlet container (web-server
layer), datasources support (datasources
layer) and core subsystems (core-server
layer). NB: security feature is offered thanks to elytron. -
jaxrs-server
: REST + JPA. Expands ondatasources-web-server
layer with thejaxrs
,cdi
andjpa
layers, plus infinispan based local second level entity caching. -
cloud-server
: Expands onjaxrs-server
withresource-adapters
,jms-activemq
(remote broker messaging, not embedded) andobservability
layers.
-
-
Openshift Decorator layers (to be used to complement base layers):
-
keycloak
: Keycloak integration. -
observability
: MP Health, Metrics, Config, OpenTracing.
-
-
-
GALLEON_PROVISION_DEFAULT_FAT_SERVER
Set this env variable to true in order to provision the default server in a way that allows to copy it to the runtime image. -
S2I_COPY_SERVER
When Galleon provisioning occurs, the server (and deployed apps) is copied to the directory/s2i-output/server
directory. This can be disabled by setting this env variable tofalse
. -
Maven env variables
-
The maven env variables you can set are documented in this document
-
MAVEN_OPTS
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.
-
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 toJAVA_OPTS
WildFly server env variables
-
Access Log env vars
-
Admin user env vars
-
Deployment scanner env var
-
CLI_GRACEFUL_SHUTDOWN
set to true to disable shutdown. -
DEFAULT_DATASOURCE
defaut toPOSTGRESQL_DATASOURCE
orMYSQL_DATASOURCE
orEXAMPLE_DATASOURCE
orExampleDS
-
Elytron security env vars
-
EXAMPLE_DATASOURCE
default toExampleDS
-
Filters (Undertow) env vars
-
HTTPS config env vars
-
JSON logging env vars
-
Keycloak env var
-
Logger categories env vars
-
Microprofiles config env vars
-
MYSQL_DATABASE
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_SERVICE_PORT
MYSQL_SERVICE_HOST
MYSQL_PASSWORD
MYSQL_USER
MYSQL_DATASOURCE
, default to MySQLDS, is used as the JNDI name of the datasourcejava:jboss/datasources/$MYSQL_DATASOURCE
-
OPENSHIFT_SMTP_HOST
default tolocalhost
-
POSTGRESQL_DATABASE
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_SERVICE_PORT
POSTGRESQL_SERVICE_HOST
POSTGRESQL_PASSWORD
POSTGRESQL_USER
POSTGRESQL_DATASOURCE
, default to PostgreSQLDS, is used as the JNDI name of the datasourcejava:jboss/datasources/$POSTGRESQL_DATASOURCE
-
Port offset env vars
-
Resource adapters env vars
-
SCRIPT_DEBUG
set to true to enable launch script debug. -
SERVER_CONFIGURATION
name of standalone XML configuration file. Default tostandalone.xml
-
WILDFLY_ENABLE_STATISTICS
default totrue
-
WILDFLY_MANAGEMENT_BIND_ADDRESS
default to0.0.0.0
-
WILDFLY_PUBLIC_BIND_ADDRESS
default to the value returned byhostname -i
-
WILDFLY_TRACING_ENABLED
in default server configuration microprofile opentracing is not enabled. Set this env variable totrue
to enable it. In case your configuration contains opentracing (eg: cloud-profile), you can disable it by setting this env variable tofalse
. -
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
Provisioning a custom server using Galleon
That is done during s2i build using the GALLEON_PROVISION_LAYERS
env variable.
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 provisioning.xml file. During s2i build, this file is used to provision a server.
This server is used to replace the one present in the s2i builder image (located in $JBOSS_HOME).
The Galleon feature-pack location to use is wildfly-s2i@maven(org.jboss.universe:s2i-universe):current
, 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 the Openshift base layers or WildFly defined galleon layers:
- mysql-datasource
- mysql-default-datasource
- mysql-driver
- postgresql-datasource
- postgresql-default-datasource
- postgresql-driver
Note: These Galleon layers are defined and documented in wildfly-extras Galleon feature-pack.
As an example, this custom configuration Galleon definition
defined in this maven project
combines the WildFly cloud-profile
with the postgresql-datasource
-
Wildfly configuration files from the
<application source>/<cfg|configuration>
are copied into the wildfly configuration directory. -
Pre-built war files from the
<application source>/deployments
are moved into the wildfly deployment directory. -
Wildfly modules from the
<application source>/modules
are copied into the wildfly modules directory. -
Execute WildFly CLI scripts by using
S2I_IMAGE_SOURCE_MOUNTS
andinstall.sh
scripts 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.yml
andoc create -f imagestreams/wildfly-runtime-centos7.yml
.wildfly
andwildfly-runtime
imagestreams are created. -
Adding the template:
oc create -f templates/wildfly-s2i-chained-build-template.yml
. Templatewildfly-s2i-chained-build-template
is created. -
The imagestreams and templates are added to the namespace (project) currently selected. It is recommended to add the imagestreams to the
openshift
namespace. In case you don't have access to the openshift namespace, you can still add the imagestreams to your project. You will need to useIMAGE_STREAM_NAMESPACE=<my project>
parameter when using thewildfly-s2i-chained-build-template
template to create an application. -
When adding the
wildfly
imagestream to theopenshift
namespace, the OpenShift catalog is automatically populated with a the templateWildFly
allowing 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-s2i-chained-build-template
with wildfly
and 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
- 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
AB_JOLOKIA_AUTH_OPENSHIFT
andAB_JOLOKIA_PASSWORD_RANDOM
tofalse
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.