© The WildFly Authors.

1. Provisioning WildFly with Galleon

As opposed to a using traditional WildFly zip installation that installs it all (all default server configurations and all JBoss modules), using Galleon tooling you can choose to install a complete or customized WildFly server.

More information on Galleon features and tooling can be found in the Galleon docs.

1.1. Download and Installation of the Galleon Command Line Tool

Releases of the Galleon command line tool are available on the Galleon releases page.

Download and unzip the release zip and add the bin dir to your system path. Use galleon.sh or galleon.bat to launch the tool.

1.2. WildFly Galleon feature-packs

The WildFly project provides a number of Galleon feature-pack maven artifacts. A feature-pack is a zipped file that contains everything needed to dynamically provision a server. These feature-packs are deployed in public maven repositories.

When Galleon is used to install WildFly, the desired WildFly feature-packs are retrieved and their content is assembled to create an installation.

The main WildFly project provides the following feature-packs for use with standard WildFly:

Maven GroupId:ArifactId Short name Use

org.wildfly:wildfly-galleon-pack

wildfly

The feature-pack most WildFly users use. Provisions a standard WildFly installation. Internally depends on the wildfly-ee feature-pack, but also provides integration of technologies like MicroProfile, Micrometer and Open Telemetry that are evolving rapidly, possibly in incompatible ways.

org.wildfly:wildfly-ee-galleon-pack

wildfly-ee

Provisions the most long-term stable functionality of standard WildFly. Does not include MicroProfile or other rapidly evolving technologies that may frequently introduce incompatible changes.

org.wildfly.cloud:wildfly-cloud-galleon-pack

-

Provisions a set of additional features allowing you to better configure a standard WildFly server to work on the cloud. It brings to the server some configuration aspects that are generally expected in a cloud context. See the feature-pack documentation for more details.

org.wildfly:wildfly-datasources-galleon-pack

-

Easy integration of popular JDBC drivers and associated datasources into a standard WildFly installation. See the feature-pack project README for more details.

org.wildfly:wildfly-myfaces-feature-pack

-

Provides MyFaces 4.x support for standard WildFly. See the feature-pack project README for more details.

The main WildFly project also provides feature-packs for use with WildFly Preview:

Maven GroupId:ArifactId Short name Use

org.wildfly:wildfly-preview-feature-pack

wildfly-preview

Provides a technology preview of things that may be coming in standard WildFly. Likely to have significant incompatible changes with every release.

org.wildfly.cloud:wildfly-preview-cloud-galleon-pack

-

WildFly Preview analogue to wildfly-cloud-galleon-pack.

org.wildfly:wildfly-datasources-preview-galleon-pack

-

WildFly Preview analogue to wildfly-datasources-galleon-pack.

There are also a number of feature-packs of varying levels of stability available from the wildfly-extras GitHub organization.

In most cases, people working with WildFly are using the wildfly feature-pack, so that is the one used in most of the examples in this document.

1.3. Installing WildFly using Galleon

The Galleon maven plugin or Galleon CLI are used to install WildFly. The latest CLI and documentation can be downloaded from the Galleon releases page.

To install the latest final version of standard WildFly into the directory my-wildfly-server call:

galleon.sh install wildfly:current --dir=my-wildfly-server

Once installed, the directory my-wildfly-server contains all that is expected to run a complete WildFly server. By default, all standalone and domain configurations are installed.

Append the release version to install an identified release, for example:

galleon.sh install wildfly:current#21.0.0.Final --dir=my-wildfly-server

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

1.4. Selecting the configurations to install

Galleon allows you to specify only a subset of the default configurations to be installed.

To only install the standalone.xml configuration call:

galleon.sh install wildfly:current --dir=my-wildfly-server --default-configs=standalone/standalone.xml

To install multiple configurations, a comma separated list of default configurations can be provided, for example:

galleon.sh install wildfly:current --dir=my-wildfly-server --default-configs=standalone/standalone.xml,domain/domain.xml

A default configuration is identified by <configuration model>/<configuration name>. WildFly defines standalone and domain models. The configuration name is the XML configuration file name (e.g.: standalone.xml, domain.xml, standalone-ha.xml).

1.5. Stability levels at provisioning time

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 option applies to both the features present in the provisioned configuration and the provisioned packages (mainly JBoss Modules modules). You can specify a different stability level for each of them by using the config-stability-level and the package-stability-level options.

If no stability level is provided, the WildFly feature-pack default stability levels for both configurations (community) and packages (experimental) apply. When provisioning WildFly with no stability level set, the community and default features are provisioned, the preview and experimental features are ignored. The experimental, preview, community and default packages are provisioned.

Having JBoss Modules modules at a lower stability level present in the installation allows you to modify a provisioned server configuration to contain extensions and subsystems or finer grained configuration elements that are at a lower stability level than what was originally provisioned.

1.5.1. Galleon CLI examples

Installing a WildFly server that contains preview features and packages (any feature and package at a lower stability level are not provisioned):

galleon.sh install wildfly:current --dir=my-wildfly-server --stability-level=preview

Installing a WildFly server that contains preview features and packages at the WildFly feature-pack packages default stability level (experimental)

galleon.sh install wildfly:current --dir=my-wildfly-server --config-stability-level=preview

1.6. WildFly Galleon layers

WildFly Galleon feature-packs expose Galleon layers. A layer identifies one or more server capabilities that can be installed on its own or in combination with other layers. For example, if your application (e.g. a microservice) is only making use of Jakarta-RESTful-Web-Services, MicroProfile Config and CDI server capabilities, you can choose to only install the jaxrs, microprofile-config and cdi layers. The standalone.xml configuration would then only contain the required subsystems and their dependencies.

The benefit to installing WildFly using Galleon layers, in addition to configuration trim down, is that Galleon only installs the needed content (JBoss Modules modules, scripts, etc.)

To install a server only configured with the Jakarta-RESTful-Web-Services and CDI capabilities call:

galleon.sh install wildfly:current --dir=my-wildfly-server --layers=cdi,jaxrs

Once installed, the directory my-wildfly-server contains all that is expected to deploy an application that depends on Jakarta-RESTful-Web-Services and CDI.

Some layers optionally depend on other layers; i.e. the features provided by layer can and by default do make use of those from another layer, but if those are not present things will still work fine. In such a case if you do not want the optional capabilities you can exclude the optional layer by prefixing its name with a '-'. For example to exclude the optional CDI dependency on Jakarta Bean Validation:

galleon.sh install wildfly:current --dir=my-wildfly-server --layers=cdi,jaxrs,-bean-validation

Tools (jboss-cli, add-user, …​) are not always installed when installing WildFly using layers. In some cases, depending on what layers you use, only server launcher scripts are installed into the bin directory. To include these tools include the core-tools layer.

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

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

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.

1.6.2. Galleon CLI recipes

Using the Galleon CLI tool, you can provision WildFly installations based on a set of layers.

In order to exclude an optional layer prefix its name with '-', for example: '-jpa' to exclude the jpa layer.

Installation of a cloud-server
galleon.sh install wildfly:current --dir=my-wildfly-server --layers=cloud-server
Installation of a cloud-server with support for https
galleon.sh install wildfly:current --dir=my-wildfly-server --layers=cloud-server,undertow-https
Installation of a cloud-server and Jakarta Enterprise Beans with ejb-dist-cache as an alternative to ejb-local-cache

This is done by excluding the ejb layer’s optional ejb-local-cache dependency and specifying its ejb-dist-cache alternative:

galleon.sh install wildfly:current --dir=my-wildfly-server --layers=cloud-server,ejb,-ejb-local-cache,ejb-dist-cache
Installation of a jaxrs-server with jpa-distributed as an alternative to jpa
galleon.sh install wildfly:current --dir=my-wildfly-server --layers=jaxrs-server,-jpa,jpa-distributed
Installation of jaxrs, cdi, elytron and logging
galleon.sh install wildfly:current --dir=my-wildfly-server --layers=jaxrs,cdi,elytron,logging
Installation of a servlet container with main core functionalities
galleon.sh install wildfly:current --dir=my-wildfly-server --layers=web-server,core-server
Installation of a servlet container with support for https
galleon.sh install wildfly:current --dir=my-wildfly-server --layers=web-server,undertow-https
Installation of a core server
galleon.sh install wildfly:current --dir=my-wildfly-server --layers=core-server
References in this document to Java Persistence API (JPA) refer to the Jakarta Persistence unless otherwise noted.