If you are a Java developer, you have probably struggled with finding a reliable host for your Tomcat based java projects that doesn’t break the bank. The OpenShift Platform-as-a-Service
is changing the Java hosting game by not only making it easy to deploy Java apps to the cloud, but also making it FREE to get started.
By default, OpenShift offers excellent support for the JBoss application server as well as Jenkins continuous
integration. Not only that, OpenShift uses Apache Maven as the default build system to allow you to push your code via git,
and watch the build happen on a remote cloud server.
What happens if you want to just use Tomcat for your Java app? In this blog post I will detail how to install and configure the Tomcat servlet container for deployment on the OpenShift PaaS.
Don’t want to read this article, or maybe you want to follow along? Check out the video where
I run through these steps.
Step 1: Create an OpenShift account
If you don’t already have an OpenShift account, head on over to the website and signup with promo code TOMCAT. It is completely free and Red
Hat gives every user three free Gears on which to run your applications. At the time of this writing, the combined resources allocated for each user is 1.5 GB of memory and 3 GB of disk space.
Step 2: Install the RHC client tools
Note: If you would rather watch a screencast of this step, check out the following videos where I demo how to install the client tools.
The OpenShift client tools are written in a very popular programming language called Ruby. With OSX 10.6 or later and most Linux distributions, ruby is installed by
default so installing the client tools is a snap. Simply issue the following command on your terminal application:
$ sudo gem install rhc
Step 3: Create an OpenShift application
Since Tomcat is not an officially support application type on OpenShift, we need to create a DIY application. What's the DIY application type? Click here to
learn more. The command to do this is:
$ rhc app create –a tomcat –t diy-0.1
This will create an application named tomcat, as well as, let OpenShift know that we plan to install your own web server. Luckily, Java is already installed and configured for the DIY application type so we only need to install and configure
the application server.
Step 4: Disable the test Ruby server
The DIY application comes with a Ruby server as an example of how to use the application type. In order for us to use Tomcat, we need to disable this service.
$ cd tomcat/.openshift/action_hooks
In this directory, there are several scripts that are executed when you push new code up to your server. Before we remove the start and stop scripts, lets ensure that we stop the currently running Ruby server.
$ rhc app stop –a tomcat
Now lets remove the start and stop scripts and replace them with blank files.
$ rm start
$ rm stop
$ touch start
$ touch stop
Once we have removed these files and replaced them with empty files, we need to commit and push our changes to our OpenShift application.
$ git commit –a –m “Replaced start and stop scripts”
$ git push
Step 5: SSH into the machine and install Tomcat
OpenShift allows users to SSH into their machine via key based authentication. In order to find your username, simply run the following command:
$ rhc domain show
This will display information about all of your currently running applications. One of the fields provided is the Git URL of your application that should look similar to this:
ssh://df4c84505552469c9e163263a01fc00d@tomcat-onpaas.rhcloud.com/~/git/tomcat.git/
In this example, my username is df4c84505552469c9e163263a01fc00d and my host name is tomcat-onpaas.rhcloud.com. At this point we can SSH into the server.
$ ssh df4c84505552469c9e163263a01fc00d@tomcat-onpaas.rhcloud.com
Step 6: Download and extract the Tomcat server
Once you are logged into the machine, simple change to the application data directory, download tomcat, and extract the contents.
$ cd tomcat/data
$ wget http://www.us.apache.org/dist/tomcat/tomcat-7/v7.0.29/bin/apache-tomcat-7.0.29.tar.gz
$ tar zxf apache-tomcat-7.0.29.tar.gz
$ rm apache-tomcat-7.0.29.tar.gz
$ cd apache-tomcat-7.0.29/conf
Now that we tomcat downloaded and extracted, we need to modify the server.xml file to specify the ports we want to use as well as the ip address to bind to. Because OpenShift is a multitenant environment, you will need to use the internal ip address that is
provided to you. In order to find this address, run the following command:
$ env |grep INTERNAL_IP
Which should return something similar to this:
OPENSHIFT_INTERNAL_IP=127.6.99.1
We need to modify the server.xml file to respect this ip address as well as change the default ports that some of the services run on.
Old Connector:
<Connector port="8080" protocol="HTTP/1.1"
connectionTimeout="20000"
redirectPort="8443" />
New Connector:
<Connector port="8080" protocol="HTTP/1.1"
connectionTimeout="20000"
address="127.6.99.1”
redirectPort="15443" />
Notice that we added an address tag to this connector.
We now need to change the following line for the Catalina Engine:
<Engine name="Catalina" defaultHost="localhost">
to
<Engine name="Catalina" defaultHost="127.6.99.1">
We also need to modify the host name section to point to our OpenShift host.
<Host name="localhost" appBase="webapps"
unpackWARs="true" autoDeploy="true">
to
<Host name="tomcat-yourdomain.rhcloud.com" appBase="webapps"
unpackWARs="true" autoDeploy="true">
The ports that are configured for others services will not work by default because OpenShift does not allow users to bind to any port below 15000 other than 8080. Because of this, we need to change the following configuration items:
<Server port="8005" shutdown="SHUTDOWN">
to
<Server port="15005" shutdown="SHUTDOWN" address="127.6.99.1”>
<Connector port="8009" protocol="AJP/1.3" redirectPort="8443" />
to
<Connector port="15009" protocol="AJP/1.3" redirectPort="8443" address="127.6.99.1”/>
Step 7: Start the Tomcat servlet container
$ cd ../bin
$ sh startup.sh && tail -f ../logs/*
This should start Tomcat as well as make it accessible to the outside world via port 80. You are probably asking yourself how it’s available on port 80 when we specifically set it to use 8080. OpenShift actually has a proxy setup that will pass all traffic
coming to your host via port 80 to a local server you have running on port 8080. This port is specified in the system environment variable OPENSHIFT_INTERNAL_PORT.
Verify that your tomcat server is running by pointing your browser to your application at tomcat-yourNamespace.rhcloud.com
If you want to use the Tomcat management console, add a user to the tomcat-users.xml file located in the conf directory. For example add the following role and user to that file deleting what is already there:
<role rolename="manager-gui"/>
<user username="tomcat" password="openshift" roles="manager-gui"/>
A Call to Action
Are you a Tomcat user and want to make it easier for others to use this servlet container on OpenShift? We would love to see someone create a GitHub quickstart application that has a preconfigured Tomcat ready to go. Follow the guide I
created that explains how to create this. One thing to watch out for is the IP address that we added to the server.xml file. In the quickstart, you will need to write a script that replaces this value with the users IP address as reported by the OPENSHIFT_INTERNAL_IP
environment variable. Once you get this created, shoot us an email at openshift@redhat.comand we will send a box of OpenShift goodies your way.
Challenge accepted! and nailed it: https://github.com/openshift/openshift-tomcat-quickstart
This quickstart makes it super fast and easy to run Tomcat on OpenShift. It's also in the git repo so deploying your war file is as easy as adding it to webapps/ and running git add/commit/push. Thanks @lilu