Chapter 3. Environment variables and model expression resolution

3.1. Prerequisites

You have some basic knowledge of how to configure environment variables on an operating system.
For configuring environment variables on the OpenShift Container Platform, you must meet the following prerequisites:
- You have already installed OpenShift and set up the OpenShift CLI ("oc"). For more information about the oc, see Getting Started with the OpenShift CLI.
- You have deployed your application to OpenShift using a Helm chart. For more information about Helm charts, see Helm Charts for JBoss EAP.

3.2. Environment variables for resolving management model expressions

To resolve management model expressions and to start your JBoss EAP 8.0 Beta server on the OpenShift Container Platform, you can either add environment variables or set Java system properties in the management command-line interface (CLI). If you use both, JBoss EAP observes and uses the Java system property rather than the environment variable to resolve the management model expression.

System property to environment variable mapping

Imagine that you have this management expression: ${my.example-expr}. When your JBoss EAP server tries to resolve it, it checks for a system property named my.example-expr.

If your server finds this property, it uses its value to resolve the expression.
If it doesn’t find this property, your server continues searching.

Next, assuming that your server does not find system property my.example-expr, it automatically changes my.example-expr to all uppercase letters and replaces all characters that aren’t alphanumeric with underscores (_): MY_EXAMPLE_EXPR. JBoss EAP then checks for an environment variable with that name.

If your server finds this variable, it uses its value to resolve the expression.
If it doesn’t find this variable, your server continues searching.

Tip

If your original expression starts with the prefix env., JBoss EAP resolves the environment variable by removing the prefix, then looking for only the environment variable name. For example, for the expression env.example, JBoss EAP looks for an example environment variable.

If none of these checks finds a property or variable to resolve your original expression, JBoss EAP looks for whether the expression has a default value. If it does, that default value resolves the expression. If not, then JBoss EAP can’t resolve the expression.

Example with two servers

Suppose that, on one server, JBoss EAP defines this management resource: <socket-binding-group name="standard-sockets" default-interface="public" port-offset="${jboss.socket.binding.port-offset:0}">. To run a second server with a different port offset, instead of editing the configuration file, do one of the following:

Set the jboss.socket.binding.port-offset Java system property to resolve the value on the second server: ./standalone.sh -Djboss.socket.binding.port-offset=100.
Set the JBOSS_SOCKET_BINDING_PORT_OFFSET environment variable to resolve the value on the second server: JBOSS_SOCKET_BINDING_PORT_OFFSET=100 ./standalone.sh.

3.3. Configuring environment variables on the OpenShift Container Platform

With JBoss EAP 8.0 Beta, you can configure environment variables to resolve management model expressions. You can also use environment variables to adapt the configuration of the JBoss EAP server you’re running on OpenShift.

Set environment variables and options on a resource that uses a pod template:

$ oc set env <object-selection> KEY_1=VAL_1 ... KEY_N=VAL_N [<set-env-options>] [<common-options>]

Option	Description
`-e, --env=<KEY>=<VAL>`	Set given key-value pairs of environment variables.
`--overwrite`	Confirm update of existing environment variables.

Note

Kubernetes workload resources that use pod templates include the following:

Deployment
ReplicaSet
StatefulSet
DaemonSet
Job
CronJob

After you configure your environment variables, the JBoss EAP management console should display them in the details for their related pods.

Additional resources

3.4. Overriding management attributes with environment variables

You know that you can use a Java system property or an environment variable to resolve a management attribute that’s defined with an expression, but you can also modify other attributes, even if they don’t use expressions.

To more easily adapt your JBoss EAP server configuration to your server environment, you can use an environment variable to override the value of any management attribute, without ever having to edit your configuration file. This feature, which is available starting with the JBoss EAP version 8.0, is useful for the following reasons:

JBoss EAP provides expressions for only its most common management attributes. Now, you can change the value of an attribute that has no defined expression.
Some management attributes connect your JBoss EAP server with other services, such as a database, whose values you can’t know in advance, or whose values you can’t store in a configuration; for example, in database credentials. By using environment variables, you can defer the configuration of such attributes while your JBoss EAP server is running.

Important

This feature is enabled by default, starting with JBoss EAP version 8.0 OpenShift runtime image. To enable it on other platforms, you must set the WILDFLY_OVERRIDING_ENV_VARS environment variable to any value; for example, export WILDFLY_OVERRIDING_ENV_VARS=1.

Note

You can’t override management attributes whose type is LIST, OBJECT, or PROPERTY.

Prerequisites

You must have defined a management attribute that you now want to override.

Procedure

To override a management attribute with an environment variable, complete the following steps:

Identify the path of the resource and attribute you want to change. For example, set the value of the proxy-address-forwarding attribute to true for the resource /subsystem=undertow/server=default-server/http-listener=default.
Create the name of the environment variable to override this attribute by mapping the resource address and the management attribute, as follows:
1. Remove the first slash (/) from the resource address: /subsystem=undertow/server=default-server/http-listener=default becomes subsystem=undertow/server=default-server/http-listener=default.
2. Append two underscores (__) and the name of the attribute; for example: subsystem=undertow/server=default-server/http-listener=default__proxy-address-forwarding.
3. Replace all non-alphanumeric characters with an underscore (_), and put the entire line of code in all capital letters: SUBSYSTEM_UNDERTOW_SERVER_DEFAULT_SERVER_HTTP_LISTENER_DEFAULT__PROXY_ADDRESS_FORWARDING.
Set the environment value: SUBSYSTEM_UNDERTOW_SERVER_DEFAULT_SERVER_HTTP_LISTENER_DEFAULT__PROXY_ADDRESS_FORWARDING=true.

Note

These values are examples that you must replace with your actual configuration values.

3.5. Provisioning a JBoss EAP server using the Maven plug-in

Using JBoss EAP Maven plug-in, you can configure a server according to your requirements by including only those Galleon layers that provide the capabilities that you need, in your server.

3.5.1. JBoss EAP Maven plug-in

The JBoss EAP Maven plug-in uses Galleon trimming capability to reduce the size and memory footprint of the server. The JBoss EAP Maven plug-in supports the execution of JBoss EAP CLI script files to customize your server configuration. A CLI script includes a list of CLI commands for configuring the server.

You can retrieve the latest Maven plug-in version from the Maven repository, which is available at Index of /ga/org/jboss/eap/plugins/eap-maven-plugin. In a Maven project, the pom.xml file contains the configuration of the JBoss EAP Maven plug-in.

The JBoss EAP Maven plug-in provisions the server and deploys the packaged application, such as WAR, to the provisioned server during the Maven execution. The provisioned server on which your application is deployed is located in target/server directory. The JBoss EAP Maven plug-in also provides the following functionality:

Note

The server in target/server is not supported and is available only for debugging or development purposes.

Uses the org.jboss.eap:wildfly-ee-galleon-pack and org.jboss.eap.cloud:eap-cloud-galleon-pack Galleon feature-pack and some of its layers for customizing the server configuration file.
Applies CLI script commands to the server.
Supports the addition of extra files into the server installation, such as a keystore file.

3.5.2. Creating a Jakarta EE 10 application with the Maven

Create an application that prints “Hello World!” when you access it.

Prerequisites

You have installed JDK 11 or JDK 17.
You have installed the Maven 3.6 or later version. For more information, see Downloading Apache Maven.

Procedure

Set up the Maven project.

$ mvn archetype:generate \
-DgroupId=GROUP_ID \
-DartifactId=ARTIFACT_ID \
-DarchetypeGroupId=org.apache.maven.archetypes \
-DarchetypeArtifactId=maven-archetype-webapp \
-DinteractiveMode=false

Where GROUP_ID is the groupId of your project and ARTIFACT_ID is the artifactId of your project.

To configure the Maven to automatically manage versions for the Jakarta EE artifacts in the jboss-eap-ee BOM, add the BOM to the <dependencyManagement> section of the project pom.xml file. For example:

<dependencyManagement>
  <dependencies>
    <dependency>
        <groupId>org.jboss.bom</groupId>
        <artifactId>jboss-eap-ee</artifactId>
        <version>8.0.0.Beta</version>
        <type>pom</type>
        <scope>import</scope>
    </dependency>
  </dependencies>
</dependencyManagement>

Add the servlet API artifact, which is managed by the BOM, to the <dependencies> section of the project pom.xml file, as shown in the following example:
```
<dependency>
    <groupId>jakarta.servlet</groupId>
    <artifactId>jakarta.servlet-api</artifactId>
</dependency>
```

Create a Java file TestServlet.java with the following content and save the file in the APPLICATION_ROOT/src/main/java/com/example/simple/ directory.

package com.example.simple;
import jakarta.servlet.annotation.WebServlet;
import jakarta.servlet.http.HttpServlet;
import jakarta.servlet.http.HttpServletRequest;
import jakarta.servlet.http.HttpServletResponse;
import java.io.IOException;
import java.io.PrintWriter;
@WebServlet(urlPatterns = "/hello")
public class TestServlet extends HttpServlet {
    @Override
    protected void doGet(HttpServletRequest req, HttpServletResponse resp) throws IOException {
        PrintWriter writer = resp.getWriter();
        writer.println("Hello World!");
        writer.close();
    }
}

You can now deploy this application on JBoss EAP or update this application to package it with and deploy it on a custom provisioned JBoss EAP server using the Maven plug-in.

3.5.3. Using the Maven plug-in to provision a JBoss EAP server

Update the pom.xml of an application to package it with and deploy on a custom provisioned JBoss EAP server using the Maven plug-in. You can then deploy the application running on the custom-provisioned JBoss EAP server on OpenShift.

Prerequisites

Ensure that the JBoss EAP Maven plug-in and the JBoss EAP Maven artifact are accessible from either your local or remote Maven repositories.
You have installed JDK 11 or JDK 17.
You have installed Maven. For more information, see Downloading Apache Maven.
Note
If you are using JDK 17 and Maven 3.8.5 or previous Maven version, use the latest Maven WAR plugin.
You have created a Maven project for Jakarta EE 10 application. For more information, see Creating a Jakarta EE 10 application with the Maven.

Procedure

Configure Maven to retrieve the JBoss EAP BOM and JBoss EAP Maven plug-in from a remote repository by adding the following content to the pom.xml file:

<repositories>
    <repository>
        <id>jboss</id>
        <url>https://maven.repository.redhat.com/earlyaccess/all/</url>
        <snapshots>
            <enabled>false</enabled>
        </snapshots>
    </repository>
</repositories>
<pluginRepositories>
    <pluginRepository>
        <id>jboss</id>
        <url>https://maven.repository.redhat.com/earlyaccess/all/</url>
        <snapshots>
            <enabled>false</enabled>
        </snapshots>
    </pluginRepository>
</pluginRepositories>

Add the following content to the <build> element of the pom.xml file. You must specify the latest version of the JBoss EAP Maven plug-in. For example:

<plugins>
    <plugin>
        <groupId>org.jboss.eap.plugins</groupId>
        <artifactId>eap-maven-plugin</artifactId>
        <version>1.0.0.Beta-redhat-00001</version>
        <configuration>
            <channels>
             	<channel>
                    <groupId>org.jboss.eap.channels</groupid> 1
                    <artifactId>eap-8.0-beta</artifactId>
                </channel>
            </channels>
            <feature-packs>
                <feature-pack>
                    <location>org.jboss.eap:wildfly-ee-galleon-pack</location> 2
                </feature-pack>
                <feature-pack>
                    <location>org.jboss.eap.cloud:eap-cloud-galleon-pack</location> 3
                </feature-pack>
            </feature-packs>
            <layers>
                <layer>cloud-server</layer> 4
            </layers>
            <runtime-name>ROOT.war</runtime-name> 5
        </configuration>
        <executions>
            <execution>
                <goals>
                    <goal>package</goal> 6
                </goals>
            </execution>
        </executions>
    </plugin>
</plugins>

1: This specifies the JBoss EAP 8.0 Beta channel in which the JBoss EAP server artifacts are defined.
2: You can retrieve the version of this feature pack from the JBoss EAP channel. The Galleon feature-pack includes Galleon layers such as cloud-server for provisioning trimmed JBoss EAP servers.
3: This feature pack adjusts the server Galleon layers for the cloud. It is necessary to use this feature pack to build applications for OpenShift.
4: This Galleon layer provisions a server with features that are necessary when running JBoss EAP applications in the cloud.
5: With this configuration option, you can register your deployment in the HTTP root context.
6: With this plug-in goal, you can provision the server, deploy your application, apply custom configured CLI scripts, and copy custom content into the server installation.

Package the application.
```
$ mvn package
```
The directory target/server contains a server and application that are ready for use for debugging or development purposes. In the JBoss EAP S2I build context, the server provisioned by the JBoss EAP maven-plugin is installed in the JBoss EAP image at the /opt/server location. For more information see Building Applications Images using Source-to-Image (S2I) in OpenShift.

Verification

You can check the generated server configuration file target/server/standalone/configuration/standalone.xml that contains the provisioned subsystems and application deployment.

The JBoss EAP server that contains your deployment has been provisioned.

Additional resources

3.5.4. The Galleon provisioning file

Provisioning files are XML files with the name provisioning.xml that you can store in the galleon subdirectory. Using them is an alternative to configuring feature packs and layers in the JBoss EAP Maven plug-in. You can configure provisioning.xml file to fine-tune the provisioning process.

The following code demonstrates a provisioning file content that you can use to provision JBoss EAP server based on the cloud-server layer.

Note

The JBoss EAP feature packs don’t have versions, versions are retrieved from the configured channel in the Maven plug-in.

<?xml version="1.0" ?>
<installation xmlns="urn:jboss:galleon:provisioning:3.0">
    <feature-pack location="org.jboss.eap:wildfly-ee-galleon-pack:">1
        <default-configs inherit="false"/>2
        <packages inherit="false"/>3
    </feature-pack>
    <feature-pack location="org.jboss.eap.cloud:eap-cloud-galleon-pack:
">4
        <default-configs inherit="false"/>
        <packages inherit="false"/>
    </feature-pack>
    <config model="standalone" name="standalone.xml">5
        <layers>
            <include name="cloud-server"/>
        </layers>
    </config>
    <options>6
        <option name="optional-packages" value="passive+"/>
    </options>
</installation>

1: This element instructs the provisioning process to provision the JBoss EAP feature pack retrieved from the JBoss EAP channel.
2: This element instructs the provisioning process to exclude default configurations. You can retrieve default configurations in JBoss EAP server installation, such as standalone.xml and standalone-ha.xml. When you are provisioning JBoss EAP server from the JBoss EAP Maven plugin, generate a single server configuration based on the configured Galleon users. Setting the option to false prevents the generation of any additional server configurations. Setting inherit=true is not supported for both default-configs and packages.
3: This element instructs the provisioning process to exclude default packages.
4: This element instructs the provisioning process to provision the JBoss EAP cloud feature pack. The child elements instruct the process to exclude default configurations and default packages.
5: This element instructs the provisioning process to create a custom standalone configuration. The configuration includes the cloud-server base layer defined in the JBoss EAP feature pack and tuned for OpenShift by the JBoss EAP cloud feature pack.
6: This element instructs the provisioning process to optimize provisioning of JBoss EAP modules.

3.5.5. The Maven plug-in configuration attributes

You can configure the eap-maven-plugin Maven plug-in by setting the following list of configuration parameters.

Table 3.1. The Maven plug-in configuration attributes

Name	Type	Description
channels	List	A list of channel YAML file references. A channel file contains the versions of the JBoss EAP server artifacts. There are two ways to identify a channel YAML file. If you deploy the channel YAML file artifact in a Maven repository with the channels classifier, then you can identify it using it’s Maven coordinates: `groupId`, `artifactId` and optional version. If version is not set, it uses the latest channel version. For example: <channels> <channel> <groupId>org.jboss.eap.channels</groupId> <artifactId>eap-8.0-beta</artifactId> </channel> </channels> You can retrieve the channel YAML file by using the URL. For example: <channels> <channel> <url>file:///path/to/channel.yaml</url> </channel> </channels>
`excluded-layers`	List	A list of Galleon layers to exclude. You can use it when `feature-pack-location` or feature packs are set. Use the system property `wildfly.provisioning.layers.excluded` to provide a comma-separated list of layers to exclude.
`extra-server-content-dirs`	List	A list of directories from which content is copied to the provisioned server. You can use either the absolute path to the directory or the relative path. The relative path must be relative to the project base directory.
`feature-packs`	List	A list of feature pack configurations to install, which you can combine with layers. Use the system property `wildfly.provisioning.feature-packs` to provide a comma-separated list of feature packs.
`filename`	String	The file name of the application to deploy. The default value is `${project.build.finalName}.${project.packaging}`. In an exception case, `ejb` packaging results in `.jar` extension. For example, the value of `$[project.packaging]` during war packaging is `war` and the value of `$[project.packaging]` during ejb packaging is `ejb`, which is not a valid jar extension. These cases require the `.jar` extension.
`galleon-options`	Map	When provisioning the server, you can set specific Galleon options. If you are building a large number of servers in the same Maven session, you must set `jboss-fork-embedded` option to `true` to fork Galleon provisioning and CLI scripts execution. For example: <galleon-options> <jboss-fork-embedded>true</jboss-fork-embedded> </galleon-options>
`layers`	List	A list of Galleon layers to provision. You can use it when `feature-pack-location` or feature packs are set. Use the system property `wildfly.provisioning.layers` to provide a comma-separated list of layers.
`layers-configuration-file-name`	String	A name of the configuration file generated from layers. The default value is `standalone.xml`. You cannot set this parameter if layers are not configured.
`log-provisioning-time`	boolean	Specifies whether to log the provisioning time at the end of the provisioning. The default value is `false`.
`name`	String	A name used for the deployment.
`offline-provisioning`	boolean	Specifies whether to use offline mode when the plug-in resolves an artifact. In offline mode, the plug-in uses the local Maven repository for artifact resolution. The default value is `false`.
`overwrite-provisioned-server`	boolean	If you want to delete the existing server referenced from the `provisioningDir` and provision a new one, set it to `true`. If not, set it to `false`. The default value is `false`.
`packaging-scripts`	List	A list of CLI scripts and commands to execute. If a script file is not absolute, it must be relative to the project base directory. Configure the CLI executions in the following way: <packaging-scripts> <packaging-script> <scripts> <script>../scripts/script1.cli</script> </scripts> <commands> <command>/system-property=foo:add(value=bar)</command> </commands> <properties-files> <property-file>my-properties.properties</property-file> </properties-files> <java-opts> <java-opt>-Xmx256m</java-opt> </java-opts> <!-- Expressions resolved during server execution --> <resolve-expressions>false</resolve-expressions> </packaging-script> </packaging-scripts>
`provisioning-dir`	String	Path to the directory in which to provision the server. It can be an absolute path or a path relative to the `buildDir`. By default, the server is provisioned into the `target/server` directory. The default value is `server`.
`provisioning-file`	File	The path to the `provisioning.xml` file to use. You cannot use it when feature packs configuration item and layers configuration item are set. If the provisioning file path is not absolute, it must be relative to the project base directory. The default value is `${project.basedir}/galleon/provisioning.xml`.
`record-provisioning-state`	boolean	Specifies whether to record the provisioning state in `.galleon` directory. The default value is `false`.
`runtime-name`	String	The runtime-name of the deployment. The default value is the deployment file name, such as `myapp.war`. You can set this argument to `ROOT.war` to get the deployment registered in the HTTP root context.
`server-config`	String	The name of the server configuration to use during deployment. The deployment is deployed inside the configuration referenced from `layers-configuration-file-name` if `layers-configuration-file-name` is set. The default value is `standalone.xml`.
`skip`	boolean	If you want the goal to be skipped, set it to `true`. If not, set it to `false`. The default value is `false`.
`stdout`	String	Indicates how `stdout` and `stderr` are handled for the created CLI processes. `stderr` is redirected to `stdout` if the value is defined unless the value is none. By default the `stdout` and `stderr` streams are inherited from the current process. You can change the setting to one from the following options: `None` indicates that `stderr` and `stdout` should not be used. `System.out` or `System.err` to redirect to the current processes. Any other value is assumed to be the path to a file and the `stdout` and `stderr` will be written to it.

Select Your Language

Infrastructure and Management

Cloud Computing

Storage

Runtimes

Integration and Automation

Language:

Language:

Chapter 3. Environment variables and model expression resolution

3.1. Prerequisites

3.2. Environment variables for resolving management model expressions

System property to environment variable mapping

3.3. Configuring environment variables on the OpenShift Container Platform

3.4. Overriding management attributes with environment variables

3.5. Provisioning a JBoss EAP server using the Maven plug-in

3.5.1. JBoss EAP Maven plug-in

3.5.2. Creating a Jakarta EE 10 application with the Maven

3.5.3. Using the Maven plug-in to provision a JBoss EAP server

3.5.4. The Galleon provisioning file

3.5.5. The Maven plug-in configuration attributes

Language:

Language and Page Formatting Options

Language:

Chapter 3. Environment variables and model expression resolution

3.1. Prerequisites

3.2. Environment variables for resolving management model expressions

System property to environment variable mapping

3.3. Configuring environment variables on the OpenShift Container Platform

3.4. Overriding management attributes with environment variables

3.5. Provisioning a JBoss EAP server using the Maven plug-in

3.5.1. JBoss EAP Maven plug-in

3.5.2. Creating a Jakarta EE 10 application with the Maven

3.5.3. Using the Maven plug-in to provision a JBoss EAP server

3.5.4. The Galleon provisioning file

3.5.5. The Maven plug-in configuration attributes