© The WildFly Authors.

WildFly Maven Plugin

This document details the steps to follow in order to develop a WildFly application using the WildFly Maven Plugin.

Developing an application with the WildFly Maven Plugin is not different from developing an application for a traditional WildFly server installation using Maven. The extra steps required to provision the WildFly server and deploy your application inside the server are handled by the org.wildfly.plugins:wildfly-maven-plugin Maven plugin package goal.

In addition to the package goal, the plugin defines two other goals that can be used to provision a WildFly server:

  • The provision goal. This goal provisions a WildFly server with no application deployment.

  • The image goal. This goal builds (and pushes) an application image containing the provisioned server and the deployment.

This document contains the minimal information set required to use the WildFly Maven Plugin. Complete information on the Maven plugin usage can be found in the WildFly Maven Plugin documentation.

1. Adding the WildFly 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-maven-plugin</artifactId>
      <configuration>
        ...
      </configuration>
      <executions>
        <execution>
          <goals>
            <goal>package</goal>
          </goals>
        </execution>
      </executions>
    </plugin>
  </plugins>
</build>

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

2. Galleon configuration

The WildFly Maven Plugin depends on Galleon to provision a WildFly server installation.

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

The first required piece of information that Galleon needs is a reference to at least one WildFly Galleon feature-pack. A 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 it depends, are deployed in public maven repositories.

At plugin execution time the WildFly feature-packs are retrieved and their content is assembled to provision a server.

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 (e.g. Jakarta RESTful Web Services, MicroProfile Config, datasources) are provided by the layers you are choosing.

If you decide not to specify Galleon layers, a complete server (WildFly server zip content) is provisioned.

Following is a WildFly Maven Plugin configuration extract example:

<build>
  <plugins>
    <plugin>
      <groupId>org.wildfly.plugins</groupId>
      <artifactId>wildfly-maven-plugin</artifactId>
      <configuration>
        <feature-packs>
          <feature-pack>
            <location>wildfly@maven(org.jboss.universe:community-universe)</location> (1)
          </feature-pack>
        </feature-packs>
        <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)#34.0.0.Final

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

If your project is using WildFly Preview, the location to use is wildfly-preview@maven(org.jboss.universe:community-universe).

2.1. Specifying additional JBoss Modules modules

In general, the JBoss Modules modules your application requires are provisioned by the specified Galleon layers. To handle some special cases — for example some uses of Jakarta REST where optional RESTEasy modules are not provided by the jaxrs layer — you can explicitly add some JBoss Modules modules:

<build>
  <plugins>
    <plugin>
      <groupId>org.wildfly.plugins</groupId>
      <artifactId>wildfly-maven-plugin</artifactId>
      <configuration>
        <feature-packs>
          <feature-pack>
            <location>wildfly@maven(org.jboss.universe:community-universe)</location>
            <included-packages>
              <included-package>org.jboss.resteasy.resteasy-rxjava2</included-package> (1)
            </included-packages>
          </feature-pack>
        </feature-packs>
        ...
      </configuration>
      <executions>
        <execution>
          <goals>
            <goal>package</goal>
          </goals>
        </execution>
      </executions>
    </plugin>
  </plugins>
</build>

(1) The Specified JBoss Modules module will be included in the provisioned server.

2.2. Discovering the required Galleon configuration using WildFly Glow

The WildFly Glow Galleon configuration discovery feature has been integrated into the WildFly Maven Plugin. WildFly Glow scans the application deployment to generate a Galleon provisioning.xml file containing the Galleon feature-packs and layers that are then used by the WildFly Maven Plugin to provision the server.

Complete documentation of the discovery plugin configuration can be found in the WildFly Glow Documentation.

Here’s a WildFly Maven Plugin configuration extract example:

<build>
  <plugins>
    <plugin>
      <groupId>org.wildfly.plugins</groupId>
      <artifactId>wildfly-maven-plugin</artifactId>
      <configuration>
        <discover-provisioning-info/> (1)
      </configuration>
      <executions>
        <execution>
          <goals>
            <goal>package</goal>
          </goals>
        </execution>
      </executions>
    </plugin>
  </plugins>
</build>

(1) This option enables the discovery of Galleon feature-packs and layers.

2.3. Setting a stability level

In order to support WildFly feature stability levels, Galleon defines some options that can be used at provisioning time to provision server features at a specific stability level.

The stability level handling described in the Stability levels at provisioning time documentation applies when provisioning a WildFly server.

For example, to provision a WildFly server that includes preview features and packages:

<build>
  <plugins>
    <plugin>
      <groupId>org.wildfly.plugins</groupId>
      <artifactId>wildfly-maven-plugin</artifactId>
      <configuration>
        <feature-packs>
          <feature-pack>
            <location>wildfly@maven(org.jboss.universe:community-universe)</location>
          </feature-pack>
        </feature-packs>
        <layers>
          <layer>jaxrs-server</layer>
        </layers>
        <galleon-options>
          <stability-level>preview</stability-level>
        </galleon-options>
      </configuration>
      <executions>
        <execution>
          <goals>
            <goal>package</goal>
          </goals>
        </execution>
      </executions>
    </plugin>
  </plugins>
</build>

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 server (e.g. a server keystore).

<build>
  <plugins>
    <plugin>
      <groupId>org.wildfly.plugins</groupId>
      <artifactId>wildfly-maven-plugin</artifactId>
      <configuration>
        ...
        <packaging-scripts> (1)
          <packaging-script>
            <scripts>
              <script>scripts/script1.cli</script>
            </scripts>
          </packaging-script>
        </packaging-scripts>
        <extra-server-content-dirs> (2)
          <dir>extra-content/</dir>
        <extra-server-content-dirs>
      </configuration>
      <executions>
        <execution>
          <goals>
            <goal>package</goal>
          </goals>
        </execution>
      </executions>
    </plugin>
  </plugins>
</build>

(1) Execute the scripts/script1.cli script (2) Copy the content of the extra-content/ directory to the root of the provisioned server.

You can check the WildFly Maven Plugin documentation for more details on how to configure the WildFly Maven Plugin package goal and in particular how to execute CLI scripts and add some extra content.

4. Packaging your application

Call mvn package to provision a server and deploy your application. The directory ${project.build.directory}/server contains the WildFly installation.

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

The dev goal runs a local instance of WildFly and watches the source directories for changes. If required, your deployment will be recompiled and possibly redeployed.

You can check the WildFly Maven Plugin documentation for more details on the dev goal.

5. Packaging your application for the cloud

The WildFly project provides a complete tool chain and workflow to deploy a WildFly application on the cloud.

The steps to follow are:

  • Configure the WildFly Maven Plugin to provision a cloud ready WildFly server.

  • Push your Maven project to a Git repository (such as github.com).

  • Use the Helm Chart for WildFly to initiate the build and deployment.

Example of a cloud ready WildFly Maven Plugin configuration. Such configuration must include a reference to the WildFly cloud feature-pack:

<build>
  <plugins>
    <plugin>
      <groupId>org.wildfly.plugins</groupId>
      <artifactId>wildfly-maven-plugin</artifactId>
      <configuration>
        <feature-packs>
            <feature-pack>
                <location>org.wildfly:wildfly-galleon-pack:34.0.0.Final</location>
            </feature-pack>
            <feature-pack>
                <location>org.wildfly.cloud:wildfly-cloud-galleon-pack:7.0.0.Final</location>
            </feature-pack>
            <layers>
                <layer>cloud-server</layer>
            </layers>
        </feature-packs>
        <layers>
          <layer>jaxrs-server</layer>
        </layers>
        <galleon-options>
          <stability-level>preview</stability-level>
        </galleon-options>
      </configuration>
      <executions>
        <execution>
          <goals>
            <goal>package</goal>
          </goals>
        </execution>
      </executions>
    </plugin>
  </plugins>
</build>

When using WildFly Glow, you need to specify the cloud context in order to provision a cloud ready server. For example:

<build>
  <plugins>
    <plugin>
      <groupId>org.wildfly.plugins</groupId>
      <artifactId>wildfly-maven-plugin</artifactId>
      <configuration>
        <discover-provisioning-info>
          <context>cloud</context> (1)
        </discover-provisioning-info>
      </configuration>
      <executions>
        <execution>
          <goals>
            <goal>package</goal>
          </goals>
        </execution>
      </executions>
    </plugin>
  </plugins>
</build>

(1) Enable discovery for the cloud execution context.

Examples of projects that produce WildFly applications for the cloud can be found in the WildFly quickstarts.

You can check this documentation for more details on the WildFly cloud feature-pack .

5.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 subsystem, interfaces, socket binding) 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.

5.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)
elytron
web-server

jaxrs-server

An extension of datasources-web-server with support for Jakarta RESTful Web Services, 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)
jmx-remoting (optional)
logging (optional)
management (optional)
request-controller (optional)
security-manager (optional)

ee-core-profile-server

A Jakarta EE Core Profile server.

core-server
cdi
ee-integration
elytron
jaxrs-core
jsonp
jsonb

5.1.2. Basic Galleon Layers

Name

Description

Dependencies

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-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 and for Jakarta Concurrency.

ee-concurrency (optional)
ee-integration

ee-concurrency

Support for Jakarta Concurrency.

naming

ee-integration

Support for common functionality in the Jakarta EE platform.

jsonb (optional)
naming

ee-security

Support for EE Security.

cdi
elytron

ejb-http-invoker

Support for invoking Jakarta Enterprise Beans over HTTP.

ejb-lite
elytron
undertow

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

embedded-activemq

Support for an embedded Apache Activemq Artemis Jakarta Messaging broker.
Alternative: remote-activemq

cdi
ee
elytron
naming
remoting
messaging-activemq
undertow

git-history

Support for using git for configuration management.

health

Support for liveness and readiness checks for the server runtime.

management

hibernate-search

Support for Hibernate Search. The jpa dependency can be excluded and jpa-distributed used instead.

jpa (optional)

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

iiop-openjdk

Support for IIOP

naming

io

Support for XNIO workers and buffer pools.

base-server

jakarta-data

Support for Jakarta Data. (preview stability in WildFly Preview only) The jpa dependency can be excluded and jpa-distributed used instead.

jpa OR
jpa-distributed

jaxrs-core

Support for Jakarta RESTful Web Services.

ee-integration
servlet

jaxrs

Support for Jakarta RESTful Web Services with optional ee-concurrency and deployment scanner layers.

deployment-scanner (optional)
ee-concurrency (optional)
jaxrs-core

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

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 Faces.

bean-validation (optional)
cdi
web-server

jsonb

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

base-server

jsonp

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

base-server

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

messaging-activemq

Support for connections to a remote Jakarta Messaging broker.

resource-adapters

metrics

Support for base server metrics in Prometheus format.

management

micrometer

Support for Micrometer

cdi

microprofile-config

Support for MicroProfile Config.

cdi

microprofile-fault-tolerance

Support for MicroProfile Fault Tolerance.

cdi
microprofile-config

microprofile-health

Support for MicroProfile Health.

management
microprofile-config

microprofile-jwt

Support for MicroProfile JWT.

ee-security
microprofile-config

microprofile-lra-coordinator

Support for acting as coordinator of MicroProfile LRA long-running actions.

cdi
jaxrs
transactions
microprofile-config (optional)

microprofile-lra-participant

Support for acting as a participant in MicroProfile LRA long-running actions.

cdi
jaxrs
microprofile-config (optional)

microprofile-openapi

Support for MicroProfile OpenAPI.

jaxrs
microprofile-config

microprofile-platform

Support for available MicroProfile platform specifications.

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

microprofile-rest-client

Support for MicroProfile REST client.

microprofile-config

microprofile-reactive-messaging

Support for MicroProfile Reactive Messaging

cdi
reactive-streams-operators

microprofile-reactive-messaging-amqp

Support for MicroProfile Reactive Messaging AMQP connector

reactive-messaging

microprofile-reactive-messaging-kafka

Support for MicroProfile Reactive Messaging Kafka connector

reactive-messaging

microprofile-reactive-streams-operators

Support for MicroProfile Reactive Streams Operators

cdi

microprofile-telemetry

Support for MicroProfile Telemetry

cdi
microprofile-config
opentelemetry

mod_cluster

Support for mod_cluster subsystem.

web-server

mvc-krazo

Support for Jakarta MVC (preview stability)

bean-validation
cdi
jaxrs-core
jsf (optional)

naming

Support for JNDI.

base-server

observability

Support for MicroProfile monitoring features.

microprofile-config (optional)
microprofile-health (optional)
microprofile-telemetry (optional)

opentelemetry

Support for OpenTelemetry

cdi

pojo

Support for legacy JBoss Microcontainer applications.

base-server

remote-activemq

Support for connections to a remote Apache Activemq Artemis Jakarta Messaging broker.
Alternative: embedded-activemq

messaging-activemq

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 Jakarta Connectors resource 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

servlet

A servlet container.

ee-integration
naming
undertow

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

undertow-https

Support for the Undertow HTTPS server secured using the applicationSSC SSLContext.

elytron
undertow

undertow-load-balancer

Support for Undertow configured as a load balancer.

base-server
io

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
ee-concurrency (optional)
naming
servlet

webservices

Support for Jakarta XML Web Services

ejb-lite (optional)
messaging-activemq (optional)
web-server
References in this document to Java Persistence API (JPA) refer to the Jakarta Persistence unless otherwise noted. References in this document to Enterprise JavaBeans (EJB) refer to the Jakarta Enterprise Beans unless otherwise noted.