[#configuring-a-wildfly-swarm-application]
= Configuring a WildFly Swarm application

You can configure numerous options with applications built with WildFly Swarm.
For all options, reasonable defaults are already applied, so you do not have to change any options unless you explicitly want to.

This reference is a complete list of all configurable items, grouped by the fraction that introduces them.
Only the items related to the fractions that your application uses are relevant to you.

[#configuring-an-application-using-properties]
== Configuring an application using properties

Here, configuration items are presented using dotted notation, and are suitable for use as Java property names, which your application consumes through explicit setting in the Maven plugin configuration, or through the command line when your application is being executed.

Any property that has the _KEY_ parameter in its name indicates that you must supply a key or identifier in that segment of the name.

.Using configuration items with the KEY parameter
====
The configuration item documented as `swarm.undertow.servers.KEY.default-host` indicates that the configuration applies to a particular named server.

In practical usage, the property would be, for example, `swarm.undertow.servers.default.default-host` for a server known as `default`.
====

[discrete]
=== Maven plugin properties

If you want to set explicit configuration values as defaults through the Maven plugin, add a `<properties>` section to the `<configuration>` block of the plugin in the `pom.xml` file in your application.

.Setting a configuration item through the Maven Plugin
====

An example Maven plugin configuration for the `swarm.bind.address` item:

[source,xml,subs=+attributes]
----
<build>
  <plugins>
    <plugin>
      <groupId>org.wildfly.swarm</groupId>
      <artifactId>wildfly-swarm-plugin</artifactId>
      <version>{version}</version>
      <configuration>
        <properties>
          <swarm.bind.address>127.0.0.1</swarm.bind.address>
          <java.net.preferIPv4Stack>true</java.net.preferIPv4Stack>
        </properties>
      </configuration>
    </plugin>
  </plugins>
</build>
----
====

NOTE: It is not recommended to set properties using the Maven plugin to control the configuration in the long term.
Instead, use the xref:configuring-an-application-using-yaml[YAML method].

[discrete]
=== Setting properties using the Command Line

Setting properties using the Maven plugin is useful for temporarily changing a configuration item for a single execution of your application.
You can customize an environment-specific setting or experiment with configuration items before setting them in a YAML configuration file.

To use a property on the command line, pass it as a command-line parameter to the Java binary:

[source,shell]
----
$ java -Dswarm.bind.address=127.0.0.1 -jar myapp-swarm.jar
----

[#configuring-an-application-using-yaml]
== Configuring an application using YAML

YAML is the preferred method for long-term configuration of your application.
In addition to that, the YAML strategy provides grouping of environment-specific configurations, which you can selectively enable when executing the application.

[discrete]
=== The General YAML format

The configuration names correspond to the YAML configuration structure.

.YAML configuration
====
For example, the item documented as `swarm.undertow.servers.KEY.default-host` translates to the following YAML structure, substituting the `KEY` segment with the `default` identifier:

[source,yaml]
----
swarm:
  undertow:
    servers:
      default:
        default-host: <myhost>
----
====

[discrete]
=== Default YAML Files

If the original `.war` file with your application contains a file named `project-defaults.yml`, that file represents the defaults applied over the absolute defaults that WildFly Swarm provides.

In addition to the `project-defaults.yml` file, you can provide specific configuration files using the `-S <name>` command-line option.
The specified files are loaded, in the order you provided them, before `project-defaults.yml`.
A name provided in the `-S <name>` argument specifies the `project-<name>.yml` file on your classpath.

.Specifying configuration files on the command line
====

Consider the following application execution:

[source,bash]
----
$ java -jar myapp-swarm.jar -Stesting -Scloud
----

The following YAML files are loaded, in this order. The first file containing a given configuration item takes precedence over others:

. `project-testing.yml`
. `project-cloud.yml`
. `project-defaults.yml`
====

[discrete]
=== Non-default YAML Files

If you want to reference a YAML file that exists outside of your application, use the `-s <path>` command-line option.

Both the `-s <path>` and `-S <name>` command-line options can be used at the same time, but files specified using the `-s <path>` option take precedence over YAML files contained in your application.

.Specifying configuration files inside and outside of the application
====

Consider the following application execution:

[source,bash]
----
$ java -jar myapp-swarm.jar -s/home/app/openshift.yml -Scloud -Stesting
----

The following YAML files are loaded, in this order:

. `/home/app/openshift.yml`
. `project-cloud.yml`
. `project-testing.yml`
. `project-defaults.yml`

The same order of preference is applied even if you invoke the application as follows:

[source,bash]
----
$ java -jar myapp-swarm.jar -Scloud -Stesting -s/home/app/openshift.yml
----
====

