From 43d7f1e430cbdacda4da8d6488281e3471fa8df9 Mon Sep 17 00:00:00 2001 From: Jean-Francois Denise Date: Fri, 12 Jun 2026 10:06:20 +0200 Subject: [PATCH] Bootable JAR creation migration guide --- content/guides/wildfly-jar-migration.adoc | 741 ++++++++++++++++++++++ data/guides.yaml | 7 + 2 files changed, 748 insertions(+) create mode 100644 content/guides/wildfly-jar-migration.adoc diff --git a/content/guides/wildfly-jar-migration.adoc b/content/guides/wildfly-jar-migration.adoc new file mode 100644 index 00000000..04dafa2a --- /dev/null +++ b/content/guides/wildfly-jar-migration.adoc @@ -0,0 +1,741 @@ +--- +layout: guide +--- += Migrating from WildFly JAR Maven Plugin to WildFly Maven Plugin +:summary: Learn how to migrate from the WildFly JAR Maven Plugin to the WildFly Maven Plugin to build a WildFly Bootable JAR. +:includedir: /templates +include::../../templates/partials/guides/attributes.adoc[] +:prerequisites-time: 10 +:wildfly-version: 41.0.1.Final +:cloud-version: 9.2.3.Final +:bootable-maven-plugin-version: 13.0.0.Final +:wildfly-maven-plugin-version: 6.0.1.Final + +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. + +include::../../templates/partials/guides/prerequisites.adoc[] + +== 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 + +[cols="1,2,2",options="header"] +|=== +|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) +|`true` + +|*Single feature-pack location* +|`{feature-pack location}` +|`{feature-pack location}` + +|*Cloud Support* +|`` element +|`wildfly-cloud-galleon-pack` feature-pack + +|*Hollow JAR* +|`true` +|`true` + +|*Output JAR Name* +|`` +|`` + +|*Deployment in the root context* +|`true` (the default) +|`ROOT.war` (WAR projects only) + +|*CLI Scripts* +|`` +|`` + +|*Galleon Options* +|`` +|`` + +|*Offline Mode* +|`` +|`` + +|*Log Time* +|`` +|`` + +|*Record State* +|`` +|`` + +|*Extra Content* +|`` +|`` (same) +|=== + +== Migration Steps + +=== Step 1: Update Plugin Coordinates + +*Before* (WildFly JAR Maven Plugin): +[source,xml,subs="normal"] +---- + + org.wildfly.plugins + wildfly-jar-maven-plugin + {bootable-maven-plugin-version} + + + + + + package + + + + +---- + +*After* (WildFly Maven Plugin): +[source,xml,subs="normal"] +---- + + org.wildfly.plugins + wildfly-maven-plugin + {wildfly-maven-plugin-version} + + + + + + package + + + + +---- + +=== Step 2: Enable Bootable JAR Mode + +Add `true` to enable bootable JAR packaging. + +*Before*: +[source,xml,subs="normal"] +---- + + org.wildfly:wildfly-galleon-pack:{wildfly-version} + + jaxrs-server + microprofile-platform + + + true + + +---- + +*After*: +[source,xml,subs="normal"] +---- + + true + + + org.wildfly:wildfly-galleon-pack:{wildfly-version} + + + + jaxrs-server + microprofile-platform + + + true + + +---- + +NOTE: The `` 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*: +[source,xml,subs="normal"] +---- + + + + org.wildfly:wildfly-galleon-pack:{wildfly-version} + + + + jaxrs-server + microprofile-platform + + + true + + +---- + +*After*: +[source,xml,subs="normal"] +---- + + true + + + org.wildfly:wildfly-galleon-pack:{wildfly-version} + + + + jaxrs-server + microprofile-platform + + + true + + ROOT.war + +---- + +=== Step 4: Migrate Cloud Configuration (If Used) + +If you use the `` element, replace it with the WildFly cloud feature-pack: + +*Remove*: +[source,xml] +---- + +---- + +*Add to feature-packs*: +[source,xml,subs="normal"] +---- + + org.wildfly.cloud:wildfly-cloud-galleon-pack:{cloud-version} + +---- + +==== What the Cloud Feature Pack Provides + +The `wildfly-cloud-galleon-pack` covers the same core capabilities as the `` element. +When building a WildFly bootable JAR with the `wildfly-cloud-galleon-pack`, the following capabilities are provisioned: + +. *Health Monitoring*: Automatic inclusion of the health subsystem, enabling liveness and readiness probes for container orchestration platforms (Kubernetes, OpenShift) +. *Console Logging*: Server logs are automatically routed to the console for easier monitoring in containerized environments +. *Cloud-Optimized Layer Adjustments*: Automatic modification of WildFly Galleon layers to ensure compatibility with cloud execution environments +. *Boot-Time Cloud Configuration*: Special cloud-specific configuration applied at boot time to optimize for cloud deployment + +==== Migrating the `enable-jgroups-password` option + +The `` element accepted an `` 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 https://docs.wildfly.org/wildfly-cloud-galleon-pack/[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*: +[source,xml] +---- + + + + + + + +---- + +*WildFly Maven Plugin*: +[source,xml] +---- + + + + + + + +---- + +Element name changes: + +* `` → `` +* `` → `` +* `` → `` + +NOTE: The `` 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 `true` +explicitly inside each `` to restore expression resolution: + +[source,xml] +---- + + + + + + true + + +---- + +=== Step 6: Rename Other Parameters (If Used) + +If you use any of these optional parameters, rename them. + +[cols="1,1,2",options="header"] +|=== +|Old Parameter |New Parameter |Notes + +|`` +|`` +| + +|`` +|`` +| + +|`` +|`` +| + +|`` +|`` +| + +|`` +|`` +| + +|`` +|`` +| + +|`` +|`` +|The old parameter was a boolean. The new `` accepts a string: `System.out` (default, equivalent to `true`), +`System.err`, `none` (equivalent to `false`), or a file path to redirect output. +|=== + +NOTE: The `` parameter (overrides the `logging.properties` ) has no equivalent in the WildFly Maven Plugin. +Use the `` 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: + +[source,xml] +---- + + ${project.build.finalName}-bootable.jar + +---- + +=== Step 7: Update Maven Goals + +The goal prefix changed from `wildfly-jar` to `wildfly`. +Update your build commands according to the table below. + +[cols="1,1,2",options="header"] +|=== +|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: + +[source,xml] +---- + + + -bmanagement=0.0.0.0 + + + -Xmx512m + + +---- + +== Complete Examples + +=== Example 1: Simple JAX-RS Application + +*Before* (wildfly-jar-maven-plugin): +[source,xml,subs="normal"] +---- + + org.wildfly.plugins + wildfly-jar-maven-plugin + {bootable-maven-plugin-version} + + + + org.wildfly:wildfly-galleon-pack:{wildfly-version} + + + + jaxrs-server + + + + + + package + + + + +---- + +*After* (wildfly-maven-plugin): +[source,xml,subs="normal"] +---- + + org.wildfly.plugins + wildfly-maven-plugin + {wildfly-maven-plugin-version} + + true + ROOT.war + + + org.wildfly:wildfly-galleon-pack:{wildfly-version} + + + + jaxrs-server + + + + + + package + + + + +---- + +=== Example 2: Hollow JAR (Server Only, No Deployment) + +*Before*: +[source,xml,subs="normal"] +---- + + org.wildfly.plugins + wildfly-jar-maven-plugin + {bootable-maven-plugin-version} + + + + org.wildfly:wildfly-galleon-pack:{wildfly-version} + + + + jaxrs-server + + true + + + + + package + + + + +---- + +*After*: +[source,xml,subs="normal"] +---- + + org.wildfly.plugins + wildfly-maven-plugin + {wildfly-maven-plugin-version} + + true + true + + + org.wildfly:wildfly-galleon-pack:{wildfly-version} + + + + jaxrs-server + + + + + + package + + + + +---- + +=== Example 3: Custom Bootable JAR Output Name and root context + +*Before*: +[source,xml,subs="normal"] +---- + + org.wildfly.plugins + wildfly-jar-maven-plugin + {bootable-maven-plugin-version} + + my-custom-server.jar + + + org.wildfly:wildfly-galleon-pack:{wildfly-version} + + + + jaxrs-server + + + + + + package + + + + +---- + +*After*: +[source,xml,subs="normal"] +---- + + org.wildfly.plugins + wildfly-maven-plugin + {wildfly-maven-plugin-version} + + true + my-custom-server.jar + ROOT.war + + + org.wildfly:wildfly-galleon-pack:{wildfly-version} + + + + jaxrs-server + + + + + + package + + + + +---- + +=== Example 4: Cloud Migration Example + +This example shows a migration with cloud support: + +*Before*: +[source,xml,subs="normal"] +---- + + org.wildfly.plugins + wildfly-jar-maven-plugin + {bootable-maven-plugin-version} + + + + org.wildfly:wildfly-galleon-pack:{wildfly-version} + + + + jaxrs-server + + + + true + + + + + + package + + + + +---- + +*After*: +[source,xml,subs="normal"] +---- + + org.wildfly.plugins + wildfly-maven-plugin + {wildfly-maven-plugin-version} + + true + ROOT.war + + + org.wildfly:wildfly-galleon-pack:{wildfly-version} + + + org.wildfly.cloud:wildfly-cloud-galleon-pack:{cloud-version} + + + + jaxrs-server + + + true + + + + + + package + + + + +---- + +=== Example 5: Application with CLI Configuration + +*Before*: +[source,xml,subs="normal"] +---- + + org.wildfly.plugins + wildfly-jar-maven-plugin + {bootable-maven-plugin-version} + + + + org.wildfly:wildfly-galleon-pack:{wildfly-version} + + + + jaxrs-server + microprofile-platform + + + + + + + + + + + + + package + + + + +---- + +*After*: +[source,xml,subs="normal"] +---- + + org.wildfly.plugins + wildfly-maven-plugin + {wildfly-maven-plugin-version} + + true + ROOT.war + + + org.wildfly:wildfly-galleon-pack:{wildfly-version} + + + + jaxrs-server + microprofile-platform + + + + + + + + + + + + + package + + + + +---- + +== What's next? + +To benefit from new provisioning features, you should migrate to the WildFly Maven Plugin. +For example, producing a Bootable JAR using https://docs.wildfly.org/wildfly-glow/[WildFly Glow] is only available in the WildFly Maven Plugin. + +== Resources + +* https://docs.wildfly.org/wildfly-maven-plugin/[WildFly Maven Plugin Documentation] +* https://docs.wildfly.org/bootablejar/[WildFly Bootable JAR Guide] +* https://docs.wildfly.org/wildfly-cloud-galleon-pack/[WildFly Cloud Feature Pack Documentation] diff --git a/data/guides.yaml b/data/guides.yaml index 1427d549..c400c2da 100644 --- a/data/guides.yaml +++ b/data/guides.yaml @@ -112,6 +112,13 @@ categories: # - title: Using MicroProfile LRA # url: /guides/use-microprofile-lra # description: Discover how to use MicroProfile LRA With WildFly. + - category: Migration + cat-id: migration + guides: + - title: Migrating from WildFly JAR Maven Plugin to WildFly Maven Plugin + url: /guides/wildfly-jar-migration + description: Learn how to migrate to the WildFly Maven Plugin to build a Bootable JAR + keywords: Migration, Maven, Bootable, Provisioning, Cloud - category: Observability cat-id: observability guides: