Migrating from WildFly JAR Maven Plugin to WildFly Maven Plugin

In this guide, you will learn how to migrate from the WildFly JAR Maven Plugin to the WildFly Maven Plugin to build a WildFly Bootable JAR.

Prerequisites

To complete this guide, you need:

  • Roughly 10 minutes

  • JDK 17+ installed with JAVA_HOME configured appropriately

  • Apache Maven 3.9+

Background

The WildFly JAR Maven Plugin was originally introduced to create bootable JARs (self-contained executable JARs containing WildFly and your application). Starting with version 5.0, the WildFly Maven Plugin consolidated this functionality, making the separate JAR plugin unnecessary.

Why Migrate?

  • Single Plugin: Consolidates provisioning, deployment, and bootable JAR creation into one plugin

  • Active Development: The WildFly Maven Plugin is the actively maintained solution

  • Future Features: New features and improvements are being added to the WildFly Maven Plugin

  • Deprecation: The WildFly JAR Maven Plugin is deprecated and may be removed in future releases

Plugin Differences: WildFly JAR Maven Plugin vs WildFly Maven Plugin

Aspect WildFly JAR Maven Plugin WildFly Maven Plugin

Artifact ID

wildfly-jar-maven-plugin

wildfly-maven-plugin

Goals

wildfly-jar:package, wildfly-jar:start

wildfly:package, wildfly:start-jar

Enable Bootable JAR

Implicit (plugin purpose)

<bootable-jar>true</bootable-jar>

Single feature-pack location

<feature-pack-location>{feature-pack location}</feature-pack-location>

<feature-packs><feature-pack><location>{feature-pack location}</location></feature-pack></feature-packs>

Cloud Support

<cloud/> element

wildfly-cloud-galleon-pack feature-pack

Hollow JAR

<hollow-jar>true</hollow-jar>

<skipDeployment>true</skipDeployment>

Output JAR Name

<output-file-name>

<bootable-jar-name>

Deployment in the root context

<context-root>true</context-root> (the default)

<name>ROOT.war</name> (WAR projects only)

CLI Scripts

<cli-sessions>

<packaging-scripts>

Galleon Options

<plugin-options>

<galleon-options>

Offline Mode

<offline>

<offline-provisioning>

Log Time

<log-time>

<log-provisioning-time>

Record State

<record-state>

<record-provisioning-state>

Extra Content

<extra-server-content-dirs>

<extra-server-content-dirs> (same)

Migration Steps

Step 1: Update Plugin Coordinates

Before (WildFly JAR Maven Plugin):

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

After (WildFly Maven Plugin):

<plugin>
    <groupId>org.wildfly.plugins</groupId>
    <artifactId>wildfly-maven-plugin</artifactId>
    <version>6.0.1.Final</version>
    <configuration>
    </configuration>
    <executions>
        <execution>
            <goals>
                <goal>package</goal>
            </goals>
        </execution>
    </executions>
</plugin>

Step 2: Enable Bootable JAR Mode

Add <bootable-jar>true</bootable-jar> to enable bootable JAR packaging.

Before:

<configuration>
    <feature-pack-location>org.wildfly:wildfly-galleon-pack:41.0.1.Final</feature-pack-location>
    <layers>
        <layer>jaxrs-server</layer>
        <layer>microprofile-platform</layer>
    </layers>
    <plugin-options>
        <jboss-fork-embedded>true</jboss-fork-embedded>
    </plugin-options>
</configuration>

After:

<configuration>
    <bootable-jar>true</bootable-jar>
    <feature-packs>
        <feature-pack>
            <location>org.wildfly:wildfly-galleon-pack:41.0.1.Final</location>
        </feature-pack>
    </feature-packs>
    <layers>
        <layer>jaxrs-server</layer>
        <layer>microprofile-platform</layer>
    </layers>
    <galleon-options>
        <jboss-fork-embedded>true</jboss-fork-embedded>
    </galleon-options>
</configuration>
Note
 The <feature-pack-location> element has to be replaced by a nested location in the array of feature-packs.

Step 3: Migrate the deployment in the root context

This was the default with the WildFly JAR Maven Plugin. This step only applies to WAR projects.

Before:

<configuration>
    <feature-packs>
        <feature-pack>
            <location>org.wildfly:wildfly-galleon-pack:41.0.1.Final</location>
        </feature-pack>
    </feature-packs>
    <layers>
        <layer>jaxrs-server</layer>
        <layer>microprofile-platform</layer>
    </layers>
    <plugin-options>
        <jboss-fork-embedded>true</jboss-fork-embedded>
    </plugin-options>
</configuration>

After:

<configuration>
    <bootable-jar>true</bootable-jar>
    <feature-packs>
        <feature-pack>
            <location>org.wildfly:wildfly-galleon-pack:41.0.1.Final</location>
        </feature-pack>
    </feature-packs>
    <layers>
        <layer>jaxrs-server</layer>
        <layer>microprofile-platform</layer>
    </layers>
    <galleon-options>
        <jboss-fork-embedded>true</jboss-fork-embedded>
    </galleon-options>
    <name>ROOT.war</name>
</configuration>

Step 4: Migrate Cloud Configuration (If Used)

If you use the <cloud/> element, replace it with the WildFly cloud feature-pack:

Remove:

<cloud/>

Add to feature-packs:

<feature-pack>
    <location>org.wildfly.cloud:wildfly-cloud-galleon-pack:9.2.3.Final</location>
</feature-pack>

What the Cloud Feature Pack Provides

The wildfly-cloud-galleon-pack covers the same core capabilities as the <cloud/> element. When building a WildFly bootable JAR with the wildfly-cloud-galleon-pack, the following capabilities are provisioned:

  1. Health Monitoring: Automatic inclusion of the health subsystem, enabling liveness and readiness probes for container orchestration platforms (Kubernetes, OpenShift)

  2. Console Logging: Server logs are automatically routed to the console for easier monitoring in containerized environments

  3. Cloud-Optimized Layer Adjustments: Automatic modification of WildFly Galleon layers to ensure compatibility with cloud execution environments

  4. Boot-Time Cloud Configuration: Special cloud-specific configuration applied at boot time to optimize for cloud deployment

Migrating the enable-jgroups-password option

The <cloud/> element accepted an <enable-jgroups-password> child option to enable JGroups cluster authentication. This option does not exist in the WildFly Maven Plugin. Instead, set the JGROUPS_CLUSTER_PASSWORD environment variable at runtime: JGroups authentication is enabled automatically when the variable is present.

For more details, see the WildFly Cloud Feature Pack documentation.

Step 5: Rename CLI scripts configuration (If used)

The CLI execution configuration has more extensive renaming:

WildFly JAR Maven Plugin:

<cli-sessions>
    <cli-session>
        <script-files>
            <script>configure.cli</script>
        </script-files>
    </cli-session>
</cli-sessions>

WildFly Maven Plugin:

<packaging-scripts>
    <packaging-script>
        <scripts>
            <script>configure.cli</script>
        </scripts>
    </packaging-script>
</packaging-scripts>

Element name changes:

  • <cli-sessions> → <packaging-scripts>

  • <cli-session> → <packaging-script>

  • <script-files> → <scripts>

Note
 The <resolve-expressions> parameter defaulted to true in the WildFly JAR Maven Plugin but defaults to false in the WildFly Maven Plugin. If your CLI scripts contain ${env.VAR} or similar expressions, add <resolve-expressions>true</resolve-expressions> explicitly inside each <packaging-script> to restore expression resolution: 
<packaging-scripts>
    <packaging-script>
        <scripts>
            <script>configure.cli</script>
        </scripts>
        <resolve-expressions>true</resolve-expressions>
    </packaging-script>
</packaging-scripts>

Step 6: Rename Other Parameters (If Used)

If you use any of these optional parameters, rename them.

Old Parameter New Parameter Notes

<output-file-name>

<bootable-jar-name>

<offline>

<offline-provisioning>

<log-time>

<log-provisioning-time>

<record-state>

<record-provisioning-state>

<hollow-jar>

<skipDeployment>

<install-artifact-classifier>

<bootable-jar-install-artifact-classifier>

<display-cli-scripts-output>

<stdout>

The old parameter was a boolean. The new <stdout> accepts a string: System.out (default, equivalent to true), System.err, none (equivalent to false), or a file path to redirect output.
Note
 The <boot-logging-config> parameter (overrides the logging.properties ) has no equivalent in the WildFly Maven Plugin. Use the <extra-server-content-dirs> to provide your own logging.properties file.
Note
 The default value for the Bootable JAR file name changed from ${project.build.finalName}-bootable.jar to ${project.artifactId}-bootable.jar. If you need to keep the old naming convention: 
<configuration>
    <bootable-jar-name>${project.build.finalName}-bootable.jar</bootable-jar-name>
</configuration>

Step 7: Update Maven Goals

The goal prefix changed from wildfly-jar to wildfly. Update your build commands according to the table below.

Old Goal New Goal Notes

wildfly-jar:package

wildfly:package

No behaviour change.

wildfly-jar:start

wildfly:start-jar

Starts the bootable JAR in the background.

wildfly-jar:shutdown

wildfly:shutdown

No behaviour change.

wildfly-jar:run

wildfly:start-jar

wildfly:run exists but starts a regular provisioned server, not a bootable JAR. Use wildfly:start-jar to run the bootable JAR.

wildfly-jar:dev

—

No direct equivalent. wildfly:dev starts a regular server, not a bootable JAR.

wildfly-jar:dev-watch

—

No direct equivalent in the WildFly Maven Plugin.
Note
 The arguments and jvmArguments parameters used with wildfly-jar:run and wildfly-jar:dev have no automatic equivalent. Use the server-args and java-opts parameters of the wildfly:start-jar goal instead: 
<configuration>
    <server-args>
        <server-arg>-bmanagement=0.0.0.0</server-arg>
    </server-args>
    <java-opts>
        <java-opt>-Xmx512m</java-opt>
    </java-opts>
</configuration>

Complete Examples

Example 1: Simple JAX-RS Application

Before (wildfly-jar-maven-plugin):

<plugin>
    <groupId>org.wildfly.plugins</groupId>
    <artifactId>wildfly-jar-maven-plugin</artifactId>
    <version>13.0.0.Final</version>
    <configuration>
        <feature-packs>
            <feature-pack>
                <location>org.wildfly:wildfly-galleon-pack:41.0.1.Final</location>
            </feature-pack>
        </feature-packs>
        <layers>
            <layer>jaxrs-server</layer>
        </layers>
    </configuration>
    <executions>
        <execution>
            <goals>
                <goal>package</goal>
            </goals>
        </execution>
    </executions>
</plugin>

After (wildfly-maven-plugin):

<plugin>
    <groupId>org.wildfly.plugins</groupId>
    <artifactId>wildfly-maven-plugin</artifactId>
    <version>6.0.1.Final</version>
    <configuration>
        <bootable-jar>true</bootable-jar>
        <name>ROOT.war</name>
        <feature-packs>
            <feature-pack>
                <location>org.wildfly:wildfly-galleon-pack:41.0.1.Final</location>
            </feature-pack>
        </feature-packs>
        <layers>
            <layer>jaxrs-server</layer>
        </layers>
    </configuration>
    <executions>
        <execution>
            <goals>
                <goal>package</goal>
            </goals>
        </execution>
    </executions>
</plugin>

Example 2: Hollow JAR (Server Only, No Deployment)

Before:

<plugin>
    <groupId>org.wildfly.plugins</groupId>
    <artifactId>wildfly-jar-maven-plugin</artifactId>
    <version>13.0.0.Final</version>
    <configuration>
        <feature-packs>
            <feature-pack>
                <location>org.wildfly:wildfly-galleon-pack:41.0.1.Final</location>
            </feature-pack>
        </feature-packs>
        <layers>
            <layer>jaxrs-server</layer>
        </layers>
        <hollow-jar>true</hollow-jar>
    </configuration>
    <executions>
        <execution>
            <goals>
                <goal>package</goal>
            </goals>
        </execution>
    </executions>
</plugin>

After:

<plugin>
    <groupId>org.wildfly.plugins</groupId>
    <artifactId>wildfly-maven-plugin</artifactId>
    <version>6.0.1.Final</version>
    <configuration>
        <bootable-jar>true</bootable-jar>
        <skipDeployment>true</skipDeployment>
        <feature-packs>
            <feature-pack>
                <location>org.wildfly:wildfly-galleon-pack:41.0.1.Final</location>
            </feature-pack>
        </feature-packs>
        <layers>
            <layer>jaxrs-server</layer>
        </layers>
    </configuration>
    <executions>
        <execution>
            <goals>
                <goal>package</goal>
            </goals>
        </execution>
    </executions>
</plugin>

Example 3: Custom Bootable JAR Output Name and root context

Before:

<plugin>
    <groupId>org.wildfly.plugins</groupId>
    <artifactId>wildfly-jar-maven-plugin</artifactId>
    <version>13.0.0.Final</version>
    <configuration>
        <output-file-name>my-custom-server.jar</output-file-name>
        <feature-packs>
            <feature-pack>
                <location>org.wildfly:wildfly-galleon-pack:41.0.1.Final</location>
            </feature-pack>
        </feature-packs>
        <layers>
            <layer>jaxrs-server</layer>
        </layers>
    </configuration>
    <executions>
        <execution>
            <goals>
                <goal>package</goal>
            </goals>
        </execution>
    </executions>
</plugin>

After:

<plugin>
    <groupId>org.wildfly.plugins</groupId>
    <artifactId>wildfly-maven-plugin</artifactId>
    <version>6.0.1.Final</version>
    <configuration>
        <bootable-jar>true</bootable-jar>
        <bootable-jar-name>my-custom-server.jar</bootable-jar-name>
        <name>ROOT.war</name>
        <feature-packs>
            <feature-pack>
                <location>org.wildfly:wildfly-galleon-pack:41.0.1.Final</location>
            </feature-pack>
        </feature-packs>
        <layers>
            <layer>jaxrs-server</layer>
        </layers>
    </configuration>
    <executions>
        <execution>
            <goals>
                <goal>package</goal>
            </goals>
        </execution>
    </executions>
</plugin>

Example 4: Cloud Migration Example

This example shows a migration with cloud support:

Before:

<plugin>
    <groupId>org.wildfly.plugins</groupId>
    <artifactId>wildfly-jar-maven-plugin</artifactId>
    <version>13.0.0.Final</version>
    <configuration>
        <feature-packs>
            <feature-pack>
                <location>org.wildfly:wildfly-galleon-pack:41.0.1.Final</location>
            </feature-pack>
        </feature-packs>
        <layers>
            <layer>jaxrs-server</layer>
        </layers>
        <cloud/>
        <plugin-options>
            <jboss-fork-embedded>true</jboss-fork-embedded>
        </plugin-options>
    </configuration>
    <executions>
        <execution>
            <goals>
                <goal>package</goal>
            </goals>
        </execution>
    </executions>
</plugin>

After:

<plugin>
    <groupId>org.wildfly.plugins</groupId>
    <artifactId>wildfly-maven-plugin</artifactId>
    <version>6.0.1.Final</version>
    <configuration>
        <bootable-jar>true</bootable-jar>
        <name>ROOT.war</name>
        <feature-packs>
            <feature-pack>
                <location>org.wildfly:wildfly-galleon-pack:41.0.1.Final</location>
            </feature-pack>
            <feature-pack>
                <location>org.wildfly.cloud:wildfly-cloud-galleon-pack:9.2.3.Final</location>
            </feature-pack>
        </feature-packs>
        <layers>
            <layer>jaxrs-server</layer>
        </layers>
        <galleon-options>
            <jboss-fork-embedded>true</jboss-fork-embedded>
        </galleon-options>
    </configuration>
    <executions>
        <execution>
            <goals>
                <goal>package</goal>
            </goals>
        </execution>
    </executions>
</plugin>

Example 5: Application with CLI Configuration

Before:

<plugin>
    <groupId>org.wildfly.plugins</groupId>
    <artifactId>wildfly-jar-maven-plugin</artifactId>
    <version>13.0.0.Final</version>
    <configuration>
        <feature-packs>
            <feature-pack>
                <location>org.wildfly:wildfly-galleon-pack:41.0.1.Final</location>
            </feature-pack>
        </feature-packs>
        <layers>
            <layer>jaxrs-server</layer>
            <layer>microprofile-platform</layer>
        </layers>
        <cli-sessions>
            <cli-session>
                <script-files>
                    <script>configure.cli</script>
                </script-files>
            </cli-session>
        </cli-sessions>
    </configuration>
    <executions>
        <execution>
            <goals>
                <goal>package</goal>
            </goals>
        </execution>
    </executions>
</plugin>

After:

<plugin>
    <groupId>org.wildfly.plugins</groupId>
    <artifactId>wildfly-maven-plugin</artifactId>
    <version>6.0.1.Final</version>
    <configuration>
        <bootable-jar>true</bootable-jar>
        <name>ROOT.war</name>
        <feature-packs>
            <feature-pack>
                <location>org.wildfly:wildfly-galleon-pack:41.0.1.Final</location>
            </feature-pack>
        </feature-packs>
        <layers>
            <layer>jaxrs-server</layer>
            <layer>microprofile-platform</layer>
        </layers>
        <packaging-scripts>
            <packaging-script>
                <scripts>
                    <script>configure.cli</script>
                </scripts>
            </packaging-script>
        </packaging-scripts>
    </configuration>
    <executions>
        <execution>
            <goals>
                <goal>package</goal>
            </goals>
        </execution>
    </executions>
</plugin>

What’s next?

To benefit from new provisioning features, you should migrate to the WildFly Maven Plugin. For example, producing a Bootable JAR using WildFly Glow is only available in the WildFly Maven Plugin.

Resources

< Back to Guides

WildFly is fully open. All components are open source and follow a community-focused development process.

This website was built with Roq, is hosted on Github Pages and is completely open source. If you want to make it better, fork it and show us what you’ve got.

Navigation
Contribute
Get Help
Find more Community Projects used with WildFly
CC by 3.0
Copyright © WildFly. All rights reserved. For details on our trademarks, please visit our Trademark Policy and Trademark List. Trademarks of third parties are owned by their respective holders and their mention here does not suggest any endorsement or association.