From 83e930baf300f93079cd7864728e4e064350c95b 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 | 673 ++++++++++++++++++++++ data/guides.yaml | 7 + 2 files changed, 680 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..83c73d2f --- /dev/null +++ b/content/guides/wildfly-jar-migration.adoc @@ -0,0 +1,673 @@ +--- +layout: guide +--- += Migrating from WildFly JAR Maven Plugin to WildFly Maven Plugin +:summary: Learn how to migrate from WildFly JAR Maven Plugin to WildFly Maven Plugin to build a WildFly Bootable JAR. +:includedir: /templates +include::../../templates/partials/guides/attributes.adoc[] +:prerequisites-time: 10 +:wildfly-version: 40.0.0.Final +:cloud-version: 9.2.3.Final +:bootable-maven-plugin-version: 13.0.0.Final +:wildfly-maven-plugin-version: 6.0.0.Final + +In this guide, you will learn how to migrate from WildFly JAR Maven Plugin to 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` + +|*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 as 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 WildFly JAR Maven Plugin. + +*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 + +Using the cloud feature-pack is identical to the `` element usage. +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 + +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: + +* `` → `` +* `` → `` +* `` → `` + +=== Step 6: Rename Other Parameters (If Used) + +If you use any of these optional parameters, rename them: + +[cols="1,1",options="header"] +|=== +|Old Parameter |New Parameter + +|`` +|`` + +|`` +|`` + +|`` +|`` + +|`` +|`` + +|`` +|`` +|=== + +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`. +To start a bootable JAR uses the `wildfly:start-jar` goal. +Update your build commands to use the new goal prefixes. + +*Before*: +[source,bash] +---- +mvn wildfly-jar:package +mvn wildfly-jar:run +mvn wildfly-jar:dev +mvn wildfly-jar:start +mvn wildfly-jar:shutdown +---- + +*After*: +[source,bash] +---- +mvn wildfly:package +mvn wildfly:run +mvn wildfly:dev +mvn wildfly:start-jar +mvn wildfly:shutdown +---- + +== 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 + + + 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 + + + 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 + + + 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: