Using Eclipse MicroProfile with JBoss EAP XP 2.0.0

Procedure

1. If you have not applied the JBoss EAP 7.3.4 GA patch patch to your JBoss EAP server, apply the JBoss EAP 7.3.4 GA patch using the JBoss EAP XP manager 2.0.0 patch-apply command:

   $ java -jar jboss-eap-xp-manager.jar patch-apply --jboss-home=/PATH/TO/EAP --patch=/PATH/TO/PATCH/jboss-eap-7.3.4-patch.zip

   The patch-apply command is similar to the patch apply management CLI command. You can use the patch apply management CLI command to apply the patch as well.

2. Set up JBoss EAP XP manager 2.0.0 to manage the EAP XP 2.0 patch stream using the following command:

   $ java -jar jboss-eap-xp-manager.jar setup --jboss-home=/PATH/TO/EAP

   Note

   You can apply the JBoss EAP XP 2.0.0 patch at the same time. Include the path to the JBoss EAP XP 2.0.0 patch using the --xp-patch argument.

   Example:

   $ java -jar jboss-eap-xp-manager.jar setup --jboss-home=/PATH/TO/EAP --xp-patch /PATH/TO/PATCH/jboss-eap-xp-2.0.0-patch.zip

   The server is now ready to manage the JBoss EAP XP 2.0 patch stream.

3. Optional: If you did not use the the --xp-patch argument with the setup command, apply the JBoss EAP XP 2.0.0 patch using the JBoss EAP XP manager 2.0.0 patch-apply command:

   $ java -jar jboss-eap-xp-manager.jar patch-apply --jboss-home=/PATH/TO/EAP --patch=/PATH/TO/PATCH/jboss-eap-xp-2.0.0-patch.zip

Procedure

1. Verify that your server is on the correct patch and has JBoss EAP XP 1.0.x installed:

   $ java -jar jboss-eap-xp-manager.jar status --jboss-home=__<path_to_eap>__
   ...
   You are currently on JBoss EAP XP 1.
   You are using an old version of JBoss EAP XP. The current version is 2, please upgrade.
   Enabled patch streams and their cumulative patch ids:
   - Patch stream: 'JBoss EAP'; Cumulative patch id: 'jboss-eap-7.3.4'
   - Patch stream: 'jboss-eap-xp-1.0'; Cumulative patch id: 'jboss-eap-xp-1.0.0.CP'
   Available commands in this state are: [remove, upgrade]

   This output indicates that your server is ready for upgrade to JBoss EAP XP 2.0.0.

   If you see other output, refer to the troubleshooting recommendations.

2. Use the upgrade command to upgrade JBoss EAP XP 1.0.x to 2.0.0 and apply the JBoss EAP XP 2.0.0 patch.

   $ java -jar jboss-eap-xp-manager.jar upgrade --jboss-home=__<path_to_eap>__ --xp-patch=__<path_to_patch>__/jboss-eap-xp-2.0.0-patch.zip

3. Accept the support policy prompt by entering yes.

   Your server is ready to manage the JBoss EAP XP 2.0.0 patch stream and is updated with the JBoss EAP XP 2.0.0 patch.

Procedure

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

2. Create a new project in OpenShift.

   A project allows a group of users to organize and manage content separately from other groups. You can create a project in OpenShift using the following command.

   $ oc new-project PROJECT_NAME

   For example, for the microprofile-config quickstart, create a new project named eap-demo using the following command.

   $ oc new-project eap-demo

Procedure

1. Follow the instructions on Red Hat Customer Portal to create an authentication token using a Registry Service Account management application.

2. Download the YAML file containing the OpenShift secret for the token.

   You can download the YAML file from the OpenShift Secret tab on your token’s Token Information page.

3. Create the authentication token secret for your OpenShift project using the YAML file that you downloaded:

   oc create -f 1234567_myserviceaccount-secret.yaml

4. Configure the secret for your OpenShift project using the following commands, replacing the secret name below with the name of your secret created in the previous step.

   oc secrets link default 1234567-myserviceaccount-pull-secret --for=pull
   oc secrets link builder 1234567-myserviceaccount-pull-secret --for=pull

   Additional resources

   • Configuring authentication to the Red Hat Container Registry
   • Registry Service Account management application
   • Configuring access to secured registries

Procedure

1. Use one of the following commands to import the latest JDK 8 and JDK 11 imagestreams and templates for the OpenShift image for JBoss EAP XP into your OpenShift project’s namespace.

   1. Import JDK 8 imagestreams:

      oc replace --force -f https://raw.githubusercontent.com/jboss-container-images/jboss-eap-openshift-templates/eap-xp2/jboss-eap-xp2-openjdk8-openshift.json

      This command imports the following imagestreams and templates:

      • The JDK 8 builder imagestream: jboss-eap-xp2-openjdk8-openshift
      • The JDK 8 runtime imagestream: jboss-eap-xp2-openjdk8-runtime-openshift

   2. Import JDK 11 imagestream:

      oc replace --force -f https://raw.githubusercontent.com/jboss-container-images/jboss-eap-openshift-templates/eap-xp2/jboss-eap-xp2-openjdk11-openshift.json

      This command imports the following imagestreams and templates:

      • The JDK 11 builder imagestream: jboss-eap-xp2-openjdk11-openshift
      • The JDK 11 runtime imagestream: jboss-eap-xp2-openjdk11-runtime-openshift

   3. Import the JDK 8 and JDK 11 templates:

      for resource in \
      eap-xp2-basic-s2i.json \
      eap-xp2-third-party-db-s2i.json
      do
      oc replace --force -f https://raw.githubusercontent.com/jboss-container-images/jboss-eap-openshift-templates/eap-xp2/templates/${resource}
      done

   Note

   The JBoss EAP XP imagestreams and templates imported using the above command are only available within that OpenShift project.

2. If you have administrative access to the general openshift namespace and want the imagestreams and templates to be accessible by all projects, add -n openshift to the oc replace line of the command. For example:

   ...
   oc replace -n openshift --force -f \
   ...

3. If you want to import the imagestreams and templates into a different project, add the -n PROJECT_NAME to the oc replace line of the command. For example:

   ...
   oc replace -n PROJECT_NAME --force -f
   ...

   If you use the cluster-samples-operator, see the OpenShift documentation on configuring the cluster samples operator. See https://docs.openshift.com/container-platform/latest/openshift_images/configuring-samples-operator.html for details about configuring the cluster samples operator.

Procedure

1. Create a new OpenShift application using the JBoss EAP XP image and your Java application’s source code. Use one of the provided JBoss EAP XP templates for S2I builds.

   $ oc new-app --template=eap-xp2-basic-s2i \ 1
    -p EAP_IMAGE_NAME=jboss-eap-xp2-openjdk8-openshift:latest \
    -p EAP_RUNTIME_IMAGE_NAME=jboss-eap-xp2-openjdk8-runtime-openshift:latest \
    -p IMAGE_STREAM_NAMESPACE=eap-demo \ 2
    -p SOURCE_REPOSITORY_URL=https://github.com/jboss-developer/jboss-eap-quickstarts \ 3
    -p SOURCE_REPOSITORY_REF=xp-2.0.x \ 4
    -p CONTEXT_DIR=microprofile-config 5

   1

   The template to use. The application image is tagged with the latest tag.

   2

   The latest images streams and templates were imported into the project’s namespace, so you must specify the namespace of where to find the imagestream. This is usually the project’s name.

   3

   URL to the repository containing the application source code.

   4

   The Git repository reference to use for the source code. This can be a Git branch or tag reference.

   5

   The directory within the source repository to build.

   As another example, to deploy the microprofile-config quickstart using the JDK 11 runtime image enter the following command. The command uses the eap-xp2-basic-s2i template in the eap-demo project, created in the Preparing OpenShift for application deployment section, with the microprofile-config source code on GitHub.

   $ oc new-app --template=eap-xp2-basic-s2i \ 1
    -p EAP_IMAGE_NAME=jboss-eap-xp2-openjdk11-openshift:latest \
    -p EAP_RUNTIME_IMAGE_NAME=jboss-eap-xp2-openjdk11-runtime-openshift:latest \
    -p IMAGE_STREAM_NAMESPACE=eap-demo \ 2
    -p SOURCE_REPOSITORY_URL=https://github.com/jboss-developer/jboss-eap-quickstarts \ 3
    -p SOURCE_REPOSITORY_REF=xp-2.0.x \ 4
    -p CONTEXT_DIR=microprofile-config 5

   1

   The template to use. The application image is tagged with the latest tag.

   2

   The latest imagestreams and templates were imported into the project’s namespace, so you must specify the namespace where to find the imagestream. This is usually the project’s name.

   3

   URL to the repository containing the application source code.

   4

   The Git repository reference to use for the source code. This can be a Git branch or tag reference.

   5

   The directory within the source repository to build.

   Note

   A template can specify default values for many template parameters, and you might have to override some, or all, of the defaults. To see template information, including a list of parameters and any default values, use the command oc describe template TEMPLATE_NAME.

   You might also want to configure environment variables when creating your new OpenShift application.

2. Retrieve the name of the build configurations.

   $ oc get bc -o name

3. Use the name of the build configurations from the previous step to view the Maven progress of the builds.

   $ oc logs -f buildconfig/${APPLICATION_NAME}-build-artifacts
   
   …
   Push successful
   $ oc logs -f buildconfig/${APPLICATION_NAME}
   …
   Push successful

   For example, for the microprofile-config, the following command shows the progress of the Maven builds.

   $ oc logs -f buildconfig/eap-xp2-basic-app-build-artifacts
   
   …
   Push successful
   $ oc logs -f buildconfig/eap-xp2-basic-app
   …
   Push successful

   Additional resources

   • Importing the latest OpenShift imagestreams and templates for JBoss EAP XP
   • Preparing OpenShift for application deployment

Procedure

1. Get the service name of your application using the following command.

   $ oc get service

2. Optional: Expose the main service as a route so you can access your application from outside of OpenShift. For example, for the microprofile-config quickstart, use the following command to expose the required service and port.

   Note

   If you used a template to create the application, the route might already exist. If it does, continue on to the next step.

   $ oc expose service/eap-xp2-basic-app --port=8080

3. Get the URL of the route.

   $ oc get route

4. Access the application in your web browser using the URL. The URL is the value of the HOST/PORT field from previous command’s output.

   Note

   For JBoss EAP XP 2.0.0 GA distribution, the Microprofile Config quickstart does not reply to HTTPS GET requests to the application’s root context. This enhancement is only available in the {JBossXPShortName101} GA distribution.

   For example, to interact with the Microprofile Config application, the URL might be http://HOST_PORT_Value/config/value in your browser.

   If your application does not use the JBoss EAP root context, append the context of the application to the URL. For example, for the microprofile-config quickstart, the URL might be http://HOST_PORT_VALUE/microprofile-config/.

5. Optionally, you can scale up the application instance by running the following command. This command increases the number of replicas to 3.

   $ oc scale deploymentconfig DEPLOYMENTCONFIG_NAME --replicas=3

   For example, for the microprofile-config quickstart, use the following command to scale up the application.

   $ oc scale deploymentconfig/eap-xp2-basic-app --replicas=3

Procedure

1. Set up the new server on the New Server dialog box.

   1. In the Select server type list, select Red Hat JBoss Enterprise Application Platform 7.3.
   2. In the Server’s host name field, enter localhost.
   3. In the Server name field, enter JBoss EAP 7.3 XP.
   4. Click Next.

2. Configure the new server.

   1. In the Home directory field, if you do not want to use the default setting, specify a new directory; for example: home/myname/dev/microprofile/runtimes/jboss-eap-7.3.
   2. Make sure the Execution Environment is set to JavaSE-1.8.
   3. Optional: Change the values in the Server base directory and Configuration file fields.
   4. Click Finish.

Procedure

1. Import the pom.xml file from the Quickstart Parent Artifact.

2. If the quickstart you are using requires environment variables, configure the environment variables.

   Define environment variables on the launch configuration on the server Overview dialog box.

   For example, the microprofile-opentracing quickstart uses the following environment variables:

   • JAEGER_REPORTER_LOG_SPANS set to true
   • JAEGER_SAMPLER_PARAM set to 1
   • JAEGER_SAMPLER_TYPE set to const

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. You must specify the latest version of any Maven plug-in and the latest version of the org.jboss.eap:wildfly-galleon-pack Galleon feature pack, as demonstrated in the following example. The following example also 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.

   <plugins>
         <plugin>
               <groupId>org.wildfly.plugins</groupId>
                <artifactId>wildfly-jar-maven-plugin</artifactId>
                <version>${bootable.jar.maven.plugin.version}</version>
               <configuration>
                    <feature-pack-location>org.jboss.eap:wildfly-galleon-pack:${jboss.xp.galleon.feature.pack.version}</feature-pack-location>
                    <layers>
                        <layer>jaxrs-server</layer>
                        <layer>jpa-distributed</layer>
                    </layers>
                    <excluded-layers>
                        <layer>jpa</layer>
                    </excluded-layers>
                    ...
   </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. You must specify the latest version of any Maven plug-in and the latest version of the org.jboss.eap:wildfly-galleon-pack Galleon feature pack. For example:

   <plugins>
       <plugin>
           <groupId>org.wildfly.plugins</groupId>
           <artifactId>wildfly-jar-maven-plugin</artifactId>
           <version>${bootable.jar.maven.plugin.version}</version>
           <configuration>
                <feature-pack-location>org.jboss.eap:wildfly-galleon-pack:${jboss.xp.galleon.feature.pack.version}</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:

   $ mvn package

3. Start the application:

   $ 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 Eclipse MicroProfile Config application:

   http://localhost:8080/config/json

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

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

   The following is the expected output:

   {"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:

   $ mvn clean package

2. Run the hollow bootable JAR:

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

   --deployment=<PATH_NAME>

3. Access the application:

   $ 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. Add the following content to the <build> element of the pom.xml file. You must specify the latest version of any Maven plug-in and the latest version of the org.jboss.eap:wildfly-galleon-pack Galleon feature pack. For example:

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

   Note

   You must include the <cloud/> element in the <configuration> element of the plug-in configuration, so the JBoss EAP Maven JAR plug-in can identify that you choose the OpenShift platform.

2. Package the application:

   $ mvn package

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

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

   $ oc new-project bootable-jar-project

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

   $ mkdir target/openshift && cp target/microprofile-config-bootable.jar target/openshift  1
   
   $ oc import-image ubi8/openjdk-11 --from=registry.redhat.io/ubi8/openjdk-11 --confirm 2
   
   $ oc new-build --strategy source --binary --image-stream openjdk-11 --name microprofile-config-app 3
   
   $ oc start-build microprofile-config-app --from-dir target/openshift 4

   1

   Creates an openshift sub-directory in the target directory. The packaged application is copied into the created sub-directory.

   2

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

   3

   Creates a build configuration based on the microprofile-config-app directory and the OpenJDK 11 imagestream.

   4

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

   Note

   OpenShift applies a set of CLI script commands to the bootable JAR configuration file to adjust it to 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.

6. Verification:

   View a list of OpenShift pods available and check the pods build statuses by issuing the following command:

   $ oc get pods

   Verify the built application image:

   $ oc get is microprofile-config-app

   The output shows the built application image details, such as name and image repository, tag, and so on. For the example in this procedure, the imagestream name and tag output displays microprofile-config-app:latest.

7. Deploy the application.

   Important

   To provide system properties to the bootable JAR, you must use the JAVA_OPTS_APPEND environment variable. The following example demonstrates usage of the JAVA_OPTS_APPEND environment variable.

   oc new-app <_IMAGESTREAM_> -e JAVA_OPTS_APPEND="-Xlog:gc*:file=/tmp/gc.log:time -Dwildfly.statistics-enabled=true"

   $ oc new-app microprofile-config-app
   
   $ oc expose svc/microprofile-config-app

   Important

   To provide system properties to the bootable JAR, you must use the JAVA_OPTS_APPEND environment variable. The following example demonstrates usage of the JAVA_OPTS_APPEND environment variable:

   $ oc new-app <_IMAGESTREAM_> -e JAVA_OPTS_APPEND="-Xlog:gc*:file=/tmp/gc.log:time -Dwildfly.statistics-enabled=true"

   A new application is created and started. The application configuration is exposed as a new service.

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

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

   Expected output:

   {"result":"Hello jim"}

Procedure

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

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

   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:

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

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

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

   $ mkdir target/openshift

9. Copy the packaged application into the created subdirectory.

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

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

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

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

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

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

    The following is the expected output:

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

Procedure

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

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

   <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-jakartaee8 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-jakartaee8</artifactId>
           <version>7.3.4.GA</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:

   <dependency>
       <groupId>org.jboss.spec.javax.servlet</groupId>
       <artifactId>jboss-servlet-api_4.0_spec</artifactId>
       <scope>provided</scope>
   </dependency>

Procedure

1. Add the JBoss Logging and JAX-RS dependencies, which are managed by the BOM, to the <dependencies> section of the project pom.xml file. For example:

   <dependencies>
       <dependency>
           <groupId>org.jboss.logging</groupId>
           <artifactId>jboss-logging</artifactId>
           <scope>provided</scope>
       </dependency>
       <dependency>
           <groupId>org.jboss.spec.javax.ws.rs</groupId>
           <artifactId>jboss-jaxrs-api_2.1_spec</artifactId>
           <scope>provided</scope>
       </dependency>
   </dependencies>

2. Add the following content to the <build> element of the pom.xml file. You must specify the latest version of any Maven plug-in and the latest version of the org.jboss.eap:wildfly-galleon-pack Galleon feature pack. For example:

   <plugins>
       <plugin>
           <groupId>org.wildfly.plugins</groupId>
           <artifactId>wildfly-jar-maven-plugin</artifactId>
           <version>${bootable.jar.maven.plugin.version}</version>
           <configuration>
               <feature-packs>
                   <feature-pack>
                       <location>org.jboss.eap:wildfly-galleon-pack:${jboss.xp.galleon.feature.pack.version}</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:

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

   package com.example.logging;
   import javax.ws.rs.ApplicationPath;
   import javax.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:

   package com.example.logging;
   
   import javax.ws.rs.Path;
   import javax.ws.rs.core.Response;
   import javax.ws.rs.GET;
   import javax.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:

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

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

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

      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:

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

    2. Rebuild the application:

       $ mvn clean package

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

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

       $ oc new-project bootable-jar-project

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

       $ mkdir target/openshift && cp target/logging-bootable.jar target/openshift 1
       
       $ oc import-image ubi8/openjdk-11 --from=registry.redhat.io/ubi8/openjdk-11 --confirm
        2
       
       $ oc new-build --strategy source --binary --image-stream openjdk-11 --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 11 imagestream tag and image information into the OpenShift project.

       3

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

       4

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

    6. Deploy the application:

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

    7. Get the URL of the route.

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

       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:

       $ oc get pods

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

       $ 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. You must specify the latest version of any Maven plug-in and the latest version of the org.jboss.eap:wildfly-galleon-pack Galleon feature pack. For example:

   <plugins>
       <plugin>
           <groupId>org.wildfly.plugins</groupId>
           <artifactId>wildfly-jar-maven-plugin</artifactId>
           <version>${bootable.jar.maven.plugin.version}</version>
           <configuration>
               <feature-pack-location>org.jboss.eap:wildfly-galleon-pack:${jboss.xp.galleon.feature.pack.version}</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:

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

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

   package com.example.webclustering;
   
   import java.io.IOException;
   import java.io.PrintWriter;
   import javax.servlet.ServletException;
   import javax.servlet.annotation.WebServlet;
   import javax.servlet.http.HttpServlet;
   import javax.servlet.http.HttpServletRequest;
   import javax.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.

   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:

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

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

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

   2. Rebuild the application:

      $ mvn clean package

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

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

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

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

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

      $ mkdir target/openshift && cp target/web-clustering-bootable.jar target/openshift 1
      
      $ oc import-image ubi8/openjdk-11 --from=registry.redhat.io/ubi8/openjdk-11 --confirm 2
      
      $ oc new-build --strategy source --binary --image-stream openjdk-11 --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 11 imagestream tag and image information into the OpenShift project.

      3

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

      4

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

   7. Deploy the application:

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

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

      http://ROUTE_NAME/clustering

      Note the user session ID and user creation time.

   10. Scale the application to two pods:

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

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

       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. You must specify the latest version of any Maven plug-in and the latest version of the org.jboss.eap:wildfly-galleon-pack Galleon feature pack. For example:

   <plugins>
       <plugin>
            <groupId>org.wildfly.plugins</groupId>
            <artifactId>wildfly-jar-maven-plugin</artifactId>
            <version>${bootable.jar.maven.plugin.version}</version>
            <configuration>
                <feature-pack-location>org.jboss.eap:wildfly-galleon-pack:${jboss.xp.galleon.feature.pack.version}</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:

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

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

   package com.example.authentication;
   
   import javax.servlet.annotation.HttpMethodConstraint;
   import javax.servlet.annotation.ServletSecurity;
   import javax.servlet.annotation.WebServlet;
   import javax.servlet.http.HttpServlet;
   import javax.servlet.http.HttpServletRequest;
   import javax.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:

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

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

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:

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

   testuser=bootable_password

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

   testuser=Users

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

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

   $ mvn package

10. Start the application:

    mvn wildfly-jar:run

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

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

    Expected output:

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

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

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

    HTTP/1.1 200 OK
    ....
    Hello testuser

Procedure

1. Add the following content to the <build> element of the pom.xml file. You must specify the latest version of any Maven plug-in and the latest version of the org.jboss.eap:wildfly-galleon-pack Galleon feature pack. For example:

   <plugins>
       <plugin>
           <groupId>org.wildfly.plugins</groupId>
           <artifactId>wildfly-jar-maven-plugin</artifactId>
           <version>${bootable.jar.maven.plugin.version}</version>
           <configuration>
               <feature-packs>
                   <feature-pack>
                       <location>org.jboss.eap:wildfly-galleon-pack:${jboss.xp.galleon.feature.pack.version}</location>
                   </feature-pack>
                   <feature-pack>
                       <location>org.jboss.sso:keycloak-adapter-galleon-pack:${keycloak.feature.pack.version}</location>
                   </feature-pack>
               </feature-packs>
               <layers>
                   <layer>datasources-web-server</layer>
                   <layer>keycloak-client-oidc</layer>
               </layers>
           </configuration>
           <executions>
               <execution>
                   <goals>
                       <goal>package</goal>
                   </goals>
               </execution>
           </executions>
       </plugin>
   </plugins>

   The Maven plug-in provisions subsystems and modules that are required for deploying the web application.

   The keycloak-client-oidc layer provides Red Hat Single Sign-On OpenID Connect client adapters to your project by using the keycloak subsystem and its dependencies to activate support for Red Hat Single Sign-On authentication. Red Hat Single Sign-On client adapters are libraries that secure applications and services with Red Hat Single Sign-On.

2. In the project pom.xml file, set the <context-root> to false in your plug-in configuration. This registers the application in the simple-webapp resource path. By default, the WAR file is registered under the root-context path.

   <configuration>
       ...
        <context-root>false</context-root>
        ...
   </configuration>

3. Create a CLI script, such as configure-oidc.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 commands similar to the following example:

   /subsystem=keycloak/secure-deployment=simple-webapp.war:add( \
       realm=demo, \
       resource=simple-webapp, \
       public-client=true, \
       auth-server-url=http://localhost:8090/auth/, \
       ssl-required=EXTERNAL)

   This script example defines the secure-deployment=simple-webapp.war resource in the keycloak subsystem. The simple-webapp.war resource is the name of the WAR file that is deployed in the bootable JAR.

4. In the project pom.xml file, add the following configuration extract to the existing plug-in <configuration> element:

   <cli-sessions>
       <cli-session>
           <script-files>
               <script>scripts/configure-oidc.cli</script>
           </script-files>
       </cli-session>
   </cli-sessions>

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

   <?xml version="1.0" encoding="UTF-8"?>
   
   <web-app version="2.5" xmlns="http://java.sun.com/xml/ns/javaee"
      xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
      xsi:schemaLocation="http://java.sun.com/xml/ns/javaee http://java.sun.com/xml/ns/javaee/web-app_2_5.xsd"
      metadata-complete="false">
   
       <login-config>
           <auth-method>BASIC</auth-method>
           <realm-name>Simple Realm</realm-name>
       </login-config>
   
   </web-app>

6. Optional: Alternatively to steps 7 through 9, you can embed the server configuration in the web application by adding the keycloak.json descriptor to the WEB-INF directory of the web application. For example:

   {
       "realm" : "demo",
       "resource" : "simple-webapp",
       "public-client" : "true",
       "auth-server-url" : "http://localhost:8090/auth/",
       "ssl-required" : "EXTERNAL"
   }

   You must then set the <auth-method> of the web application to KEYCLOAK. The following example code illustrates how to set the <auth-method>:

       <login-config>
           <auth-method>KEYCLOAK</auth-method>
           <realm-name>Simple Realm</realm-name>
       </login-config>

7. Create a Java file named SecuredServlet.java with the following content and save the file in the APPLICATION_ROOT/src/main/java/com/example/securedservlet/ directory.

   package com.example.securedservlet;
   
   import java.io.IOException;
   import java.io.PrintWriter;
   import java.security.Principal;
   
   import javax.servlet.ServletException;
   import javax.servlet.annotation.HttpMethodConstraint;
   import javax.servlet.annotation.ServletSecurity;
   import javax.servlet.annotation.WebServlet;
   import javax.servlet.http.HttpServlet;
   import javax.servlet.http.HttpServletRequest;
   import javax.servlet.http.HttpServletResponse;
   
   @WebServlet("/secured")
   @ServletSecurity(httpMethodConstraints = { @HttpMethodConstraint(value = "GET",
       rolesAllowed = { "Users" }) })
   public class SecuredServlet extends HttpServlet {
   
       @Override
       protected void doGet(HttpServletRequest req, HttpServletResponse resp) throws ServletException, IOException {
           try (PrintWriter writer = resp.getWriter()) {
               writer.println("<html>");
               writer.println("<head><title>Secured Servlet</title></head>");
               writer.println("<body>");
               writer.println("<h1>Secured Servlet</h1>");
               writer.println("<p>");
               writer.print(" Current Principal '");
               Principal user = req.getUserPrincipal();
               writer.print(user != null ? user.getName() : "NO AUTHENTICATED USER");
               writer.print("'");
               writer.println("    </p>");
               writer.println("  </body>");
               writer.println("</html>");
           }
       }
   }

8. Package the application as a bootable JAR.

   $ mvn package

9. Start the application. The following example starts the simple-webapp web application from its specified bootable JAR path:

   $ java -jar target/simple-webapp-bootable.jar

10. Specify the following URL in your web browser to access the webpage secured with Red Hat Single Sign-On. The following example shows the URL for the secured simple-webapp web application:

    http://localhost:8080/simple-webapp/secured

11. Log in as a user from your Red Hat Single Sign-On realm.

12. Verification: Check that the webpage displays the following output:

    Current Principal '<principal id>'

Procedure

1. Build and start the bootable JAR in Development Mode:

   $ mvn wildfly-jar:dev

   In dev mode, the server deployment scanner is configured to monitor the target/deployments directory.

2. Prompt the JBoss EAP Maven Plug-in to build and copy your application to the target/deployments directory with the following command:

   $ mvn package -Ddev

   The server packaged inside the bootable JAR deploys the application stored in the target/deployments directory.

3. Modify the code in your application code.
4. Use the mvn package -Ddev to prompt the JBoss EAP Maven Plug-in to re-build your application and re-deploy it.

5. Stop the server. For example:

   $ mvn wildfly-jar:shutdown

6. After you complete your application changes, package your application as a bootable JAR:

   $ mvn package

Procedure

1. Create a CLI script that defines the legacy patches you want to apply to your bootable JAR. The script must contain one or more patch apply commands. The --override-all command is required when patching a server that was trimmed with Galleon layers, for example:

   patch apply patch-oneoff1.zip --override-all
   
   patch apply patch-oneoff2.zip --override-all
   
   patch info --json-output

2. Reference your CLI script in the <legacy-patch-cli-script> element of your pom.xml file.
3. Rebuild the bootable JAR.