Chapter 2. Getting started with Red Hat JBoss Web Server for OpenShift

Procedure

1. Follow the instructions on the Red Hat Customer Portal to create an authentication token using a registry service account.
2. On the Token Information page for your token, click the OpenShift Secret tab and download the YAML file that contains the OpenShift secret for the token.

3. Use the YAML file that you have downloaded to create the authentication token secret for your OpenShift project.

   For example:

   oc create -f 1234567_myserviceaccount-secret.yaml

4. To configure the secret for your OpenShift project, enter the following commands:

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

   Note

   In the preceding examples, replace 1234567-myserviceaccount with the name of the secret that you created in the previous step.

Procedure

1. Log in to the Red Hat Container Registry by using your Customer Portal credentials. For more information, see Red Hat Container Registry Authentication.

2. Depending on the JDK version that you are using, perform one of the following steps:

   • OpenJDK 8

     If you are using OpenJDK 8, enter the following command:

     for resource in \
     jws57-openjdk8-tomcat9-ubi8-basic-s2i.json \
     jws57-openjdk8-tomcat9-ubi8-https-s2i.json \
     jws57-openjdk8-tomcat9-ubi8-image-stream.json
     do
     oc replace -n openshift --force -f \
     https://raw.githubusercontent.com/jboss-container-images/jboss-webserver-5-openshift-image/jws57el8-v5.7.8/templates/${resource}
     done

     The preceding command imports the UBI8 JDK 8 image stream, jboss-webserver57-openjdk8-tomcat9-openshift-ubi8, and all templates specified in the command.

   • OpenJDK 11

     If you are using OpenJDK 11, enter the following command:

     for resource in \
     jws57-openjdk11-tomcat9-ubi8-basic-s2i.json \
     jws57-openjdk11-tomcat9-ubi8-https-s2i.json \
     jws57-openjdk11-tomcat9-ubi8-image-stream.json
     do
     oc replace -n openshift --force -f \
     https://raw.githubusercontent.com/jboss-container-images/jboss-webserver-5-openshift-image/jws57el8-v5.7.8/templates/${resource}
     done

     The preceding command imports the UBI8 JDK 11 image stream, jboss-webserver57-openjdk11-tomcat9-openshift-ubi8, and all templates specified in the command.

   • OpenJDK 17

     If you are using OpenJDK 17, enter the following command:

     for resource in \
     jws57-openjdk17-tomcat9-ubi8-basic-s2i.json \
     jws57-openjdk17-tomcat9-ubi8-https-s2i.json \
     jws57-openjdk17-tomcat9-ubi8-image-stream.json
     do
     oc replace -n openshift --force -f \
     https://raw.githubusercontent.com/jboss-container-images/jboss-webserver-5-openshift-image/jws57el8-v5.7.8/templates/${resource}
     done

     The preceding command imports the UBI8 JDK 17 image stream, jboss-webserver57-openjdk17-tomcat9-openshift-ubi8, and all templates specified in the command.

Procedure

1. On your local file system, create a source directory for the binary build and a deployments subdirectory.

   For example, to create a /ocp source directory and a /deployments subdirectory for the tomcat-websocket-chat application, enter the following commands:

   $ cd tomcat-websocket-chat-quickstart/tomcat-websocket-chat/
   $ mkdir -p ocp/deployments

   Note

   The source directory can contain any content required by your application that is not included in the Maven binary. For more information, see JWS for OpenShift S2I process.

2. Copy the .war,.ear, or .jar binary files to the deployments subdirectory.

   For example, to copy the .war file for the example tomcat-websocket-chat application, enter the following command:

   $ cp target/websocket-chat.war ocp/deployments/

   Note

   In the preceding example, target/websocket-chat.war is the path to the binary file you want to copy.

   Application archives in the deployments subdirectory of the source directory are copied to the $JWS_HOME/tomcat/webapps/ directory of the image that is being built on OpenShift. To allow the application to be deployed successfully, you must ensure that the directory hierarchy that contains the web application data is structured correctly. For more information, see JWS for OpenShift S2I process.

3. Log in to the OpenShift instance:

   $ oc login <url>

4. Create a new project if required.

   For example:

   $ oc new-project jws-bin-demo

   Note

   In the preceding example, jws-bin-demo is the name of the project you want to create.

5. Identify the JWS for OpenShift image stream to use for your application:

   $ oc get is -n openshift | grep ^jboss-webserver | cut -f1 -d ' '

   The preceding command produces the following type of output:

   jboss-webserver57-openjdk8-tomcat9-openshift-ubi8

   Note

   The -n openshift option specifies the project to use. The oc get is -n openshift command gets the image stream resources from the openshift project.

6. Create the new build configuration, and ensure that you specify the image stream and application name.

   For example, to create the new build configuration for the example tomcat-websocket-chat application:

   $ oc new-build --binary=true \
    --image-stream=jboss-webserver57-openjdk8-tomcat9-openshift-ubi8:latest \
    --name=jws-wsch-app

   Note

   In the preceding example, jws-wsch-app is the name of the JWS for OpenShift application.

   The preceding command produces the following type of output:

   --> Found image 8c3b85b (4 weeks old) in image stream "openshift/jboss-webserver57-tomcat9-openshift" under tag "latest" for "jboss-webserver57"
   
       JBoss Web Server 5.7
       --------------------
       Platform for building and running web applications on JBoss Web Server 5.7 - Tomcat v9
   
       Tags: builder, java, tomcat9
   
       * A source build using binary input will be created
         * The resulting image will be pushed to image stream "jws-wsch-app:latest"
         * A binary build was created, use 'start-build --from-dir' to trigger a new build
   
   --> Creating resources with label build=jws-wsch-app ...
       imagestream "jws-wsch-app" created
       buildconfig "jws-wsch-app" created
   --> Success

7. Start the binary build.

   For example:

   $ oc start-build jws-wsch-app --from-dir=./ocp --follow

   Note

   In the preceding example, jws-wsch-app is the name of the JWS for OpenShift application, and ocp is the name of the source directory.

   The preceding command instructs OpenShift to use the source directory that you have created for binary input of the OpenShift image build.

   The preceding command produces the following type of output:

   Uploading directory "ocp" as binary input for the build ...
   build "jws-wsch-app-1" started
   Receiving source from STDIN as archive ...
   
   Copying all deployments war artifacts from /home/jboss/source/deployments directory into `/opt/jws-5.7/tomcat/webapps` for later deployment...
   '/home/jboss/source/deployments/websocket-chat.war' -> '/opt/jws-5.7/tomcat/webapps/websocket-chat.war'
   
   Pushing image 172.30.202.111:5000/jws-bin-demo/jws-wsch-app:latest ...
   Pushed 0/7 layers, 7% complete
   Pushed 1/7 layers, 14% complete
   Pushed 2/7 layers, 29% complete
   Pushed 3/7 layers, 49% complete
   Pushed 4/7 layers, 62% complete
   Pushed 5/7 layers, 92% complete
   Pushed 6/7 layers, 100% complete
   Pushed 7/7 layers, 100% complete
   Push successful

8. Create a new OpenShift application based on the image:

   For example:

   $ oc new-app jws-wsch-app

   Note

   In the preceding example, jws-wsch-app is the name of the JWS for OpenShift application.

   The preceding command produces the following type of output:

   --> Found image e5f3a6b (About a minute old) in image stream "jws-bin-demo/jws-wsch-app" under tag "latest" for "jws-wsch-app"
   
       JBoss Web Server 5.7
       --------------------
       Platform for building and running web applications on JBoss Web Server 5.7 - Tomcat v9
   
       Tags: builder, java, tomcat9
   
       * This image will be deployed in deployment config "jws-wsch-app"
       * Ports 8080/tcp, 8443/tcp, 8778/tcp will be load balanced by service "jws-wsch-app"
         * Other containers can access this service through the hostname "jws-wsch-app"
   
   --> Creating resources ...
       deploymentconfig "jws-wsch-app" created
       service "jws-wsch-app" created
   --> Success
       Application is not exposed. You can expose services to the outside world by executing one or more of the commands below:
        'oc expose svc/jws-wsch-app'
       Run 'oc status' to view your app.

9. Expose the service to make the application accessible to users:

   For example, to make the example jws-wsch-app application accessible, perform the following steps:

   1. Check the name of the service to expose:

      $ oc get svc -o name

      The preceding command produces the following type of output:

      service/jws-wsch-app

   2. Expose the service:

      $ oc expose svc/jws-wsch-app

      The preceding command produces the following type of output:

      route "jws-wsch-app" exposed

10. Retrieve the address of the exposed route:

    oc get routes --no-headers -o custom-columns='host:spec.host' jws-wsch-app

11. Open a web browser and enter the URL to access the application.

    For example, to access the example jws-wsch-app application, enter the following URL:

    http://<address_of_exposed_route>/websocket-chat

    Note

    In the preceding example, replace <address_of_exposed_route> with the appropriate value for your deployment.

Procedure

1. Log in to the OpenShift instance:

   $ oc login <url>

2. Create a new project if required:

   $ oc new-project <project-name>

   Note

   In the preceding example, replace <project-name> with the name of the project you want to create.

3. Identify the JWS for OpenShift image stream to use for your application:

   $ oc get is -n openshift | grep ^jboss-webserver | cut -f1 -d ' '

   The preceding command produces the following type of output:

   jboss-webserver57-openjdk8-tomcat9-openshift-ubi8

   Note

   The -n openshift option specifies the project to use. The oc get is -n openshift command gets the image stream resources from the openshift project.

4. Create the new OpenShift application from source code by using Red Hat JBoss Web Server for OpenShift images:

   $ oc new-app \
    <source_code_location> \
    --image-stream=jboss-webserver57-openjdk8-tomcat9-openshift-ubi8:latest \
    --name=<openshift_application_name>

   For example:

   $ oc new-app \
    https://github.com/web-servers/tomcat-websocket-chat-quickstart.git#main \
    --image-stream=jboss-webserver57-openjdk8-tomcat9-openshift-ubi8:latest \
    --context-dir='tomcat-websocket-chat' \
    --name=jws-wsch-app

   The preceding command adds the source code to the image and compiles the source code. The preceding command also creates the build configuration and services.

5. To expose the application, perform the following steps:

   1. To check the name of the service to expose:

      $ oc get svc -o name

      The preceding command produces the following type of output:

      service/<openshift_application_name>

   2. To expose the service:

      $ oc expose svc/<openshift_application_name>

      The preceding command produces the following type of output:

      route "<openshift_application_name>" exposed

6. To retrieve the address of the exposed route:

   oc get routes --no-headers -o custom-columns='host:spec.host' <openshift_application_name>

7. Open a web browser and enter the following URL to access the application:

   http://<address_of_exposed_route>/<java_application_name>

   Note

   In the preceding example, replace <address_of_exposed_route> and <java_application_name> with appropriate values for your deployment.

Procedure

1. Start the image in Docker:

   docker run --network host -i -t -p 8080:8080 ImageURL

2. Find the CONTAINER ID:

    docker ps | grep <ImageName>

3. Copy the library to the tomcat/lib/ directory:

   docker cp <yourLibrary> <CONTAINER ID>:/opt/jws-5.7/tomcat/lib/

4. Commit the changes to a new image:

   docker commit <CONTAINER ID> <NEW IMAGE NAME>

5. Create a new image tag:

   docker tag <NEW IMAGE NAME>:latest <NEW IMAGE REGISTRY URL>:<TAG>

6. Push the image to a registry:

   docker push <NEW IMAGE REGISTRY URL>