Chapter 6. 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. 6.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. 6.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 21. You have installed the Maven 3.6 or later version. For more information, see Downloading Apache Maven . Procedure Set up the Maven project. USD 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.GA-redhat-00009</version> <type>pom</type> <scope>import</scope> </dependency> </dependencies> </dependencyManagement> Note <version>A.B.C-redhat-XXXXX</version> Where A.B.C is the release number and XXXXX is build number of your JBoss EAP instance. See the Red Hat Maven repository for version details about JBoss EAP releases. The release and build numbers are available for all JBoss EAP releases. https://maven.repository.redhat.com/earlyaccess/all/org/jboss/bom/jboss-eap-ee/ . 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. 6.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 21. You have installed Maven. For more information, see Downloading Apache Maven . Note If you are using JDK 17 and Maven 3.8.5 or 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/ga/</url> <snapshots> <enabled>false</enabled> </snapshots> </repository> </repositories> <pluginRepositories> <pluginRepository> <id>jboss</id> <url>https://maven.repository.redhat.com/ga/</url> <snapshots> <enabled>false</enabled> </snapshots> </pluginRepository> </pluginRepositories> Add the following content to the <build> element of the pom.xml file. For example: <plugins> <plugin> <groupId>org.jboss.eap.plugins</groupId> <artifactId>eap-maven-plugin</artifactId> <version>1.0.0.Final-redhat-00014</version> 1 <configuration> <channels> <channel> <manifest> <groupId>org.jboss.eap.channels</groupId> 2 <artifactId>eap-8.0</artifactId> </manifest> </channel> </channels> <feature-packs> <feature-pack> <location>org.jboss.eap:wildfly-ee-galleon-pack</location> 3 </feature-pack> <feature-pack> <location>org.jboss.eap.cloud:eap-cloud-galleon-pack</location> 4 </feature-pack> </feature-packs> <layers> <layer>cloud-server</layer> 5 </layers> <runtime-name>ROOT.war</runtime-name> 6 </configuration> <executions> <execution> <goals> <goal>package</goal> 7 </goals> </execution> </executions> </plugin> </plugins> 1 <version>1.0.0.Final-redhat-00014</version> is an example version of JBoss EAP Maven plugin. See the Red Hat Maven repository for more information on JBoss EAP Maven plugin releases: https://maven.repository.redhat.com/earlyaccess/all/org/jboss/eap/plugins/eap-maven-plugin/ . 2 This specifies the JBoss EAP 8.0 channel in which the JBoss EAP server artifacts are defined. 3 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. 4 This feature pack adjusts the server Galleon layers for the cloud. It is necessary to use this feature pack to build applications for OpenShift. 5 This Galleon layer provisions a server with features that are necessary when running JBoss EAP applications in the cloud. 6 With this configuration option, you can register your deployment in the HTTP root context. 7 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. 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 . Note If you use the mvn package command with debugging enabled ( -X option), include the property -Dorg.slf4j.simpleLogger.log.com.networknt.schema=off to prevent excessive debug logging during schema validation. 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 Available JBoss EAP layers . Use the Maven Repository . Introduction to the Standard Directory Layout in the Apache Maven documentation . 6.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. 6.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 6.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: You can retrieve the channel YAML file by using the URL. For example: 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 USD{project.build.finalName}.USD{project.packaging} . In an exception case, ejb packaging results in .jar extension. For example, the value of USD[project.packaging] during war packaging is war and the value of USD[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 USD{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. 6.6. How to enable support for eap-datasources-galleon-pack for JBoss EAP 8.0 The eap-data-sources-galleon-pack Galleon feature pack allows you to provision a JBoss EAP 8.0 server that can connect to your databases. Note Not all databases are supported. In addition, this feature pack provides JDBC drivers and data sources for various databases that can be provisioned along with the JBoss EAP 8.0 Galleon feature packs. Galleon layers defined in this feature pack are decorator layers. This means that they need to be provisioned in addition to a JBoss EAP base layer. Important The datasources-web-server base layer, is the minimal base layer to use when provisioning Galleon layers that are feature pack defined. Additional resources JBoss EAP 8.0 defined layer documentation 6.7. Supported drivers and data sources For each database the Galleon feature pack supports, it provides Galleon layers that build upon each other, these are: postgresql-driver postgresql-datasource mssqlserver-datasource mssqlserver-driver oracle-datasource oracle-driver Table 6.2. Supported drivers and data sources Layers Description postgresql-driver This installs a JBoss EAP module for the driver and adds a driver resource to the data sources subsystem in the server configuration. postgresql-datasource This is built upon the postgresql-driver Galleon layer to add a data source. Note No specific driver version is included in the feature pack. Before you provision your server, you have to specify the driver version. Example POSTGRESQL_DRIVER_VERSION="42.2.19" The driver-specific environment variables are defined within their specific driver documentation. Additional resources Environment variables to configure Microsoft SQL Server driver and data source Environment variables to configure Oracle driver and data source Environment variables to configure PostgreSQL driver and data source 6.8. Using the JBoss EAP Maven plugin to provision a server with JDBC drivers and data sources You can use the Galleon feature pack to provision your JBoss EAP server on OpenShift. Note This procedure only demonstrates how to provision your JBoss EAP server on OpenShift for JBoss EAP 8.0. Prerequisites You have already installed OpenShift and set up the OpenShift CLI ("oc"). For more information, see Getting Started with the OpenShift CLI . You have basic knowledge of how to use the JBoss EAP maven plugin. For more information, see JBoss EAP Maven plug-in . Procedure Add the Maven coordinates (GroupId and artifactId) of the data sources feature pack to the JBoss EAP maven plugin configuration. <channels> <channel> <groupId>org.jboss.eap.channels</groupId> <artifactId>eap-8.0</artifactId> </channel> </channels> <feature-packs> <feature-pack> <location>org.jboss.eap:wildfly-ee-galleon-pack</location> </feature-pack> <feature-pack> <location>org.jboss.eap.cloud:eap-cloud-galleon-pack</location> </feature-pack> <feature-pack> <location>org.jboss.eap:eap-datasources-galleon-pack</location> </feature-pack> </feature-packs> <layers> <!-- Base layer --> <layer>jaxrs-server</layer> <!-- The postgresql datasource layer --> <layer>postgresql-datasource</layer> </layers> Additional resources JBoss EAP 8 Beta Maven Plugin configuration for the todo-backend quickstart

Commands:
mvn archetype:generate -DgroupId=GROUP_ID -DartifactId=ARTIFACT_ID -DarchetypeGroupId=org.apache.maven.archetypes -DarchetypeArtifactId=maven-archetype-webapp -DinteractiveMode=false
<dependencyManagement> <dependencies> <dependency> <groupId>org.jboss.bom</groupId> <artifactId>jboss-eap-ee</artifactId> <version>8.0.0.GA-redhat-00009</version> <type>pom</type> <scope>import</scope> </dependency> </dependencies> </dependencyManagement>
<dependency> <groupId>jakarta.servlet</groupId> <artifactId>jakarta.servlet-api</artifactId> </dependency>
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(); } }
<repositories> <repository> <id>jboss</id> <url>https://maven.repository.redhat.com/ga/</url> <snapshots> <enabled>false</enabled> </snapshots> </repository> </repositories> <pluginRepositories> <pluginRepository> <id>jboss</id> <url>https://maven.repository.redhat.com/ga/</url> <snapshots> <enabled>false</enabled> </snapshots> </pluginRepository> </pluginRepositories>
<plugins> <plugin> <groupId>org.jboss.eap.plugins</groupId> <artifactId>eap-maven-plugin</artifactId> <version>1.0.0.Final-redhat-00014</version> 1 <configuration> <channels> <channel> <manifest> <groupId>org.jboss.eap.channels</groupId> 2 <artifactId>eap-8.0</artifactId> </manifest> </channel> </channels> <feature-packs> <feature-pack> <location>org.jboss.eap:wildfly-ee-galleon-pack</location> 3 </feature-pack> <feature-pack> <location>org.jboss.eap.cloud:eap-cloud-galleon-pack</location> 4 </feature-pack> </feature-packs> <layers> <layer>cloud-server</layer> 5 </layers> <runtime-name>ROOT.war</runtime-name> 6 </configuration> <executions> <execution> <goals> <goal>package</goal> 7 </goals> </execution> </executions> </plugin> </plugins>
mvn package
<?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>
<channels> <channel> <manifest> <groupId>org.jboss.eap.channels</groupId> <artifactId>eap-8.0</artifactId> </manifest> </channel> </channels>
<channels> <channel> <manifest> <url>file:///foo/my-manifest.yaml</url> </manifest> </channel> </channels>
<galleon-options> <jboss-fork-embedded>true</jboss-fork-embedded> </galleon-options>
<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>
<channels> <channel> <groupId>org.jboss.eap.channels</groupId> <artifactId>eap-8.0</artifactId> </channel> </channels> <feature-packs> <feature-pack> <location>org.jboss.eap:wildfly-ee-galleon-pack</location> </feature-pack> <feature-pack> <location>org.jboss.eap.cloud:eap-cloud-galleon-pack</location> </feature-pack> <feature-pack> <location>org.jboss.eap:eap-datasources-galleon-pack</location> </feature-pack> </feature-packs> <layers> <!-- Base layer --> <layer>jaxrs-server</layer> <!-- The postgresql datasource layer --> <layer>postgresql-datasource</layer> </layers>