[[Galleon_Provisioning]]
= Provisioning WildFly with Galleon

ifdef::env-github[]
:tip-caption: :bulb:
:note-caption: :information_source:
:important-caption: :heavy_exclamation_mark:
:caution-caption: :fire:
:warning-caption: :warning:
endif::[]

As opposed to a using traditional WildFly zip installation that installs it all (all default
server configurations and all JBoss modules), using https://github.com/wildfly/galleon[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 https://docs.wildfly.org/galleon/[docs].

== Download and Installation of the Galleon Command Line Tool

Releases of the Galleon command line tool are available on the Galleon link:https://github.com/wildfly/galleon/releases[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.

[[WildFly_Galleon_feature-packs]]
== WildFly Galleon feature-packs

The WildFly project provides a number of Galleon https://docs.wildfly.org/galleon/#_feature_packs[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 xref:WildFly_and_WildFly_Preview.adoc[standard WildFly]:

[cols="~,~,~",options="header"]
|=======================================================================
|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 https://github.com/wildfly-extras/wildfly-cloud-galleon-pack/blob/main/doc/index.md[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 https://github.com/wildfly-extras/wildfly-datasources-galleon-pack/blob/main/README.md[README] for more details.
|*org.wildfly:wildfly-myfaces-feature-pack*|-|Provides MyFaces 4.x support for standard WildFly. See the feature-pack project https://github.com/wildfly-extras/wildfly-myfaces-feature-pack/blob/master/README.md[README] for more details.
|=======================================================================

The main WildFly project also provides feature-packs for use with xref:WildFly_and_WildFly_Preview.adoc[WildFly Preview]:

[cols="~,~,~",options="header"]
|=======================================================================
|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 https://github.com/orgs/wildfly-extras/repositories[*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.

== 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 https://github.com/wildfly/galleon/releases[page].

To install the latest final version of standard WildFly into the directory _my-wildfly-server_ call:

[source,options="nowrap"]
----
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.

[NOTE]
====

Append the release version to install an identified release, for example:
[source,options="nowrap"]
----
galleon.sh install wildfly:current#21.0.0.Final --dir=my-wildfly-server
----
====

[NOTE]
====

If your project is using link:WildFly_and_WildFly_Preview{outfilesuffix}[WildFly Preview], the ``feature-pack-location`` to use
is ``wildfly-preview@maven(org.jboss.universe:community-universe)``.
====
== 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:

[source,options="nowrap"]
----
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:
[source,options="nowrap"]
----
galleon.sh install wildfly:current --dir=my-wildfly-server --default-configs=standalone/standalone.xml,domain/domain.xml
----

[NOTE]
====

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_).
====

[[WildFly_Galleon_stability]]
== Stability levels at provisioning time

In order to support xref:Admin_Guide.adoc#Feature_stability_levels[WildFly feature stability levels], Galleon defines 
some http://docs.wildfly.org/galleon/#_built_in_and_product_specific_options[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.

[NOTE]
====
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.
====

=== 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):

[source,options="nowrap"]
----
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`)

[source,options="nowrap"]
----
galleon.sh install wildfly:current --dir=my-wildfly-server --config-stability-level=preview 
----

[[wildfly_galleon_layers]]
== WildFly Galleon layers

WildFly Galleon feature-packs expose link:++https://docs.wildfly.org/galleon/#_layers++[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:

[source,options="nowrap"]
----
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_:

[source,options="nowrap"]
----
galleon.sh install wildfly:current --dir=my-wildfly-server --layers=cdi,jaxrs,-bean-validation
----

[NOTE]
====

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

include::Galleon_layers.adoc[]

[[galleon-cli-recipes]]
=== Galleon CLI recipes

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

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

==== Installation of a cloud-server

[source,options="nowrap"]
----
galleon.sh install wildfly:current --dir=my-wildfly-server --layers=cloud-server
----

==== Installation of a cloud-server with support for https 

[source,options="nowrap"]
----
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:

[source,options="nowrap"]
----
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

[source,options="nowrap"]
----
galleon.sh install wildfly:current --dir=my-wildfly-server --layers=jaxrs-server,-jpa,jpa-distributed
----

==== Installation of jaxrs, cdi, elytron and logging

[source,options="nowrap"]
----
galleon.sh install wildfly:current --dir=my-wildfly-server --layers=jaxrs,cdi,elytron,logging
----

==== Installation of a servlet container with main core functionalities

[source,options="nowrap"]
----
galleon.sh install wildfly:current --dir=my-wildfly-server --layers=web-server,core-server
----

==== Installation of a servlet container with support for https

[source,options="nowrap"]
----
galleon.sh install wildfly:current --dir=my-wildfly-server --layers=web-server,undertow-https
----

==== Installation of a core server

[source,options="nowrap"]
----
galleon.sh install wildfly:current --dir=my-wildfly-server --layers=core-server
----

NOTE: References in this document to Java Persistence API (JPA) refer to the Jakarta Persistence unless otherwise noted.
