How to use environment variables in WildFly configuration

One of the key features of WildFly is its support for environment variables, which allow you to dynamically configure your application server based on the environment in which it is running. In this tutorial, we will go through the steps required to use environment variables in WildFly configuration files like standalone.xml or host.xml.

Support for expressions in configuration

Firstly, before we show how to pass environment variables to your configuration, you need to be aware that not all configuration elements support expressions.

For example, if you check WildFly Model for the File in the logger subsystems, you will see that it contains in the Attribute “Expressions Allowed” the value “false”

jboss environment variables

Therefore, if you try setting an expression in it, you will see the unpleasant error message:

18:13:40,401 ERROR [org.jboss.as.controller] (Controller Boot Thread) WFLYCTL0362: Capabilities required by resource '/subsystem=logging/periodic-rotating-file-handler=FILE' are not available:
    org.wildfly.management.path.${env.logdir:/var/log}; This unresolvable capability likely is due to the use of an expression string in a configuration attribute that does not support expressions.

Hint: you can check if a resource support expressions by querying the resource description. For example, for the file handler:

/subsystem=logging/periodic-rotating-file-handler=FILE:read-resource-description()

How to use expressions in the configuration

After the initial premise, let’s see how to use expressions in configuration elements that support expressions. To use environment variables in the XML configuration you need to apply the ${env. } prefix to the variable:

${env.var}"/>

For example, we will inject the environment variable “jbossport” in the Socket Binding expression of WildFly:

<socket-binding name="http" port="${env.jbossport:8080}"/>

Then, let’s set the variable from the shell:

$ export jbossport=8081

Finally, start WildFly and verify that it now binds the http socket to port 8081:

18:39:10,959 INFO  [org.wildfly.extension.undertow] (MSC service thread 1-3) WFLYUT0006: Undertow HTTP listener default listening on 127.0.0.1:8081

As we are using 8080 as fallback value, if you don’t set the environment variable “jbossport” the application server will boot with the default port 8080:

18:39:53,792 INFO  [org.wildfly.extension.undertow] (MSC service thread 1-1) WFLYUT0006: Undertow HTTP listener default listening on 127.0.0.1:8080

Check Env variables when resolving System Properties

Besides the env pattern it is also possible to allow the resolution of System Properties through environment variables. This is possible since WildFly 17 and in JBoss EAP 8.

For example:

<socket-binding name="http" port="${jbossport:8080}"/>

As you can see, we are using the expression “jbossport” without the env prefix. That means, a System Property will be used as first option. Next, set the environment variable and start WildFly:

export jbossport=9080
./standalone.sh 

Then, check that the application server starts on port 9090:

18:45:33,746 INFO  [org.wildfly.extension.undertow] (MSC service thread 1-7) WFLYUT0006: Undertow HTTP listener default listening on 127.0.0.1:9080

On the other hand, if WildFly is able to resolve the expression both a system property and an environment variable, the system property takes precedence, as per the Default ConfigSources section of the MicroProfile Config specification.

Conclusion

In conclusion, using environment variables in WildFly configuration files can help simplify your configuration management and allow for more flexibility in your application deployment. By following the steps outlined in this tutorial, you can easily incorporate environment variables into your WildFly deployment.