Install Apache Tomcat and deploy a Java web application on Red Hat OpenShift

July 1, 2020
Pandurang Memane
Related topics:
ContainersJavaKubernetes
Related products:
Red Hat JBoss Web Server

If you are new to OpenShift, then you might want to install Apache Tomcat on top of it for simpler experimentation. This article guides you through installing Apache Tomcat from a Docker image and then using it to deploy a Java web app on Red Hat OpenShift. I also show you how to access the Tomcat management console on OpenShift.

To follow the examples, you must have an OpenShift account. We will use the OpenShift command-line interface (CLI) for this demonstration, so be sure to install the CLI (oc) before you begin.

A note about the sample application: You will need a Java web application to use for the deployment example. I am using the Sample Java Web Application from the OpenShift Demos GitHub repository. It is a simple application that is useful for understanding basic concepts. You may use the provided sample or choose your own application to work with.

About the Tomcat management console

The Tomcat Manager is for deploying a new web application (or undeploying an existing one) without having to shut down and restart the entire container. In addition, the Tomcat Manager lets you request that an existing application reload itself, even if you have not declared it to be reloadable in the Tomcat server configuration file.

This manager consists of a web application (installed by default on the context path /manager) that supports the following functions:

  • Deploy a new web application from the uploaded contents of a WAR file.
  • Deploy a new web application, on a specified context path, from the server file system.
  • List the currently deployed web applications, as well as the sessions that are currently active for those web applications.
  • Reload an existing web application, to reflect changes in the contents of /WEB-INF/classes or /WEB-INF/lib.
  • List the OS and JVM property values.
  • List the available global JNDI resources, for use in deployment tools that prepare <ResourceLink> elements nested in a <Context> deployment description.
  • Start a stopped application (thus making it available again).
  • Stop an existing application (so that it becomes unavailable), but do not undeploy it.
  • Undeploy a deployed web application and delete its document base directory (unless it was deployed from the file system).

Step 1: Install Tomcat on OpenShift

To start, let's install Apache Tomcat 9 from a Docker image. As previously mentioned, we'll use the OpenShift command-line tool, oc, for our installation:

  1. From the command line, log in to your OpenShift console: 
    $ oc login --server=https://openshift.testcluster.lab.redhat.com -u user -p password
  2. Enter your Red Hat registry service account username and password: 
    sh-4.2# sudo sh -

sh-4.2# docker login

Username: {REGISTRY-SERVICE-ACCOUNT-USERNAME}

Password: {REGISTRY-SERVICE-ACCOUNT-PASSWORD}

Login Succeeded
  3. Here is the command to pull the Docker image from the Red Hat container registry, followed by status output: 
    sh-4.2# docker pull registry.redhat.io/jboss-webserver-5/webserver53-openjdk8-tomcat9-openshift-rhel7

Using default tag: latest

Trying to pull repository registry.redhat.io/jboss-webserver-5/webserver53-openjdk8-tomcat9-openshift-rhel7 ...

latest: Pulling from registry.redhat.io/jboss-webserver-5/webserver53-openjdk8-tomcat9-openshift-rhel7

1f1202c893ce: Pull complete

32be9843afa0: Pull complete

c927648f9ad0: Pull complete

8ac7bcea2a65: Pull complete

Digest: sha256:bd637c88fdc94cd4e4476e00af1baeb3c1f3a6d9a873a73bee646950cdf076fc

Status: Downloaded newer image for registry.redhat.io/jboss-webserver-5/webserver53-openjdk8-tomcat9-openshift-rhel7:latest

Step 2: Create a new project

Next, we'll create a new project to deploy the web application using Tomcat.

  1. Enter the following to create a new project: 
    sh-4.2# oc new-project tomcat

Now using project "tomcat" on server "https://openshift.testcluster.lab.redhat.com:443".
  2. Go to your new tomcat project: 
    sh-4.2# oc project tomcat

Already on project "tomcat" on server "https://openshift.testcluster.lab.redhat.com:443".

Step 3: Create the Java web application

Now, we create a Java web application.

  1. Create a new-app using the sample application that you chose (mine is os-sample-java-web): 
    $ oc new-app registry.redhat.io/jboss-webserver-5/webserver53-openjdk8-tomcat9-openshift-rhel7~https://github.com/openshiftdemos/os-sample-java-web.git
  2. Verify that the application was deployed and the pod was created: 
    sh-4.2# oc get pods

NAME READY STATUS RESTARTS AGE

os-sample-java-web-1-build 0/1 Completed 0 2m

os-sample-java-web-1-k5sqz 1/1 Running 0 1m
  3. Verify that the cluster service was created: 
    sh-4.2# oc get svc

NAME TYPE CLUSTER-IP EXTERNAL-IP PORT(S) AGE

os-sample-java-web ClusterIP x.x.x.x <none> 8080/TCP,8443/TCP,8778/TCP 1m

sh-4.2#
  4. Verify whether or not the route was created. If the route is not present (as shown below), then run the following command to expose the service: 
    sh-4.2# oc get route

No resources found.sh-4.2# oc expose svc os-sample-java-web

route.route.openshift.io/os-sample-java-web exposedsh-4.2# oc get route

NAME HOST/PORT PATH SERVICES PORT TERMINATION WILDCARD

os-sample-java-web os-sample-java-web-tomcat.openshift.testcluster.lab.redhat.com os-sample-java-web 8080-tcp None
  5. Using the route that you have just discovered, confirm that you can access application: 
    os-sample-java-web-tomcat.openshift.testcluster.lab.redhat.com

Step 4: Access the Tomcat Manager on OpenShift

For security purposes, you can only access the Tomcat Manager on localhost. If you tried entering the following, for example, you would receive a "403 forbidden" error:

os-sample-java-web-tomcat.openshift.testcluster.lab.redhat.com/manager

Here is the command-line procedure to access the management console for Tomcat:

  1. Copy the secure-mgmt-console.sh and context.xml file from your pods to your master machine: 
    sh-4.2# oc cp os-sample-java-web-1-k5sqz:/opt/jws-5.3/tomcat/bin/launch/secure-mgmt-console.sh secure-mgmt-console.sh

sh-4.2# oc cp os-sample-java-web-1-k5sqz:/opt/jws-5.3/tomcat/webapps/manager/META-INF/context.xml context.xml

sh-4.2# ls

ansible.cfg context.xml hosts htpasswd log openshift-ansible secure-mgmt-console.sh
  2. Back up the main secure-mgmt-console.sh file: 
    cp -pr secure-mgmt-console.sh secure-mgmt-console.sh_ORIG
  3. Make the following changes in the new secure-mgmt-console.sh file (note that users with the manager-gui role should not be granted the manager-script or manager-jmx role): 
    sh-4.2# diff secure-mgmt-console.sh secure-mgmt-console.sh_ORIG

13c13

< sed -i -e"s|</tomcat-users>|\n<role rolename=\"manager-gui\"/>\n<user username=\"${JWS_ADMIN_USERNAME}\" password=\"${JWS_ADMIN_PASSWORD}\" roles=\"manager-gui\"/>\n</tomcat-users>|" $JWS_HOME/conf/tomcat-users.xml

---

> sed -i -e"s|</tomcat-users>|\n<user username=\"${JWS_ADMIN_USERNAME}\" password=\"${JWS_ADMIN_PASSWORD}\" roles=\"manager-jmx,manager-script\"/>\n</tomcat-users>|" $JWS_HOME/conf/tomcat-users.xml
  4. Now, back up the main context.xml file: 
    sh-4.2# cp -pr context.xml context.xml_ORIG

sh-4.2# diff context.xml context.xml_ORIG

19,20c19,20

< <!-- <Valve className="org.apache.catalina.valves.RemoteAddrValve"

< allow="127\.\d+\.\d+\.\d+|::1|0:0:0:0:0:0:0:1" /> -->

---

> <Valve className="org.apache.catalina.valves.RemoteAddrValve"

> allow="127\.\d+\.\d+\.\d+|::1|0:0:0:0:0:0:0:1" />

23c23

< <!-- <Valve className="org.apache.catalina.valves.RemoteAddrValve" allow="127\.\d+\.\d+\.\d+|::1|0:0:0:0:0:0:0:1"/> -->

    > <Valve className="org.apache.catalina.valves.RemoteAddrValve" allow="127\.\d+\.\d+\.\d+|::1|0:0:0:0:0:0:0:1"/>
  5. Create config maps for secure-mgmt-console.sh and context.xml, respectively: 
    sh-4.2# oc create configmap mgmtsecure --from-file=secure-mgmt-console.sh

configmap/mgmtsecure created

sh-4.2# oc create configmap mgmtcontext --from-file=context.xml

configmap/mgmtcontext created
  6. Set the volume for the mgmtsecure and mgmtcontext config maps: 
    sh-4.2# oc set volume dc/os-sample-java-web --add --name=mgmtsecure --configmap-name=mgmtsecure --default-mode=0777 --mount-path=/opt/jws-5.3/tomcat/bin/launch/secure-mgmt-console.sh --sub-path=secure-mgmt-console.sh

deploymentconfig.apps.openshift.io/os-sample-java-web volume updated

sh-4.2# oc set volume dc/os-sample-java-web --add --name=mgmtcontext --configmap-name=mgmtcontext --default-mode=0777 --mount-path=/opt/jws-5.3/tomcat/webapps/manager/META-INF/context.xml --sub-path=context.xml

deploymentconfig.apps.openshift.io/os-sample-java-web volume updated
  7. Overwrite JWS_ADMIN_USERNAME and JWS_ADMIN_PASSWORD as shown: 
    sh-4.2# oc set env dc/os-sample-java-web --overwrite JWS_ADMIN_USERNAME=jwsadmin

deploymentconfig.apps.openshift.io/os-sample-java-web updated

sh-4.2# oc set env dc/os-sample-java-web --overwrite JWS_ADMIN_PASSWORD=jwsadmin

deploymentconfig.apps.openshift.io/os-sample-java-web update

sh-4.2# oc set env dc/os-sample-java-web --overwrite SCRIPT_DEBUG=true

deploymentconfig.apps.openshift.io/os-sample-java-web updated
  8. Verify that the application was deployed and the pod was created with your changes: 
    os-sample-java-web-2-build 0/1 Completed 0 27m

os-sample-java-web-7-rghgk 1/1 Running 0 26m

Open the Tomcat Manager

The last step is to open the /manager page. It will pop up a login console. Enter your user ID (jwsadmin) and password (jwsadmin) to access the Tomcat Manager in the OpenShift console.

Open the Tomcat manager

Conclusion

You now know how to install Tomcat on OpenShift, use Tomcat to deploy a web application to OpenShift, and access the Tomcat /manager page. I hope this tutorial helps you get started with your OpenShift explorations.

Last updated: January 12, 2024