Red Hat Summit Red Hat SummitSupportConsoleDevelopersStart a trialContact

Chapter 3. Get Started

3.1. Initial setup
Copy link

The instructions in this guide follow on from the OpenShift Primer, assuming a supported OpenShift configuration or a non-production OpenShift instance like that described in the OpenShift Primer.

Note

The JWS for OpenShift application templates are distributed for Tomcat 9.

Before you can import and use the Red Hat JBoss Web Server image, you must first configure authentication to the Red Hat Container Registry.

Red Hat recommends that you create an authentication token using a registry service account to configure access to the Red Hat Container Registry. This means that you don’t have to use or store your Red Hat account’s username and password in your OpenShift configuration.

  1. Follow the instructions on Red Hat Customer Portal to create an authentication token using a registry service account.
  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
    Copy to Clipboard Toggle word wrap

  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
    Copy to Clipboard Toggle word wrap

See the OpenShift documentation for more information on other methods for configuring access to secured registries.

See the Red Hat Customer Portal for more information on configuring authentication to the Red Hat Container Registry.

You must import the latest Red Hat JBoss Web Server for OpenShift image streams and templates for your JDK into the namespace of your OpenShift project.

Note

Log in to the Red Hat Container Registry using your Customer Portal credentials to import the Red Hat JBoss Web Server image streams, templates and update image streams. For more information, see Red Hat Container Registry Authentication.

Import command for JDK 8 (RHEL7)

for resource in \
jws54-openjdk8-tomcat9-rhel7-basic-s2i.json \
jws54-openjdk8-tomcat9-rhel7-https-s2i.json \
jws54-openjdk8-tomcat9-rhel7-image-stream.json \
jws54-openjdk8-tomcat9-rhel7-mongodb-persistent-s2i.json \
jws54-openjdk8-tomcat9-rhel7-mongodb-s2i.json \
jws54-openjdk8-tomcat9-rhel7-mysql-persistent-s2i.json \
jws54-openjdk8-tomcat9-rhel7-mysql-s2i.json \
jws54-openjdk8-tomcat9-rhel7-postgresql-persistent-s2i.json \
jws54-openjdk8-tomcat9-rhel7-postgresql-s2i.json
do
oc replace -n openshift --force -f \
https://raw.githubusercontent.com/jboss-container-images/jboss-webserver-5-openshift-image/jws54el7-v1.0/templates/${resource}
done
Copy to Clipboard Toggle word wrap

This command imports the following image streams and templates.

  • The RHEL7 JDK 8 imagestream: jboss-webserver54-openjdk8-tomcat9-openshift-rhel7
  • All templates specified in the command.

Import command for JDK 8 (RHEL8)

for resource in \
jws54-openjdk8-tomcat9-ubi8-basic-s2i.json \
jws54-openjdk8-tomcat9-ubi8-https-s2i.json \
jws54-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/jws54el8-v1.0/templates/${resource}
done
Copy to Clipboard Toggle word wrap

This command imports the following image streams and templates.

  • The RHEL8 JDK 8 imagestream: jboss-webserver54-openjdk8-tomcat9-openshift-ubi8
  • All templates specified in the command.

Import command for JDK 11 (RHEL7)

for resource in \
jws54-openjdk11-tomcat9-rhel7-basic-s2i.json \
jws54-openjdk11-tomcat9-rhel7-https-s2i.json \
jws54-openjdk11-tomcat9-rhel7-image-stream.json \
jws54-openjdk11-tomcat9-rhel7-mongodb-persistent-s2i.json \
jws54-openjdk11-tomcat9-rhel7-mongodb-s2i.json \
jws54-openjdk11-tomcat9-rhel7-mysql-persistent-s2i.json \
jws54-openjdk11-tomcat9-rhel7-mysql-s2i.json \
jws54-openjdk11-tomcat9-rhel7-postgresql-persistent-s2i.json \
jws54-openjdk11-tomcat9-rhel7-postgresql-s2i.json
do
oc replace -n openshift --force -f \
https://raw.githubusercontent.com/jboss-container-images/jboss-webserver-5-openshift-image/jws54el7-v1.0/templates/${resource}
done
Copy to Clipboard Toggle word wrap

This command imports the following image streams and templates.

  • The RHEL7 JDK 11 imagestream: jboss-webserver54-openjdk11-tomcat9-openshift-rhel7
  • All templates specified in the command.

Import command for JDK 11 (RHEL8)

for resource in \
jws54-openjdk8-tomcat9-ubi8-basic-s2i.json \
jws54-openjdk8-tomcat9-ubi8-https-s2i.json \
jws54-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/jws54el8-v1.0/templates/${resource}
done
Copy to Clipboard Toggle word wrap

This command imports the following image streams and templates.

  • The RHEL8 JDK 11 image stream: jboss-webserver54-openjdk11-tomcat9-openshift-ubi8
  • All templates specified in the command.

3.3.1. Update Commands
Copy link

  • In order to update the core JWS 5.4 tomcat 9 OpenJDK8 RHEL7 OpenShift image, you must execute 
$  oc -n openshift import-image \
   jboss-webserver54-openjdk8-tomcat9-openshift-rhel7:1.0
Copy to Clipboard Toggle word wrap
  • In order to update the core JWS 5.4 tomcat 9 OpenJDK8 RHEL8 OpenShift, you must execute 
$ oc -n openshift import-image \
  jboss-webserver54-openjdk8-tomcat9-openshift-ubi8:1.0
Copy to Clipboard Toggle word wrap
  • In order to update the core JWS 5.4 tomcat 9 OpenJDK11 RHEL7 OpenShift image, you must execute 
$ oc -n openshift import-image \
  jboss-webserver54-openjdk11-tomcat9-openshift-rhel7:1.0
Copy to Clipboard Toggle word wrap
  • In order to update the core JWS 5.4 tomcat 9 OpenJDK11 RHEL8 OpenShift image, you must execute 
$ oc -n openshift import-image \
  jboss-webserver54-openjdk11-tomcat9-openshift-ubi8:1.0
Copy to Clipboard Toggle word wrap
Note

The 1.0 tag at the end of each image you import refers to the stream version that is set in the image stream.

To run and configure the JWS for OpenShift images, use the OpenShift S2I process with the application template parameters and environment variables.

The S2I process for the JWS for OpenShift images works as follows:

  • If there is a Maven settings.xml file in the configuration/ source directory, it is moved to $HOME/.m2/ of the new image.

    See the Apache Maven Project website for more information on Maven and the Maven settings.xml file.

  • If there is a pom.xml file in the source repository, a Maven build is triggered using the contents of the $MAVEN_ARGS environment variable.

    By default, the package goal is used with the openshift profile, including the arguments for skipping tests (-DskipTests) and enabling the Red Hat GA repository (-Dcom.redhat.xpaas.repo.redhatga).

  • The results of a successful Maven build are copied to /opt/webserver/webapps/. This includes all WAR files from the source directory specified by the $ARTIFACT_DIR environment variable. The default value of $ARTIFACT_DIR is the target/ directory.

    Use the MAVEN_ARGS_APPEND environment variable to modify the Maven arguments.

  • All WAR files from the deployments/ source directory are copied to /opt/webserver/webapps/.
  • All files in the configuration/ source directory are copied to /opt/webserver/conf/ (excluding the Maven settings.xml file).

  • All files in the lib/ source directory are copied to /opt/webserver/lib/.

    Note

    If you want to use custom Tomcat configuration files, the file names should be the same as for a normal Tomcat installation. For example, context.xml and server.xml.

See the Artifact Repository Mirrors section for guidance on configuring the S2I process to use a custom Maven artifacts repository mirror.

Existing applications are deployed on OpenShift using the oc start-build command.

Prerequisite: An existing .war, .ear, or .jar of the application to deploy on JWS for OpenShift.

  1. Prepare the directory structure on the local file system.

    Create a source directory containing any content required by your application not included in the binary (if required, see Using the JWS for OpenShift Source-to-Image (S2I) process), then create a subdirectory deployments/: 

    $ mkdir -p <build_dir>/deployments
    Copy to Clipboard Toggle word wrap

  2. Copy the binaries (.war,.ear,.jar) to deployments/: 

    $ cp /path/to/binary/<filenames_with_extensions> <build_dir>/deployments/
    Copy to Clipboard Toggle word wrap
    Note

    Application archives in the deployments/ subdirectory of the source directory are copied to the $JWS_HOME/tomcat/webapps/ directory of the image being built on OpenShift. For the application to deploy, the directory hierarchy containing the web application data must be structured correctly (see Section 3.4, “Using the JWS for OpenShift Source-to-Image (S2I) process”).

  3. Log in to the OpenShift instance: 

    $ oc login <url>
    Copy to Clipboard Toggle word wrap

  4. Create a new project if required: 

    $ oc new-project <project-name>
    Copy to Clipboard Toggle word wrap

  5. Identify the JWS for OpenShift image stream to use for your application with oc get is -n openshift: 

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

jboss-webserver50-tomcat9-openshift
    Copy to Clipboard Toggle word wrap
    Note

    The option -n openshift specifies the project to use. oc get is -n openshift retrieves (get) the image stream resources (is) from the openshift project.

  6. Create the new build configuration, specifying image stream and application name: 

    $ oc new-build --binary=true \
 --image-stream=jboss-webserver<version>-openjdk8-tomcat9-openshift-rhel7:latest \
--name=<my-jws-on-openshift-app>
    Copy to Clipboard Toggle word wrap

  7. Instruct OpenShift to use the source directory created above for binary input of the OpenShift image build: 

    $ oc start-build <my-jws-on-openshift-app> --from-dir=./<build_dir> --follow
    Copy to Clipboard Toggle word wrap

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

    $ oc new-app <my-jws-on-openshift-app>
    Copy to Clipboard Toggle word wrap

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

    # to check the name of the service to expose
$ oc get svc -o name

service/<my-jws-on-openshift-app>

# to expose the service
$ oc expose svc/my-jws-on-openshift-app

route "my-jws-on-openshift-app" exposed
    Copy to Clipboard Toggle word wrap

  10. Retrieve the address of the exposed route: 

    oc get routes --no-headers -o custom-columns='host:spec.host' my-jws-on-openshift-app
    Copy to Clipboard Toggle word wrap
  11. To access the application in your browser: http://<address_of_exposed_route> / <my-war-ear-jar-filename-without-extension>

The example below uses the tomcat-websocket-chat quickstart using the procedure from Section 3.4.1, “Create a JWS for OpenShift application using existing maven binaries”.

3.4.2.1. Prerequisites:
Copy link

  1. Get the WAR application archive or build the application locally.

    • Clone the source code: 

      $ git clone https://github.com/jboss-openshift/openshift-quickstarts.git
      Copy to Clipboard Toggle word wrap

    • Configure the Red Hat JBoss Middleware Maven Repository

    • Build the application: 

      $ cd openshift-quickstarts/tomcat-websocket-chat/
      Copy to Clipboard Toggle word wrap 
      $ mvn clean package

[INFO] Scanning for projects...
[INFO]
[INFO] ------------------------------------------------------------------------
[INFO] Building Tomcat websocket example 1.2.0.Final
[INFO] ------------------------------------------------------------------------
...
[INFO] ------------------------------------------------------------------------
[INFO] BUILD SUCCESS
[INFO] ------------------------------------------------------------------------
[INFO] Total time: 01:28 min
[INFO] Finished at: 2018-01-16T15:59:16+10:00
[INFO] Final Memory: 19M/271M
[INFO] ------------------------------------------------------------------------
      Copy to Clipboard Toggle word wrap

  1. Prepare the directory structure on the local file system.

    Create the source directory for the binary build on your local file system and the deployments/ subdirectory. Copy the WAR archive to deployments/: 

    [tomcat-websocket-chat]$ ls

pom.xml  README.md  src/  target/
    Copy to Clipboard Toggle word wrap 
    $ mkdir -p ocp/deployments
    Copy to Clipboard Toggle word wrap 
    $ cp target/websocket-chat.war ocp/deployments/
    Copy to Clipboard Toggle word wrap

  1. Log in to the OpenShift instance: 

    $ oc login <url>
    Copy to Clipboard Toggle word wrap

  2. Create a new project if required: 

    $ oc new-project jws-bin-demo
    Copy to Clipboard Toggle word wrap

  3. Identify the JWS for OpenShift image stream to use for your application with oc get is -n openshift: 

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

jboss-webserver50-tomcat9-openshift
    Copy to Clipboard Toggle word wrap

  4. Create new build configuration, specifying image stream and application name: 

    $ oc new-build --binary=true \
 --image-stream=jboss-webserver<version>-openjdk8-tomcat9-openshift-rhel7:latest\
 --name=jws-wsch-app

--> Found image 8c3b85b (4 weeks old) in image stream "openshift/jboss-webserver<version>-tomcat9-openshift" under tag "latest" for "jboss-webserver<version>"

    JBoss Web Server 5.0
    --------------------
    Platform for building and running web applications on JBoss Web Server 5.0 - 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
    Copy to Clipboard Toggle word wrap

  5. Start the binary build. Instruct OpenShift to use source directory for the binary input for the OpenShift image build: 

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

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.4/tomcat/webapps` for later deployment...
'/home/jboss/source/deployments/websocket-chat.war' -> '/opt/jws-5.4/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
    Copy to Clipboard Toggle word wrap

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

    $ oc new-app jws-wsch-app

--> 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.0
    --------------------
    Platform for building and running web applications on JBoss Web Server 5.0 - 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.
    Copy to Clipboard Toggle word wrap

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

    # to check the name of the service to expose
$ oc get svc -o name

service/jws-wsch-app

# to expose the service
$ oc expose svc/jws-wsch-app

route "jws-wsch-app" exposed
    Copy to Clipboard Toggle word wrap

  8. Retrieve the address of the exposed route: 

    oc get routes --no-headers -o custom-columns='host:spec.host' jws-wsch-app
    Copy to Clipboard Toggle word wrap
  9. Access the application in your browser: http://<address_of_exposed_route>/websocket-chat

For detailed instructions on creating new OpenShift applications from source code, see OpenShift.com - Creating an application from source code.

Note

Before proceeding, ensure that the applications' data is structured correctly (see Section 3.4, “Using the JWS for OpenShift Source-to-Image (S2I) process”).

  1. Log in to the OpenShift instance: 

    $ oc login <url>
    Copy to Clipboard Toggle word wrap

  2. Create a new project if required: 

    $ oc new-project <project-name>
    Copy to Clipboard Toggle word wrap

  3. Identify the JWS for OpenShift image stream to use for your application with oc get is -n openshift: 

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

jboss-webserver50-tomcat9-openshift
    Copy to Clipboard Toggle word wrap

  4. Create the new OpenShift application from source code using Red Hat JBoss Web Server for OpenShift images, use the --image-stream option: 

    $ oc new-app \
 <source_code_location>\
 --image-stream=jboss-webserver<version>-openjdk8-tomcat9-openshift-rhel7\
 --name=<openshift_application_name>
    Copy to Clipboard Toggle word wrap

    For Example: 

    $ oc new-app \
 https://github.com/jboss-openshift/openshift-quickstarts.git#master \
 --image-stream=jboss-webserver<version>-openjdk8-tomcat9-openshift-rhel7\
 --context-dir='tomcat-websocket-chat' \
 --name=jws-wsch-app
    Copy to Clipboard Toggle word wrap

    The source code is added to the image and the source code is compiled. The build configuration and services are also created.

  5. To expose the application: 

    # to check the name of the service to expose
$ oc get svc -o name

service/<openshift_application_name>

# to expose the service
$ oc expose svc/<openshift_application_name>

route "<openshift_application_name>" exposed
    Copy to Clipboard Toggle word wrap

  6. To retrieve the address of the exposed route: 

    oc get routes --no-headers -o custom-columns='host:spec.host' <openshift_application_name>
    Copy to Clipboard Toggle word wrap
  7. To access the application in your browser: http://<address_of_exposed_route>/<java_application_name>

Additional jar files can be added to tomcat/lib/ directory using docker.

For adding jar files in tomcat/lib/

  1. Get the image started in docker 

    docker run --network host -i -t -p 8080:8080 ImageURL
    Copy to Clipboard Toggle word wrap

  2. Find the CONTAINER ID 

     docker ps | grep <ImageName>
    Copy to Clipboard Toggle word wrap

  3. Copy the library to tomcat/lib/ directory 

    docker cp <yourLibrary> <CONTAINER ID>:/opt/jws-5.4/tomcat/lib/
    Copy to Clipboard Toggle word wrap

  4. Commit the changes to a new image 

    docker commit <CONTAINER ID> <NEW IMAGE NAME>
    Copy to Clipboard Toggle word wrap

  5. Create a new image tag 

    docker tag <NEW IMAGE NAME>:latest <NEW IMAGE REGISTRY URL>:<TAG>
    Copy to Clipboard Toggle word wrap

  6. Push the image to a registry 

    docker push <NEW IMAGE REGISTRY URL>
    Copy to Clipboard Toggle word wrap
Red Hat logoGithubredditYoutubeTwitter

Learn

Try, buy, & sell

Communities

About Red Hat Documentation

We help Red Hat users innovate and achieve their goals with our products and services with content they can trust. Explore our recent updates.

Making open source more inclusive

Red Hat is committed to replacing problematic language in our code, documentation, and web properties. For more details, see the Red Hat Blog.

About Red Hat

We deliver hardened solutions that make it easier for enterprises to work across platforms and environments, from the core datacenter to the network edge.

Theme

© 2026 Red HatBack to top