JBoss EAP/WildFly configuration project

When developing applications using the JBoss EAP/WildFly application server there is a repetitive task that has been solved differently over and over again: The configuration of the application server, i.e. installing JDBC drivers, startup scripts, data sources, JMS destinations, logging categories, etc.
Within our company there are several projects addressing this problem. In this post we’d like to propose a project to combine all those different requirements and experiences into a single build system.

We believe that it is a good approach to define a declarative configuration and create the server through a configurable and repeatable build process instead of editing XML and shell scripts manually. Such changes are hardly ever documented and may over time lead to a system which somehow works, but is hard to change or migrate.
Since JBoss 7 there exists a Command Line Interface (CLI) tool to manage a running server instance. This is the preferred way to change the configuration (in standalone.xml usually) and it works the same on different versions of WildFly. I.e., a CLI script for WildFly 8 might also work on WildFly 10. This approach also allows to document the adaptations made via comments.


In this article we would like to propose is a configurable and extensible tool that allows to adapt a “raw” distribution to an application’s needs. It should be applicable for different kinds of projects and provide reusable components that just need to assembled. In the context of WildFly that means, e.g.

  • A repository for modules, JDBC drivers in particular (there dozens of web sites explaining the same thing over and over again).
  • A repository for all kinds of CLI scripts that may either be used as templates and edited manually or parameterized through the configuration.
    (There already exist some collections in the Web)
  • Add or modify files from the distribution (property files, certificates, key stores, …)
  • Allows to use additional tools such as the add-user.sh script that allows to create administration users
  • Deploy an application, so the server is fully operational at startup
  • Create startup/shutdown scripts, especially when WildFly is to be installed as a service
  • Configure runtime parameters (JVM parameters, system properties, …)
  • Address different operating systems

The tool should also help us to create different versions of the server. Usually, we have to address different environments: Development system, Staging (Test), Production, Integration tests, …
These systems usually share 95% in common configuration, but use different databases, for example. Another idea would be to use the configuration utility to install an application server and application at the customer site, i.e. operate as an installation wizard.

Build process

The build process will mainly consist of executing CLI scripts, this requires a running server instance. Since WildFly 9 the server may be also started in an embedded mode from the CLI. We will focus on the embedded mode since starting and stopping the server in background is more difficult. We may add support for older versions later if there is really a need.

Once the configuration has been set up the build process consists of the following steps:

  • Download the pristine distribution (once). In case of a RedHat EAP distribution this has to be done manually (see below).
  • Unpack the distribution.
  • Download modules from repository (once) and install them into the module directory.
  • Pre-configuration phase: Copy resources (parameterized through ${my.property} values)  that cannot be created via CLI: This is done in several steps since we have to distinguish between different environments here: common, dev, prod, …
  • Run selected set of (parameterized through ${my.property} values) CLI scripts
  • Post-configuration phase: Same as above
  • Optional step: Deploy an application, i.e. copy it into deployments/ folder
  • Optional step: Create scripts to install WildFly as a service
  • ZIP/Tar the distribution for redistribution

EAP distributions

JBoss EAP distributions are somewhat different to handle, since they require a login to be downloaded. RedHat also provides patches fix bugs and security issues. Please refer to the previous blog post Upgrading and patching the Red Hat JBoss Enterprise Application Platform on how to update an EAP server.

To keep the distribution slim you may also may want to take a look at Shrinking patched JBoss EAP server to a reasonable size.


Changes applied later to the system are OK as long as you do not forget to write CLI scripts and add them to your tool configuration, too. In fact, for every change of the configuration the server should be created anew. This requires some discipline yet prevents changes from getting lost.


There are several ways how that tool might be implemented: On top of an existing build system such as  Maven or Gradle, in a scripting language, or in a combination of both. Using Maven has the advantage that we can use the existing repository mechanisms to deploy module artifacts.

Some aspects of the addressed problems could also be solved through container-based Docker solution. Yet this is a more heavy-weight approach not really feasible for development and still requires the ability to configure a server instance in a comfortable way.

This proposal is a work in progress and any comments, suggestions and ideas are welcome.

Posted in All