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

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

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= -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
    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
    Using default tag: latest
    Trying to pull repository ...
    latest: Pulling from
    1f1202c893ce: Pull complete
    32be9843afa0: Pull complete
    c927648f9ad0: Pull complete
    8ac7bcea2a65: Pull complete
    Digest: sha256:bd637c88fdc94cd4e4476e00af1baeb3c1f3a6d9a873a73bee646950cdf076fc
    Status: Downloaded newer image for

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 "".
  2. Go to your new tomcat project:
    sh-4.2# oc project tomcat
    Already on project "tomcat" on server "".

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
  2. Verify that the application was deployed and the pod was created:
    sh-4.2# oc get pods
    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
    os-sample-java-web ClusterIP x.x.x.x <none> 8080/TCP,8443/TCP,8778/TCP 1m
  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 oc expose svc os-sample-java-web exposedsh-4.2# oc get route
    os-sample-java-web os-sample-java-web 8080-tcp None
  5. Using the route that you have just discovered, confirm that you can access application:

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:

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

  1. Copy the 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/
    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
  2. Back up the main file:
    cp -pr secure-mgmt-console.sh_ORIG
  3. Make the following changes in the new 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_ORIG
    < 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
    < <!-- <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" />
    < <!-- <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 and context.xml, respectively:
    sh-4.2# oc create configmap mgmtsecure
    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/ 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 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 updated
    sh-4.2# oc set env dc/os-sample-java-web --overwrite JWS_ADMIN_PASSWORD=jwsadmin update
    sh-4.2# oc set env dc/os-sample-java-web --overwrite SCRIPT_DEBUG=true 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.


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.