© 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
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 |
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-serverOnce 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: |
|
If your project is using WildFly Preview, the |
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.xmlTo 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=previewInstalling 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=preview1.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,jaxrsOnce 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, 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 |
|---|---|---|
A servlet container with support for datasources. |
core-server |
|
An extension of datasources-web-server with support for Jakarta RESTful Web Services, CDI and JPA. |
bean-validation (optional) |
|
An extension of jaxrs-server to address common cloud requirements. |
ee-security (optional) |
|
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) |
|
A Jakarta EE Core Profile server. |
core-server |
Basic Galleon Layers
Name |
Description |
Dependencies |
Empty runnable server. |
git-history (optional) |
|
Support for Jakarta Batch. |
||
Support for Jakarta Bean Validation. |
base-server |
|
Support for Jakarta Contexts and Dependency Injection. |
base-server |
|
An aggregation of some basic layers to address cloud use cases. |
bean-validation (optional) |
|
Support for server management services. |
||
Support for jboss-cli, add-user and elytron-tool launch scripts and configuration files. |
management (optional) |
|
Support for datasources. |
||
Support for deployment directory scanning. |
||
Support for discovery. |
||
Support for common functionality in the Jakarta EE platform and for Jakarta Concurrency. |
ee-concurrency (optional) |
|
Support for Jakarta Concurrency. |
||
Support for common functionality in the Jakarta EE platform. |
||
Support for EE Security. |
||
Support for invoking Jakarta Enterprise Beans over HTTP. |
||
Support for Jakarta Enterprise Beans, excluding the IIOP protocol. |
ejb-lite |
|
Infinispan-based distributed cache for stateful session beans. |
||
Support for Jakarta Enterprise Beans Lite. |
ejb-local-cache (optional) |
|
Infinispan-based local cache for stateful session beans. |
||
Support for Elytron security. |
||
Support for an embedded Apache Activemq Artemis Jakarta Messaging broker. |
||
Support for using git for configuration management. |
||
Support for liveness and readiness checks for the server runtime. |
||
Support for Hibernate Search. The jpa dependency can be excluded and jpa-distributed used instead. |
jpa (optional) |
|
Support for an H2 datasource |
||
Support for an H2 datasource set as the ee subsystem default datasource. |
||
Support for the H2 JDBC driver. |
||
Support for IIOP |
||
Support for XNIO workers and buffer pools. |
||
Support for Jakarta RESTful Web Services. |
||
Support for Jakarta RESTful Web Services with optional ee-concurrency and deployment scanner layers. |
deployment-scanner (optional) |
|
Support for the JBoss Diagnostic Reporting (JDR) subsystem. |
base-server |
|
Deprecated - use messaging-activemq. |
||
Support for registration of Management Model MBeans. |
||
Support for a JMX remoting connector. |
||
Support for JPA (using the latest WildFly supported Hibernate release). |
bean-validation (optional) |
|
Support for JPA with a distributed second level cache. |
bean-validation (optional) |
|
Support for Jakarta Faces. |
bean-validation (optional) |
|
Support for JSON Binding (Jakarta JSON Binding) provisioning the Jakarta JSON Binding API and Implementation modules. |
||
Support for JSON Processing (Jakarta JSON Processing) provisioning the Jakarta JSON Processing API and Implementation modules. |
||
Support for the logging subsystem. |
||
Support for Jakarta Mail. |
||
Support for remote access to management interfaces secured using Elytron. |
||
Support for connections to a remote Jakarta Messaging broker. |
||
Support for base server metrics in Prometheus format. |
||
Support for Micrometer |
||
Support for MicroProfile Config. |
||
Support for MicroProfile Fault Tolerance. |
||
Support for MicroProfile Health. |
||
Support for MicroProfile JWT. |
||
Support for acting as coordinator of MicroProfile LRA long-running actions. |
cdi |
|
Support for acting as a participant in MicroProfile LRA long-running actions. |
cdi |
|
Support for MicroProfile OpenAPI. |
||
Support for available MicroProfile platform specifications. |
microprofile-config (optional) |
|
Support for MicroProfile REST client. |
||
Support for MicroProfile Reactive Messaging |
||
Support for MicroProfile Reactive Messaging AMQP connector |
||
Support for MicroProfile Reactive Messaging Kafka connector |
||
Support for MicroProfile Reactive Streams Operators |
||
Support for MicroProfile Telemetry |
||
Support for mod_cluster subsystem. |
||
Support for Jakarta MVC ( |
bean-validation |
|
Support for JNDI. |
||
Support for MicroProfile monitoring features. |
microprofile-config (optional) |
|
Support for OpenTelemetry |
||
Support for legacy JBoss Microcontainer applications. |
||
Support for connections to a remote Apache Activemq Artemis Jakarta Messaging broker. |
||
Support for inbound and outbound JBoss Remoting connections, secured using Elytron. |
||
Support for request management |
||
Support for deployment of Jakarta Connectors resource adapters. |
||
Support for SAR archives to deploy MBeans. |
||
Support for applying security manager permissions to applications. |
||
A servlet container. |
||
Support for transactions. |
||
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. |
||
Support for the Undertow HTTPS server secured using the applicationSSC SSLContext. |
||
Support for Undertow configured as a load balancer. |
||
Support for distributable web applications. Configures a non-local Infinispan-based container web cache for data session handling suitable to clustering environments. |
||
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. |
||
Support for distributable web applications. Configures a local Infinispan-based container web cache for data session handling suitable to single node environments. |
||
A servlet container. |
deployment-scanner (optional) |
|
Support for Jakarta XML Web Services |
ejb-lite (optional) |
| 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-serverInstallation of a cloud-server with support for https
galleon.sh install wildfly:current --dir=my-wildfly-server --layers=cloud-server,undertow-httpsInstallation 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-cacheInstallation 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-distributedInstallation of jaxrs, cdi, elytron and logging
galleon.sh install wildfly:current --dir=my-wildfly-server --layers=jaxrs,cdi,elytron,loggingInstallation of a servlet container with main core functionalities
galleon.sh install wildfly:current --dir=my-wildfly-server --layers=web-server,core-serverInstallation of a servlet container with support for https
galleon.sh install wildfly:current --dir=my-wildfly-server --layers=web-server,undertow-httpsInstallation 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. |