2024. 03. 10.

10:19 Bootable JAR Guide

Bootable JAR Guide

WildFly team
Version 31.0.0.Final, 2024-01-24T15:29:51Z

https://docs.wildfly.org/31/Bootable_Guide.html 1/17
2024. 03. 10. 10:19 Bootable JAR Guide

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

https://docs.wildfly.org/31/Bootable_Guide.html 2/17
2024. 03. 10. 10:19 Bootable JAR Guide

© 2020 The original authors.

https://docs.wildfly.org/31/Bootable_Guide.html 3/17
2024. 03. 10. 10:19 Bootable JAR Guide

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 (https://github.com/wildfly-extras/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
(https://docs.wildfly.org/bootablejar/).

https://docs.wildfly.org/31/Bootable_Guide.html 4/17
2024. 03. 10. 10:19 Bootable JAR Guide

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.

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

https://docs.wildfly.org/31/Bootable_Guide.html 5/17
2024. 03. 10. 10:19 Bootable JAR Guide

2. Galleon configuration
The Bootable JAR Maven plugin depends on Galleon (https://docs.wildfly.org/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: Jakarta RESTful Web Services, 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:

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

https://docs.wildfly.org/31/Bootable_Guide.html 6/17
2024. 03. 10. 10:19 Bootable JAR Guide

If your project is using WildFly Preview, the feature-pack-location to use is wildfly-

 preview@maven(org.jboss.universe:community-universe) .

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

https://docs.wildfly.org/31/Bootable_Guide.html 7/17
2024. 03. 10. 10:19 Bootable JAR Guide

Name Description Dependencies

jaxrs-server An extension of datasources-web-server with support for bean-validation (optional)

Jakarta RESTful Web Services, CDI and JPA. cdi (optional)
datasources-web-server
jaxrs (optional)
jpa (optional)
microprofile-rest-client
(optional)

cloud-server An extension of jaxrs-server to address common cloud ee-security (optional)

requirements. jaxrs-server
jms-activemq (optional)
observability (optional)
resource-adapters
(optional)

core-server A typical manageable server core. This layer could serve core-management
as a base for a more specialized WildFly that doesn’t (optional)
need the capabilities provided by the other foundational jmx-remoting (optional)
layers. 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

2.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)

https://docs.wildfly.org/31/Bootable_Guide.html 8/17
2024. 03. 10. 10:19 Bootable JAR Guide

cloud-profile An aggregation of some basic layers to address cloud use bean-validation (optional)
cases. 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 management (optional)
scripts and configuration files.

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

platform and for Jakarta Concurrency. ee-integration

ee-concurrency Support for Jakarta Concurrency. naming

ee-integration Support for common functionality in the Jakarta EE jsonb (optional)

platform. naming

ee-security Support for EE Security. cdi

elytron

ejb-http-invoker Support for invoking Jakarta Enterprise Beans over ejb-lite

HTTP. elytron
undertow

ejb Support for Jakarta Enterprise Beans, excluding the IIOP ejb-lite
protocol. messaging-activemq
remoting
resource-adapters
undertow

ejb-dist-cache Infinispan-based distributed cache for stateful session transactions

beans.
Alternative: ejb-local-cache

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

Alternative: ejb-dist-cache

https://docs.wildfly.org/31/Bootable_Guide.html 9/17
2024. 03. 10. 10:19 Bootable JAR Guide

elytron Support for Elytron security. base-server

embedded-activemq Support for an embedded Apache Activemq Artemis cdi

Jakarta Messaging broker. ee
Alternative: remote-activemq elytron
naming
remoting
messaging-activemq
undertow

git-history Support for using git for configuration management.

hibernate-search Support for Hibernate Search. The jpa dependency can jpa (optional)
be excluded and jpa-distributed used instead.

h2-datasource Support for an H2 datasource h2-driver

h2-default-datasource Support for an H2 datasource set as the ee subsystem h2-datasource

default 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

jaxrs-core Support for Jakarta RESTful Web Services. ee-integration

servlet

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

jdr Support for the JBoss Diagnostic Reporting (JDR) base-server

subsystem. 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 bean-validation (optional)
Hibernate release). datasources
Alternative: jpa-distributed

jpa-distributed Support for JPA with a distributed second level cache. bean-validation (optional)
Alternative: jpa datasources

https://docs.wildfly.org/31/Bootable_Guide.html 10/17
2024. 03. 10. 10:19 Bootable JAR Guide

jsf Support for Jakarta Faces. bean-validation (optional)

cdi
web-server

jsonb Support for JSON Binding (Jakarta JSON Binding) base-server

provisioning the Jakarta JSON Binding API and
Implementation modules.

jsonp Support for JSON Processing (Jakarta JSON Processing) base-server

provisioning the Jakarta JSON Processing API and
Implementation modules.

logging Support for the logging subsystem. base-server

mail Support for Jakarta Mail. base-server

naming

management Support for remote access to management interfaces elytron

secured using Elytron.

messaging-activemq Support for connections to a remote Jakarta Messaging resource-adapters

broker.

micrometer Support for Micrometer cdi

microprofile-config Support for MicroProfile Config. cdi

microprofile-fault- Support for MicroProfile Fault Tolerance. cdi

tolerance microprofile-config

microprofile-health Support for MicroProfile Health. management

microprofile-config

microprofile-jwt Support for MicroProfile JWT. ee-security

microprofile-config

microprofile-openapi Support for MicroProfile OpenAPI. jaxrs

microprofile-config

microprofile-platform Support for available MicroProfile platform microprofile-config

specifications. (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

https://docs.wildfly.org/31/Bootable_Guide.html 11/17
2024. 03. 10. 10:19 Bootable JAR Guide

microprofile-reactive- Support for MicroProfile Reactive Messaging cdi

messaging reactive-streams-operators

microprofile-reactive- Support for MicroProfile Reactive Messaging AMQP reactive-messaging

messaging-amqp connector

microprofile-reactive- Support for MicroProfile Reactive Messaging Kafka reactive-messaging

messaging-kafka connector

microprofile-reactive- Support for MicroProfile Reactive Streams Operators cdi

streams-operators

microprofile-lra- Support for MicroProfile LRA Coordinator cdi

coordinator jaxrs
transactions

microprofile-lra- Support for MicroProfile LRA Participant cdi

participant jaxrs

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 (WildFly Preview only unless the bean-validation
wildfly-mvc-krazo-feature-pack cdi
(https://github.com/wildfly-extras/mvc-krazo-feature- jaxrs-core
pack/blob/main/README.md) jsf (optional)
is used)

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 messaging-activemq

Artemis Jakarta Messaging broker.
Alternative: embedded-activemq

remoting Support for inbound and outbound JBoss Remoting elytron

connections, secured using Elytron. io

request-controller Support for request management base-server

https://docs.wildfly.org/31/Bootable_Guide.html 12/17
2024. 03. 10. 10:19 Bootable JAR Guide

resource-adapters Support for deployment of Jakarta Connectors resource transactions

adapters.

sar Support for SAR archives to deploy MBeans. base-server

jmx

security-manager Support for applying security manager permissions to base-server

applications.

servlet A servlet container. ee-integration

naming
undertow

transactions Support for transactions. ee

elytron

undertow Support for the Undertow HTTP server. Provides servlet base-server
support but does not provide typical EE integration like io
resource injection. Use web-server for a servlet
container with EE integration.

undertow-https Support for the Undertow HTTPS server secured using elytron
the applicationSSC SSLContext. undertow

undertow-load-balancer Support for Undertow configured as a load balancer. base-server

io

web-clustering Support for distributable web applications. Configures a transactions

non-local Infinispan-based container web cache for data web-server
session handling suitable to clustering environments.

web-console Support for loading the HAL web console from the management
/console context on the HTTP management interface.
Not required to use a HAL console obtained
independently and configured to connect to the server.

web-passivation Support for distributable web applications. Configures a transactions

local Infinispan-based container web cache for data web-server
session handling suitable to single node environments.

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

https://docs.wildfly.org/31/Bootable_Guide.html 13/17
2024. 03. 10. 10:19 Bootable JAR Guide

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.

https://docs.wildfly.org/31/Bootable_Guide.html 14/17
2024. 03. 10. 10:19 Bootable JAR Guide

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 bootable JAR (e.g.: server keystore).

Check this documentation (https://docs.wildfly.org/bootablejar) for more details on how to configure execution of CLI scripts
and to package extra content.

https://docs.wildfly.org/31/Bootable_Guide.html 15/17
2024. 03. 10. 10:19 Bootable JAR Guide

4. Packaging your application

Call ` mvn package ` to package both your application and the bootable JAR in the file <project build
directory>/<project final name>-bootable.jar

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

Check this documentation (https://docs.wildfly.org/bootablejar) for more details on the development mode.

https://docs.wildfly.org/31/Bootable_Guide.html 16/17
2024. 03. 10. 10:19 Bootable JAR Guide

5. Running your application

Call java -jar <path to bootable JAR> <arguments>

In additon, you can use the wildfly-jar:run and wildfly-jar:start plugin goals to launch the bootable JAR.

5.1. Bootable JAR arguments

The following arguments can be used when starting the bootable JAR:

Option Description

-b[interface]=<value> Set system property jboss.bind.address.<interface> to

the given value

-b=<value> Set system property jboss.bind.address to the given

value

-D<name>[=<value>] Set a system property. The system properties are set by

the server. They are not set by the bootable JAR JVM.

--help Display help then exit

--cli-script=<path to CLI script file> Path to a CLI script to execute when starting the
Bootable JAR

--deployment=<path to WAR/JAR/EAR file or exploded Application to install in the hollow JAR. Adding a
deployment directory> deployment to an bootable JAR already containing a
deployment is invalid.

--display-galleon-config Display the content of the Galleon configuration used to

build this bootable JAR.

--install-dir=<path to directory to install server in> By default a new TEMP directory is created. TEMP
directory location is controlled by the Java VM (call to
Files.createTempDirectory ).

--properties=<url> Load system properties from the given url

-S<name>[=value] Set a security property

-secmgr Activate and install the WildFlySecurityManager.

-u=<value> Set system property jboss.default.multicast.address to

the given value.

--version Print version and exit.

Version 31.0.0.Final
Last updated 2023-07-25 20:50:17 -0500

https://docs.wildfly.org/31/Bootable_Guide.html 17/17