Chapter 11. The bootable JAR

Procedure

1. Identify the supported JBoss EAP Galleon layers that provide the capabilities that you need to run your application.

2. Reference a JBoss EAP feature pack location in the <plugin> element of the Maven project pom.xml file. The following example displays the inclusion of a single feature-pack, which includes the jaxrs-server base layer and the jpa-distributed layer . The jaxrs-server base layer provides additional support for the server.

   Copy to Clipboard Toggle word wrap

   <plugins>
   	<plugin>
   		<groupId>org.wildfly.plugins</groupId>
   		<artifactId>wildfly-jar-maven-plugin</artifactId>
   		<version>${bootable.jar.maven.plugin.version}</version>
   		<configuration>
   			<channels>
   				<channel>
   					<manifest>
   						<groupId>org.jboss.eap.channels</groupId>
   						<artifactId>eap-8.0</artifactId>
   					</manifest>
   				</channel>
   				<channel>
   					<manifest>
   						<groupId>org.jboss.eap.channels</groupId>
   						<artifactId>eap-xp-5.0</artifactId>
   					</manifest>
   				</channel>
   			</channels>
   			<feature-pack-location>org.jboss.eap.xp:wildfly-galleon-pack</feature-pack-location>
   			<layers>
   				<layer>jaxrs-server</layer>
   				<layer>jpa-distributed</layer>
   			</layers>
   			<excluded-layers>
   				<layer>jpa</layer>
   			</excluded-layers>
                    ...
   		</configuration>
   	</plugin>
   </plugins>

   This example also shows the exclusion of the jpa layer from the project.

   Note

   If you include the jpa-distributed layer in your project, you must exclude the jpa layer from the jaxrs-server layer. The jpa layer configures a local infinispan hibernate cache, while the jpa-distributed layer configures a remote infinispan hibernate cache.

Procedure

1. Add the following content to the <build> element of the pom.xml file. For example:

   Copy to Clipboard Toggle word wrap

   <plugins>
   	<plugin>
   		<groupId>org.wildfly.plugins</groupId>
   		<artifactId>wildfly-jar-maven-plugin</artifactId>
   		<version>${bootable.jar.maven.plugin.version}</version>
   		<configuration>
   			<channels>
   				<channel>
   					<manifest>
   						<groupId>org.jboss.eap.channels</groupId>
   						<artifactId>eap-8.0</artifactId>
   					</manifest>
   				</channel>
   				<channel>
   					<manifest>
   						<groupId>org.jboss.eap.channels</groupId>
   						<artifactId>eap-xp-5.0</artifactId>
   					</manifest>
   				</channel>
   			</channels>
   			<feature-pack-location>org.jboss.eap.xp:wildfly-galleon-pack</feature-pack-location>
   			<layers>
   				<layer>jaxrs-server</layer>
   				<layer>microprofile-platform</layer>
   			</layers>
   		</configuration>
   		<executions>
   			<execution>
   				<goals>
   					<goal>package</goal>
   				</goals>
   			</execution>
   		</executions>
   	</plugin>
   </plugins>

   Note

   If you do not specify Galleon layers in your pom.xml file then the bootable JAR server contains a configuration that is identical to a standalone-microprofile.xml configuration.

2. Package the application as a bootable JAR:

   Copy to Clipboard Toggle word wrap

   $ mvn package

3. Start the application:

   Copy to Clipboard Toggle word wrap

   $ NAME="foo" java -jar target/microprofile-config-bootable.jar

   Note

   The example uses NAME as the environment variable, but you can choose to use jim, which is the default value.

   Note

   To view a list of supported bootable JAR arguments, append --help to the end of the java -jar target/microprofile-config-bootable.jar command.

4. Specify the following URL in your web browser to access the MicroProfile Config application:

   Copy to Clipboard Toggle word wrap

   http://localhost:8080/config/json

5. Verification: Test the application behaves properly by issuing the following command in your terminal:

   Copy to Clipboard Toggle word wrap

   curl http://localhost:8080/config/json

   The following is the expected output:

   Copy to Clipboard Toggle word wrap

   {"result":"Hello foo"}

Procedure

1. To build a hollow bootable JAR, you must set the <hollow-jar> plug-in configuration element to true in the project pom.xml file. For example:

1. Build the hollow bootable JAR:

   Copy to Clipboard Toggle word wrap

   $ mvn clean package

2. Run the hollow bootable JAR:

   Copy to Clipboard Toggle word wrap

   $ java -jar target/microprofile-config-bootable.jar --deployment=target/microprofile-config.war

   Important

   To specify the path to the WAR file that you want to deploy on the server, use the following argument, where <PATH_NAME> is the path to your deployment.

   Copy to Clipboard Toggle word wrap

   --deployment=<PATH_NAME>

3. Access the application:

   Copy to Clipboard Toggle word wrap

   $ curl http://localhost:8080/microprofile-config/config/json

   Note

   To register your web application in the root directory, name the application ROOT.war.

Procedure

1. Create a directory named scripts at the root directory of your project. For example:

   Copy to Clipboard Toggle word wrap

   $ mkdir scripts

2. Create a cli.properties file and save the file in the /scripts directory. Define the config.path and the config.ordinal system properties in this file. For example:

   Copy to Clipboard Toggle word wrap

   config.path=/etc/config
   config.ordinal=200

3. Create a CLI script, such as mp-config.cli, and save it in an accessible directory in the bootable JAR, such as the /scripts directory. The following example shows the contents of the mp-config.cli script:

   Copy to Clipboard Toggle word wrap

   # config map
   
   /subsystem=microprofile-config-smallrye/config-source=os-map:add(dir={path=${config.path}}, ordinal=${config.ordinal})

   The mp-config.cli CLI script creates a new ConfigSource, to which ordinal and path values are retrieved from a properties file.

4. Save the script in the /scripts directory, which is located at the root directory of the project.

5. Add the following configuration extract to the existing plug-in <configuration> element:

   Copy to Clipboard Toggle word wrap

   <cli-sessions>
       <cli-session>
           <properties-file>
               scripts/cli.properties
           </properties-file>
           <script-files>
               <script>scripts/mp-config.cli</script>
           </script-files>
       </cli-session>
   </cli-sessions>

6. Package the application:

   Copy to Clipboard Toggle word wrap

   $ mvn package

7. Log in to your OpenShift instance using the oc login command.

8. Optional: If you have not previously created a target/openshift subdirectory, you must create the suddirectory by issuing the following command:

   Copy to Clipboard Toggle word wrap

   $ mkdir target/openshift

9. Copy the packaged application into the created subdirectory.

   Copy to Clipboard Toggle word wrap

   $ cp target/microprofile-config-bootable.jar target/openshift

10. Use the target/openshift subdirectory as the binary input to build the application:

    Copy to Clipboard Toggle word wrap

    $ oc start-build microprofile-config-app --from-dir target/openshift

    Note

    OpenShift applies a set of CLI script commands to the bootable JAR configuration file to enable it for the cloud environment. You can access this script by opening the bootable-jar-build-artifacts/generated-cli-script.txt file in the Maven project /target directory.

11. Create a ConfigMap. For example:

    Copy to Clipboard Toggle word wrap

    $ oc create configmap microprofile-config-map --from-literal=name="Name comes from Openshift ConfigMap"

12. Mount the ConfigMap into the application with the dc. For example:

    Copy to Clipboard Toggle word wrap

    $ oc set volume deployments/microprofile-config-app --add --name=config-volume \
    --mount-path=/etc/config \
    --type=configmap \
    --configmap-name=microprofile-config-map

    After executing the oc set volume command, the application is re-deployed with the new configuration settings.

13. Test the output:

    Copy to Clipboard Toggle word wrap

    $ curl http://$(oc get route microprofile-config-app --template='{{ .spec.host }}')/config/json

    The following is the expected output:

    Copy to Clipboard Toggle word wrap

    {"result":"Hello Name comes from Openshift ConfigMap"}

Procedure

1. Set up the Maven project:

   Copy to Clipboard Toggle word wrap

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

2. In the pom.xml file, configure Maven to retrieve the JBoss EAP BOM file from a remote repository.

   Copy to Clipboard Toggle word wrap

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

3. To configure 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:

   Copy to Clipboard Toggle word wrap

   <dependencyManagement>
     <dependencies>
       <dependency>
           <groupId>org.jboss.bom</groupId>
           <artifactId>jboss-eap-ee</artifactId>
           <version>8.0.2.GA-redhat-00007</version>
           <type>pom</type>
           <scope>import</scope>
       </dependency>
     </dependencies>
   </dependencyManagement>

4. Add the servlet API artifact, which is managed by the BOM, to the <dependency> section of the project pom.xml file, as shown in the following example:

   Copy to Clipboard Toggle word wrap

   <dependency>
       <groupId>jakarta.servlet</groupId>
       <artifactId>jakarta.servlet-api</artifactId>
       <scope>provided</scope>
   </dependency>

Procedure

1. Add the JBoss Logging and Jakarta RESTful Web Services dependencies, which are managed by the BOM, to the <dependencies> section of the project pom.xml file. For example:

   Copy to Clipboard Toggle word wrap

   <dependencies>
       <dependency>
           <groupId>org.jboss.logging</groupId>
           <artifactId>jboss-logging</artifactId>
           <scope>provided</scope>
       </dependency>
       <dependency>
           <groupId>jakarta.ws.rs</groupId>
           <artifactId>jakarta.ws.rs-api</artifactId>
           <scope>provided</scope>
       </dependency>
   </dependencies>

2. Add the following content to the <build> element of the pom.xml file. For example:

   Copy to Clipboard Toggle word wrap

   <plugins>
   	<plugin>
   		<groupId>org.wildfly.plugins</groupId>
   		<artifactId>wildfly-jar-maven-plugin</artifactId>
   		<version>${bootable.jar.maven.plugin.version}</version>
   		<configuration>
   			<channels>
   				<channel>
   					<manifest>
   						<groupId>org.jboss.eap.channels</groupId>
   						<artifactId>eap-8.0</artifactId>
   					</manifest>
   				</channel>
   				<channel>
   					<manifest>
   						<groupId>org.jboss.eap.channels</groupId>
   						<artifactId>eap-xp-5.0</artifactId>
   					</manifest>
   				</channel>
   			</channels>
   			<feature-packs>
   				<feature-pack>
   					<location>org.jboss.eap.xp:wildfly-galleon-pack</location>
   				</feature-pack>
   			</feature-packs>
   			<layers>
   				<layer>jaxrs-server</layer>
   			</layers>
   		</configuration>
   		<executions>
   			<execution>
   				<goals>
   					<goal>package</goal>
   				</goals>
   			</execution>
   		</executions>
   	</plugin>
   </plugins>

3. Create the directory to store Java files:

   Copy to Clipboard Toggle word wrap

   $ mkdir -p APPLICATION_ROOT/src/main/java/com/example/logging/

   Where APPLICATION_ROOT is the directory containing the pom.xml configuration file for the application.

4. Create a Java file RestApplication.java with the following content and save the file in the APPLICATION_ROOT/src/main/java/com/example/logging/ directory:

   Copy to Clipboard Toggle word wrap

   package com.example.logging;
   import jakarta.ws.rs.ApplicationPath;
   import jakarta.ws.rs.core.Application;
   
   @ApplicationPath("/")
   public class RestApplication extends Application {
   }

5. Create a Java file HelloWorldEndpoint.java with the following content and save the file in the APPLICATION_ROOT/src/main/java/com/example/logging/ directory:

   Copy to Clipboard Toggle word wrap

   package com.example.logging;
   
   import jakarta.ws.rs.Path;
   import jakarta.ws.rs.core.Response;
   import jakarta.ws.rs.GET;
   import jakarta.ws.rs.Produces;
   
   import org.jboss.logging.Logger;
   @Path("/hello")
   public class HelloWorldEndpoint {
   
       private static Logger log = Logger.getLogger(HelloWorldEndpoint.class.getName());
       @GET
       @Produces("text/plain")
       public Response doGet() {
           log.debug("HelloWorldEndpoint.doGet called");
           return Response.ok("Hello from XP bootable jar!").build();
       }
   }

6. Create a CLI script, such as logging.cli, and save it in an accessible directory in the bootable JAR, such as the APPLICATION_ROOT/scripts directory, where APPLICATION_ROOT is the root directory of your Maven project. The script must contain the following commands:

   Copy to Clipboard Toggle word wrap

   /subsystem=logging/logger=com.example.logging:add(level=ALL)
   /subsystem=logging/json-formatter=json-formatter:add(exception-output-type=formatted, pretty-print=false, meta-data={version="1"}, key-overrides={timestamp="@timestamp"})
   /subsystem=logging/console-handler=CONSOLE:write-attribute(name=level,value=ALL)
   /subsystem=logging/console-handler=CONSOLE:write-attribute(name=named-formatter, value=json-formatter)

7. Add the following configuration extract to the plug-in <configuration> element:

   Copy to Clipboard Toggle word wrap

   <cli-sessions>
           <cli-session>
           <script-files>
               <script>scripts/logging.cli</script>
           </script-files>
       </cli-session>
   </cli-sessions>

   This example shows the logging.cli CLI script, which modifies the server logging configuration file to enable JSON logging for your application.

8. Package the application as a bootable JAR.

   Copy to Clipboard Toggle word wrap

   $ mvn package

9. Optional: To run the application on a JBoss EAP bare-metal platform, follow the steps outlined in Using a bootable JAR on a JBoss EAP bare-metal platform, but with the following difference:

   1. Start the application:

      Copy to Clipboard Toggle word wrap

      mvn wildfly-jar:run

   2. Verification: You can access the application by specifying the following URL in your browser: http://127.0.0.1:8080/hello.

      Expected output: You can view the JSON-formatted logs, including the com.example.logging.HelloWorldEndpoint debug trace, in the application console.

10. Optional: To run the application on a JBoss EAP OpenShift platform, complete the following steps:

    1. Add the <cloud/> element to the plug-in configuration. For example:

       Copy to Clipboard Toggle word wrap

       <plugins>
          <plugin>
              ... <!-- You must evolve the existing configuration with the <cloud/> element  -->
              <configuration >
                  ...
                  <cloud/>
               </configuration>
           </plugin>
       </plugins>

    2. Rebuild the application:

       Copy to Clipboard Toggle word wrap

       $ mvn clean package

    3. Log in to your OpenShift instance using the oc login command.

    4. Create a new project in OpenShift. For example:

       Copy to Clipboard Toggle word wrap

       $ oc new-project bootable-jar-project

    5. Enter the following oc commands to create an application image:

       Copy to Clipboard Toggle word wrap

       $ mkdir target/openshift && cp target/logging-bootable.jar target/openshift 

       1

       
       
       $ oc import-image ubi8/openjdk-17 --from=registry.redhat.io/ubi8/openjdk-17 --confirm
        

       2

       
       
       $ oc new-build --strategy source --binary --image-stream openjdk-17 --name logging 

       3

       
       
       $ oc start-build logging --from-dir target/openshift 

       4

       1

       Creates the target/openshift subdirectory. The packaged application is copied into the openshift subdirectory.

       2

       Imports the latest OpenJDK 17 imagestream tag and image information into the OpenShift project.

       3

       Creates a build configuration based on the logging directory and the OpenJDK 17 imagestream.

       4

       Uses the target/openshift subdirectory as the binary input to build the application.

    6. Deploy the application:

       Copy to Clipboard Toggle word wrap

       $ oc new-app logging
       
       $ oc expose svc/logging

    7. Get the URL of the route.

       Copy to Clipboard Toggle word wrap

       $ oc get route logging --template='{{ .spec.host }}'

    8. Access the application in your web browser using the URL returned from the previous command. For example:

       Copy to Clipboard Toggle word wrap

       http://ROUTE_NAME/hello

    9. Verification: Issue the following command to view a list of OpenShift pods available, and to check the pods build statuses:

       Copy to Clipboard Toggle word wrap

       $ oc get pods

       Access a running pod log of your application. Where APP_POD_NAME is the name of the running pod logging application.

       Copy to Clipboard Toggle word wrap

       $ oc logs APP_POD_NAME

       Expected outcome: The pod log is in JSON format and includes the com.example.logging.HelloWorldEndpoint debug trace.

Procedure

1. Add the following content to the <build> element of the pom.xml file. For example:

   Copy to Clipboard Toggle word wrap

   <plugins>
   	<plugin>
   		<groupId>org.wildfly.plugins</groupId>
   		<artifactId>wildfly-jar-maven-plugin</artifactId>
   		<version>${bootable.jar.maven.plugin.version}</version>
   		<configuration>
   			<channels>
   				<channel>
   					<manifest>
   						<groupId>org.jboss.eap.channels</groupId>
   						<artifactId>eap-8.0</artifactId>
   					</manifest>
   				</channel>
   				<channel>
   					<manifest>
   						<groupId>org.jboss.eap.channels</groupId>
   						<artifactId>eap-xp-5.0</artifactId>
   					</manifest>
   				</channel>
   			</channels>
   			<feature-pack-location>org.jboss.eap.xp:wildfly-galleon-pack</feature-pack-location>
   			<layers>
   				<layer>datasources-web-server</layer>
   				<layer>web-clustering</layer>
   			</layers>
   		</configuration>
   		<executions>
   			<execution>
   				<goals>
   					<goal>package</goal>
   				</goals>
   			</execution>
   		</executions>
   	</plugin>
   </plugins>

   Note

   This example makes use of the web-clustering Galleon layer to enable web session sharing.

2. Update the web.xml file in the src/main/webapp/WEB-INF directory with the following configuration:

   Copy to Clipboard Toggle word wrap

   <?xml version="1.0" encoding="UTF-8"?>
   
   <web-app version="4.0"
            xmlns="http://xmlns.jcp.org/xml/ns/javaee"
            xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
            xsi:schemaLocation="http://xmlns.jcp.org/xml/ns/javaee  http://xmlns.jcp.org/xml/ns/javaee/web-app_4_0.xsd">
       <distributable/>
   </web-app>

   The <distributable/> tag indicates that this servlet can be distributed across multiple servers.

3. Create the directory to store Java files:

   Copy to Clipboard Toggle word wrap

   $ mkdir -p APPLICATION_ROOT
   /src/main/java/com/example/webclustering/

   Where APPLICATION_ROOT is the directory containing the pom.xml configuration file for the application.

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

   Copy to Clipboard Toggle word wrap

   package com.example.webclustering;
   
   import java.io.IOException;
   import java.io.PrintWriter;
   import jakarta.servlet.ServletException;
   import jakarta.servlet.annotation.WebServlet;
   import jakarta.servlet.http.HttpServlet;
   import jakarta.servlet.http.HttpServletRequest;
   import jakarta.servlet.http.HttpServletResponse;
   
   @WebServlet(urlPatterns = {"/clustering"})
   public class MyServlet extends HttpServlet {
       @Override
       protected void doGet(HttpServletRequest request, HttpServletResponse response)
               throws IOException {
           response.setContentType("text/html;charset=UTF-8");
           long t;
           User user = (User) request.getSession().getAttribute("user");
           if (user == null) {
               t = System.currentTimeMillis();
               user = new User(t);
               request.getSession().setAttribute("user", user);
           }
           try (PrintWriter out = response.getWriter()) {
               out.println("<!DOCTYPE html>");
               out.println("<html>");
               out.println("<head>");
               out.println("<title>Web clustering demo</title>");
               out.println("</head>");
               out.println("<body>");
               out.println("<h1>Session id " + request.getSession().getId() + "</h1>");
               out.println("<h1>User Created " + user.getCreated() + "</h1>");
               out.println("<h1>Host Name " + System.getenv("HOSTNAME") + "</h1>");
               out.println("</body>");
               out.println("</html>");
           }
       }
   }

   The content in MyServlet.java defines the endpoint to which a client sends an HTTP request.

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

   Copy to Clipboard Toggle word wrap

   package com.example.webclustering;
   
   import java.io.Serializable;
   
   public class User implements Serializable {
       private final long created;
   
       User(long created) {
           this.created = created;
       }
       public long getCreated() {
           return created;
       }
   }

6. Package the application:

   Copy to Clipboard Toggle word wrap

   $ mvn package

7. Optional: To run the application on a JBoss EAP bare-metal platform, follow the steps outlined in Using a bootable JAR on a JBoss EAP bare-metal platform, but with the following difference:

   1. On a JBoss EAP bare-metal platform, you can use the java -jar command to run multiple bootable JAR instances, as demonstrated in the following examples:

      Copy to Clipboard Toggle word wrap

      $ java -jar target/web-clustering-bootable.jar -Djboss.node.name=node1
      
      $ java -jar target/web-clustering-bootable.jar -Djboss.node.name=node2 -Djboss.socket.binding.port-offset=10

   2. Verification: You can access the application on the node 1 instance: http://127.0.0.1:8080/clustering. Note the user session ID and the user-creation time.

      After you kill this instance, you can access the node 2 instance: http://127.0.0.1:8090/clustering. The user must match the session ID and the user-creation time of the node 1 instance.

8. Optional: To run the application on a JBoss EAP OpenShift platform, follow the steps outlined in Using a bootable JAR on a JBoss EAP OpenShift platform, but complete the following steps:

   1. Add the <cloud/> element to the plug-in configuration. For example:

      Copy to Clipboard Toggle word wrap

      <plugins>
         <plugin>
             ... <!-- You must evolve the existing configuration with the <cloud/> element  -->
             <configuration >
                 ...
                 <cloud/>
              </configuration>
          </plugin>
      </plugins>

   2. Rebuild the application:

      Copy to Clipboard Toggle word wrap

      $ mvn clean package

   3. Log in to your OpenShift instance using the oc login command.

   4. Create a new project in OpenShift. For example:

      Copy to Clipboard Toggle word wrap

      $ oc new-project bootable-jar-project

   5. To run a web-clustering application on a JBoss EAP OpenShift platform, authorization access must be granted for the service account that the pod is running in. The service account can then access the Kubernetes REST API. The following example shows authorization access being granted to a service account:

      Copy to Clipboard Toggle word wrap

      $ oc policy add-role-to-user view system:serviceaccount:$(oc project -q):default

   6. Enter the following oc commands to create an application image:

      Copy to Clipboard Toggle word wrap

      $ mkdir target/openshift && cp target/web-clustering-bootable.jar target/openshift 

      1

      
      
      $ oc import-image ubi8/openjdk-17 --from=registry.redhat.io/ubi8/openjdk-17 --confirm 

      2

      
      
      $ oc new-build --strategy source --binary --image-stream openjdk-17 --name web-clustering 

      3

      
      
      $ oc start-build web-clustering --from-dir target/openshift 

      4

      1

      Creates the target/openshift sub-directory. The packaged application is copied into the openshift sub-directory.

      2

      Imports the latest OpenJDK 17 imagestream tag and image information into the OpenShift project.

      3

      Creates a build configuration based on the web-clustering directory and the OpenJDK 17 imagestream.

      4

      Uses the target/openshift sub-directory as the binary input to build the application.

   7. Deploy the application:

      Copy to Clipboard Toggle word wrap

      $ oc new-app web-clustering -e KUBERNETES_NAMESPACE=$(oc project -q)
      
      $ oc expose svc/web-clustering

      Important

      You must use the KUBERNETES_NAMESPACE environment variable to view other pods in the current OpenShift namespace; otherwise, the server attempts to retrieve the pods from the default namespace.

   8. Get the URL of the route.

      Copy to Clipboard Toggle word wrap

      $ oc get route web-clustering --template='{{ .spec.host }}'

   9. Access the application in your web browser using the URL returned from the previous command. For example:

      Copy to Clipboard Toggle word wrap

      http://ROUTE_NAME/clustering

      Note the user session ID and user creation time.

   10. Scale the application to two pods:

       Copy to Clipboard Toggle word wrap

       $ oc scale --replicas=2 deployments web-clustering

   11. Issue the following command to view a list of OpenShift pods available, and to check the pods build statuses:

       Copy to Clipboard Toggle word wrap

       $ oc get pods

   12. Kill the oldest pod using the oc delete pod web-clustering-POD_NAME command, where POD_NAME is the name of your oldest pod.

   13. Access the application again:

       Copy to Clipboard Toggle word wrap

       http://ROUTE_NAME/clustering

       Expected outcome: The session ID and the creation time generated by the new pod match those of the of the terminated pod. This indicates that web session data storage is enabled.

Procedure

1. Add the following content to the <build> element of the pom.xml file. For example:

   Copy to Clipboard Toggle word wrap

   <plugins>
   	<plugin>
   		<groupId>org.wildfly.plugins</groupId>
   		<artifactId>wildfly-jar-maven-plugin</artifactId>
   		<version>${bootable.jar.maven.plugin.version}</version>
   		<configuration>
   			<channels>
   				<channel>
   					<manifest>
   						<groupId>org.jboss.eap.channels</groupId>
   						<artifactId>eap-8.0</artifactId>
   					</manifest>
   				</channel>
   				<channel>
   					<manifest>
   						<groupId>org.jboss.eap.channels</groupId>
   						<artifactId>eap-xp-5.0</artifactId>
   					</manifest>
   				</channel>
   			</channels>
   			<feature-pack-location>org.jboss.eap.xp:wildfly-galleon-pack</feature-pack-location>
   			<layers>
   				<layer>datasources-web-server</layer>
   			</layers>
   		</configuration>
   		<executions>
   			<execution>
   				<goals>
   					<goal>package</goal>
   				</goals>
   			</execution>
   		</executions>
   	</plugin>
   </plugins>

   The example shows the inclusion of the datasources-web-server Galleon layer that contains the elytron subsystem.

2. Update the web.xml file in the src/main/webapp/WEB-INF directory. For example:

   Copy to Clipboard Toggle word wrap

   <?xml version="1.0" encoding="UTF-8"?>
   
   <web-app version="4.0"
            xmlns="http://xmlns.jcp.org/xml/ns/javaee"
            xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
            xsi:schemaLocation="http://xmlns.jcp.org/xml/ns/javaee  http://xmlns.jcp.org/xml/ns/javaee/web-app_4_0.xsd">
   
       <login-config>
           <auth-method>BASIC</auth-method>
           <realm-name>Example Realm</realm-name>
       </login-config>
   
   </web-app>

3. Create the directory to store Java files:

   Copy to Clipboard Toggle word wrap

   $ mkdir -p APPLICATION_ROOT/src/main/java/com/example/authentication/

   Where APPLICATION_ROOT is the root directory of your Maven project.

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

   Copy to Clipboard Toggle word wrap

   package com.example.authentication;
   
   import jakarta.servlet.annotation.HttpMethodConstraint;
   import jakarta.servlet.annotation.ServletSecurity;
   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")
   @ServletSecurity(httpMethodConstraints = { @HttpMethodConstraint(value = "GET", rolesAllowed = { "Users" }) })
   public class TestServlet extends HttpServlet {
   
       @Override
       protected void doGet(HttpServletRequest req, HttpServletResponse resp) throws IOException {
           PrintWriter writer = resp.getWriter();
           writer.println("Hello " + req.getUserPrincipal().getName());
           writer.close();
       }
   
   }

5. Create a CLI script, such as authentication.cli, and save it in an accessible directory in the bootable JAR, such as the APPLICATION_ROOT/scripts directory. The script must contain the following commands:

   Copy to Clipboard Toggle word wrap

   /subsystem=elytron/properties-realm=bootable-realm:add(users-properties={relative-to=jboss.server.config.dir, path=bootable-users.properties, plain-text=true}, groups-properties={relative-to=jboss.server.config.dir, path=bootable-groups.properties})
   /subsystem=elytron/security-domain=BootableDomain:add(default-realm=bootable-realm, permission-mapper=default-permission-mapper, realms=[{realm=bootable-realm, role-decoder=groups-to-roles}])
   
   /subsystem=undertow/application-security-domain=other:write-attribute(name=security-domain, value=BootableDomain)

6. Add the following configuration extract to the plug-in <configuration> element:

   Copy to Clipboard Toggle word wrap

   <cli-sessions>
       <cli-session>
           <script-files>
               <script>scripts/authentication.cli</script>
           </script-files>
       </cli-session>
   </cli-sessions>

   This example shows the authentication.cli CLI script, which configures the default undertow security domain to the security domain defined for your server.

   Note

   You have the option to execute the CLI script at runtime instead of packaging time. To do so, skip this step and proceed to step 10.

7. In the root directory of your Maven project create a directory to store the properties files that the JBoss EAP JAR Maven plug-in adds to the bootable JAR:

   Copy to Clipboard Toggle word wrap

   $ mkdir -p APPLICATION_ROOT/extra-content/standalone/configuration/

   Where APPLICATION_ROOT is the directory containing the pom.xml configuration file for the application.

   This directory stores files such as bootable-users.properties and bootable-groups.properties files.

   The bootable-users.properties file contains the following content:

   Copy to Clipboard Toggle word wrap

   testuser=bootable_password

   The bootable-groups.properties file contains the following content:

   Copy to Clipboard Toggle word wrap

   testuser=Users

8. Add the following extra-content-content-dirs element to the existing <configuration> element:

   Copy to Clipboard Toggle word wrap

   <extra-server-content-dirs>
               <extra-content>extra-content</extra-content>
   </extra-server-content-dirs>

   The extra-content directory contains the properties files.

9. Package the application as a bootable JAR.

   Copy to Clipboard Toggle word wrap

   $ mvn package

10. Start the application:

    Copy to Clipboard Toggle word wrap

    mvn wildfly-jar:run

    If you have chosen to skip step 6 and not execute the CLI script during build, launch the application with the following command:

    Copy to Clipboard Toggle word wrap

    mvn wildfly-jar:run -Dwildfly.bootable.arguments=--cli-script=scripts/authentication.cli

11. Call the servlet, but do not specify credentials:

    Copy to Clipboard Toggle word wrap

    curl -v http://localhost:8080/hello

    Expected output:

    Copy to Clipboard Toggle word wrap

    HTTP/1.1 401 Unauthorized
    ...
    WWW-Authenticate: Basic realm="Example Realm"

12. Call the server and specify your credentials. For example:

    Copy to Clipboard Toggle word wrap

    $ curl -v -u testuser:bootable_password http://localhost:8080/hello

    A HTTP 200 status is returned that indicates HTTP authentication is enabled for your bootable JAR. For example:

    Copy to Clipboard Toggle word wrap

    HTTP/1.1 200 OK
    ....
    Hello testuser