© 2020 The original authors.

WildFly bootable JAR application development

This document details the steps to follow in order to develop a WildFly application packaged as a bootable JAR. A bootable JAR can be run both on bare-metal and cloud platforms.

Developing an application packaged as a bootable JAR is not different from developing an application for a traditional WildFly server installation using Maven. The extra steps required to package your application inside a bootable JAR are handled by the org.wildfly.plugins:wildfly-jar-maven-plugin Maven plugin.

This document contains the minimal information set required to build and run a WildFly bootable JAR. Complete information on the Maven plugin usage can be found in the bootable JAR documentation.

1. Adding the bootable JAR Maven plugin to your pom file

This is done by adding an extra build step to your application deployment Maven pom.xml file.

<build>
  <plugins>
    <plugin>
      <groupId>org.wildfly.plugins</groupId>
      <artifactId>wildfly-jar-maven-plugin</artifactId>
      <configuration>
        ...
      </configuration>
      <executions>
        <execution>
          <goals>
            <goal>package</goal>
          </goals>
        </execution>
      </executions>
    </plugin>
  </plugins>
</build>

The next chapter covers the plugin configuration items that are required to identify the WildFly server version and content.

2. Galleon configuration

The Bootable JAR Maven plugin depends on Galleon to construct the WildFly server contained in the JAR file.

Galleon is configured thanks to the Maven plugin <configuration> element.

The first required piece of information that Galleon needs is a reference to the WildFly Galleon feature-pack. The WildFly Galleon feature-pack is a maven artifact that contains everything needed to dynamically provision a server. This feature-pack, as well as the feature-packs on which its depends, are deployed in public maven repositories.

When the bootable JAR Maven plugin builds a JAR, WildFly feature-packs are retrieved and their content is assembled to create the server contained in the JAR.

Once you have identified a WildFly Galleon feature-pack, you need to select a set of WildFly Layers that are used to compose the server.

The set of Galleon layers to include is driven by the needs of the application you are developing. The list of WildFly Layers provides details on the server features that each layer brings. Make sure that the API and server features you are using (eg: JAX-RS, Eclipse MicroProfile Config, datasources) are provided by the layers you are choosing.

If you decide not to specify Galleon layers, a server containing all MicroProfile subsystems is provisioned. (The server configuration is identical to the standalone-microprofile.xml configuration in the traditional WildFly server zip.)

Maven Plugin configuration extract example:

<build>
  <plugins>
    <plugin>
      <groupId>org.wildfly.plugins</groupId>
      <artifactId>wildfly-jar-maven-plugin</artifactId>
      <configuration>
        <feature-pack-location>wildfly@maven(org.jboss.universe:community-universe)</feature-pack-location> (1)
        <layers>
          <layer>jaxrs-server</layer> (2)
        </layers>
      </configuration>
      <executions>
        <execution>
          <goals>
            <goal>package</goal>
          </goals>
        </execution>
      </executions>
    </plugin>
  </plugins>
</build>

(1) In this plugin configuration extract, we are retrieving the latest WildFly Galleon feature-pack installed in the org.jboss.universe:community-universe Galleon universe. In case you would like to provision a specific version of the server, you would need to specify the server version, for example wildfly@maven(org.jboss.universe:community-universe)#21.0.0.Final

(2) The jaxrs-server layer and all its dependencies are provisioned.

2.1. WildFly Layers

A Galleon layer is a name that identifies a server capability (e.g.: jaxrs, ejb, microprofile-config, jpa) or an aggregation of such capabilities. A layer captures a server capability in the form of:

  • A piece of server XML configuration (e.g.: extension, configured subsystem, interfaces) that describes the capability.

  • A set of modules and other filesystem content that implements the capability.

When you are using a layer, it delivers these pieces of information in order for Galleon to assemble a server containing only the required configuration and modules.

In the tables below we provide basic information about all of the layers WildFly provides.

Besides the layer names and a brief description of each, the tables below detail the various dependency relationships between layers. If the capabilities provided by a layer A require capabilities provided by another layer B, then layer A will depend on layer B. If you ask for layer A, then Galleon will automatically provide B as well. In some cases A’s dependency on B can be optional; that is A typically comes with B, but can function without it. In this case if you ask for A by default Galleon will provide B as well, but you can tell Galleon to exclude B.

Some layers are logical alternatives to other layers. If two layers are alternatives to each other they both provide the same general capabilities, but with different implementation characteristics. For example a number of layers provide the capability to cache different types of objects. These layers typically come in pairs of alternatives, where one alternative provides local caching, while the other provides distributed caching. If a layer you want has an optional dependency on a layer that has an alternative, you can exclude that dependency and instead specify the alternative. If a layer has an alternative the Description column in the tables below will identify it.

If the elytron layer is present, security will be handled by the elytron subsystem. The undertow and ejb subsystems are configured with an other application-security-domain that references the Elytron ApplicationDomain security domain.

2.1.1. Foundational Galleon layers

A single Galleon layer can provide a relatively small set of capabilities, but most users will want to start with a broader set of capabilities without having to spell out all the details. To help with this WildFly provides a few foundational layers all of which provide typical core WildFly capabilities like the logging subsystem and a secure remote management interface.

You don’t have to base your WildFly installation on one of these foundational layers, but doing so may be more convenient.

Name Description Dependencies

datasources-web-server

A servlet container with support for datasources.

core-server
core-tools (optional)
datasources (optional)
web-server

jaxrs-server

An extension of datasources-web-server with support for JAX-RS, CDI and JPA.

bean-validation (optional)
cdi (optional)
datasources-web-server
jaxrs (optional)
jpa (optional)

cloud-server

An extension of jaxrs-server to address common cloud requirements.

ee-security (optional)
jaxrs-server
jms-activemq (optional)
observability (optional)
resource-adapters (optional)

core-server

A typical manageable server core. This layer could serve as a base for a more specialized WildFly that doesn’t need the capabilities provided by the other foundational layers.

core-management (optional)
core-security-realms (optional)
jmx-remoting (optional)
logging (optional)
management (optional)
request-controller (optional)
security-manager (optional)

2.1.2. Basic Galleon Layers

Name

Description

Dependencies

application-security-realm

Security realm meant for securing applications.

base-server

base-server

Empty runnable server.

git-history (optional)

batch-jberet

Support for Jakarta Batch.

cdi
ee
elytron
transactions

bean-validation

Support for Jakarta Bean Validation.

base-server
cdi (optional)

cdi

Support for Jakarta Contexts and Dependency Injection.

base-server
bean-validation (optional)

cloud-profile

An aggregation of some basic layers to address cloud use cases.

bean-validation (optional)
cdi (optional)
ee-security (optional)
jaxrs (optional)
jms-activemq (optional)
jpa (optional)
observability (optional)
resource-adapters (optional)
web-server

core-management

Support for server management services.

base-server

core-security-realms

Support for core Application and Management security realms.

application-security-realm (optional)
base-server
management-security-realm (optional)

core-tools

Support for jboss-cli, add-user and elytron-tool launch scripts and configuration files.

management (optional)

datasources

Support for datasources.

transactions

deployment-scanner

Support for deployment directory scanning.

base-server

discovery

Support for discovery.

base-server

ee

Support for common functionality in the Jakarta EE platform.

jsonb (optional)
naming

ee-security

Support for EE Security.

cdi

ejb

Support for Jakarta Enterprise Beans, excluding the IIOP protocol.

ejb-lite
messaging-activemq
remoting
resource-adapters
undertow

ejb-dist-cache

Infinispan-based distributed cache for stateful session beans.
Alternative: ejb-local-cache

transactions

ejb-lite

Support for Jakarta Enterprise Beans Lite.

ejb-local-cache (optional)
naming
transactions

ejb-local-cache

Infinispan-based local cache for stateful session beans.
Alternative: ejb-dist-cache

transactions

elytron

Support for Elytron security.

base-server

git-history

Support for using git for configuration management.

h2-datasource

Support for an H2 datasource

h2-driver

h2-default-datasource

Support for an H2 datasource set as the ee subsystem default datasource.

h2-datasource

h2-driver

Support for the H2 JDBC driver.

base-server

io

Support for XNIO workers and buffer pools.

base-server

jaxrs

Support for JAXRS.

web-server
microprofile-rest-client (optional)

jdr

Support for the JBoss Diagnostic Reporting (JDR) subsystem.

base-server
management (optional)

jms-activemq

Deprecated - use messaging-activemq.

messaging-activemq

jmx

Support for registration of Management Model MBeans.

base-server

jmx-remoting

Support for a JMX remoting connector.

jmx
management (optional)

jpa

Support for JPA (using the latest WildFly supported Hibernate release).
Alternative: jpa-distributed

bean-validation (optional)
datasources

jpa-distributed

Support for JPA with a distributed second level cache.
Alternative: jpa

bean-validation (optional)
datasources

jsf

Support for Jakarta Server Faces.

bean-validation (optional)
cdi (optional)
web-server

jsonb

Support for JSON Binding (JSON-B) provisioning the JSON-B API and Implementation modules.

base-server

jsonp

Support for JSON Processing (JSON-P) provisioning the JSON-P API and Implementation modules.

base-server

legacy-management

Support for remote access to management interfaces secured with the core ManagementRealm.

management-security-realm

legacy-remoting

Support for inbound and outbound JBoss Remoting connections, secured using legacy security realms.

application-security-realm
io

legacy-security

Support for legacy Picketbox-based web security.

naming
vault

logging

Support for the logging subsystem.

base-server

mail

Support for Jakarta Mail.

base-server
naming

management

Support for remote access to management interfaces secured using Elytron.

elytron

management-security-realm

Security realm meant for securing server management interfaces.

base-server

messaging-activemq

Support for connections to a remote JMS broker.

resource-adapters

microprofile-config

Support for MicroProfile Config.

cdi

microprofile-fault-tolerance

Support for MicroProfile Fault Tolerance.

cdi
microprofile-config
microprofile-metrics

microprofile-health

Support for MicroProfile Health.

management
microprofile-config

microprofile-jwt

Support for MicroProfile JWT.

ee-security
elytron
microprofile-config

microprofile-metrics

Support for MicroProfile Metrics.

management
microprofile-config

microprofile-openapi

Support for MicroProfile OpenAPI.

jaxrs
microprofile-config

microprofile-opentracing

Support for MicroProfile OpenTracing.

cdi
microprofile-config

microprofile-platform

Support for available MicroProfile platform specifications.

microprofile-config (optional)
microprofile-fault-tolerance (optional)
microprofile-health (optional)
microprofile-jwt (optional)
microprofile-metrics (optional)
microprofile-openapi (optional)
microprofile-opentracing (optional)
microprofile-rest-client (optional)

microprofile-rest-client

Support for MicroProfile REST client.

microprofile-config

naming

Support for JNDI.

base-server

observability

Support for MicroProfile monitoring features.

microprofile-config (optional)
microprofile-health (optional)
microprofile-metrics (optional)
open-tracing (optional)

open-tracing

Deprecated Use microprofile-opentracing

cdi
microprofile-config

pojo

Support for legacy JBoss Microcontainer applications.

base-server

remote-activemq

Support for connections to a remote Apache Activemq Artemis JMS broker.

resource-adapters

remoting

Support for inbound and outbound JBoss Remoting connections, secured using Elytron.

elytron
io

request-controller

Support for request management

base-server

resource-adapters

Support for deployment of JCA adapters.

transactions

sar

Support for SAR archives to deploy MBeans.

base-server
jmx

security-manager

Support for applying security manager permissions to applications.

base-server

transactions

Support for transactions.

ee
elytron

undertow

Support for the Undertow HTTP server. Provides servlet support but does not provide typical EE integration like resource injection. Use web-server for a servlet container with EE integration.

base-server
io
vault

undertow-legacy-https

Support for the Undertow HTTPS server secured using the legacy security ApplicationRealm.

core-security-realms
undertow

undertow-load-balancer

Support for Undertow configured as a load balancer.

base-server
io
vault

vault

Support for Picketbox security vaults.

base-server

web-clustering

Support for distributable web applications. Configures a non-local Infinispan-based container web cache for data session handling suitable to clustering environments.

transactions
web-server

web-console

Support for loading the HAL web console from the /console context on the HTTP management interface. Not required to use a HAL console obtained independently and configured to connect to the server.

management

web-passivation

Support for distributable web applications. Configures a local Infinispan-based container web cache for data session handling suitable to single node environments.

transactions
web-server

web-server

A servlet container.

deployment-scanner (optional)
ee
naming
undertow

webservices

Support for Jakarta XML Web Services

ejb-lite (optional)
messaging-activemq (optional)
web-server

3. Additional configuration

The plugin allows you to specify additional configuration items:

  • A set of WildFly CLI scripts to execute to fine tune the server configuration.

  • Some extra content to be copied inside the bootable JAR (e.g.: server keystore).

Check this documentation for more details on how to configure execution of CLI scripts and to package extra content.

4. Packaging your application

Call ` mvn package` to package both your application and the bootable JAR in the file <project build directory>/<project final name>-bootable.jar

In order to speed-up the development of your application (avoid rebuilding the JAR each time your application is re-compiled), the Maven plugin offers a development mode that allows you to build and start the bootable JAR only once.

Check this documentation for more details on the development mode.

5. Running your application

Call java -jar <path to bootable JAR> <arguments>

In additon, you can use the wildfly-jar:run and wildfly-jar:start plugin goals to launch the bootable JAR.

5.1. Bootable JAR arguments

The following arguments can be used when starting the bootable JAR:

Option Description

-b[interface]=<value>

Set system property jboss.bind.address.<interface> to the given value

-b=<value>

Set system property jboss.bind.address to the given value

-D<name>[=<value>]

Set a system property. The system properties are set by the server. They are not set by the bootable JAR JVM.

--help

Display help then exit

--deployment=<path to WAR/JAR/EAR file or exploded deployment directory>

Application to install in the hollow JAR. Adding a deployment to an bootable JAR already containing a deployment is invalid.

--display-galleon-config

Display the content of the Galleon configuration used to build this bootable JAR.

--install-dir=<path to directory to install server in>

By default a new TEMP directory is created. TEMP directory location is controlled by the Java VM (call to Files.createTempDirectory).

--properties=<url>

Load system properties from the given url

-S<name>[=value]

Set a security property

-secmgr

Activate and install the WildFlySecurityManager.

-u=<value>

Set system property jboss.default.multicast.address to the given value.

--version

Print version and exit.