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)

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.

Bootable JAR Guide

WildFly bootable JAR application development

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

2. Galleon configuration

2.1. WildFly Layers

2.1.1. Foundational Galleon layers

2.1.2. Basic Galleon Layers

3. Additional configuration

4. Packaging your application

5. Running your application

5.1. Bootable JAR arguments