© 2020 The original 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

WildFly provides a Galleon feature-pack maven artifact (a zipped file 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 Galleon is used to install WildFly, WildFly feature-packs are retrieved and their content is assembled to create an installation.

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 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. WildFly Galleon layers

WildFly Galleon feature-packs expose some 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.5.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.

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)
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)
core-security-realms (optional)
jmx-remoting (optional)
logging (optional)
management (optional)
request-controller (optional)
security-manager (optional)

Basic Galleon Layers

Name

Description

Dependencies

application-security-realm

Security realm meant for securing applications.

base-server

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-security-realms

Support for core Application and Management security realms.

application-security-realm (optional)
base-server
management-security-realm (optional)

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.

jsonb (optional)
naming

ee-security

Support for EE Security.

cdi

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

git-history

Support for using git for configuration management.

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

io

Support for XNIO workers and buffer pools.

base-server

jaxrs

Support for JAXRS.

web-server
microprofile-rest-client (optional)

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

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 Server Faces.

bean-validation (optional)
cdi (optional)
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

legacy-management

Support for remote access to management interfaces secured with the core ManagementRealm.

management-security-realm

legacy-remoting

Support for inbound and outbound JBoss Remoting connections, secured using legacy security realms.

application-security-realm
io

legacy-security

Support for legacy Picketbox-based web security.

naming
vault

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

management-security-realm

Security realm meant for securing server management interfaces.

base-server

messaging-activemq

Support for connections to a remote Jakarta Messaging broker.

resource-adapters

microprofile-config

Support for MicroProfile Config.

cdi

microprofile-fault-tolerance

Support for MicroProfile Fault Tolerance.

cdi
microprofile-config
microprofile-metrics

microprofile-health

Support for MicroProfile Health.

management
microprofile-config

microprofile-jwt

Support for MicroProfile JWT.

ee-security
elytron
microprofile-config

microprofile-metrics

Support for MicroProfile Metrics.

management
microprofile-config

microprofile-openapi

Support for MicroProfile OpenAPI.

jaxrs
microprofile-config

microprofile-opentracing

Support for MicroProfile OpenTracing.

cdi
microprofile-config

microprofile-platform

Support for available MicroProfile platform specifications.

microprofile-config (optional)
microprofile-fault-tolerance (optional)
microprofile-health (optional)
microprofile-jwt (optional)
microprofile-metrics (optional)
microprofile-openapi (optional)
microprofile-opentracing (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-kafka

Support for MicroProfile Reactive Messaging Kafka connector

reactive-messaging

microprofile-reactive-streams-operators

Support for MicroProfile Reactive Streams Operators

cdi

naming

Support for JNDI.

base-server

observability

Support for MicroProfile monitoring features.

microprofile-config (optional)
microprofile-health (optional)
microprofile-metrics (optional)
open-tracing (optional)

open-tracing

Deprecated Use microprofile-opentracing

cdi
microprofile-config

pojo

Support for legacy JBoss Microcontainer applications.

base-server

remote-activemq

Support for connections to a remote Apache Activemq Artemis Jakarta Messaging broker.

resource-adapters

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

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
vault

undertow-legacy-https

Support for the Undertow HTTPS server secured using the legacy security ApplicationRealm.

core-security-realms
undertow

undertow-load-balancer

Support for Undertow configured as a load balancer.

base-server
io
vault

vault

Support for Picketbox security vaults.

base-server

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
naming
undertow

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.5.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 (using legacy core ApplicationRealm)
galleon.sh install wildfly:current --dir=my-wildfly-server --layers=cloud-server,undertow-legacy-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 (using legacy core ApplicationRealm)
galleon.sh install wildfly:current --dir=my-wildfly-server --layers=web-server,undertow-legacy-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.