Please note that these documents apply to OpenShift Online v2 only (accounts created before August 1st, 2016).
If you are using one of the OpenShift 3 products, please refer to documents available at

Getting Started with Tomcat 6/7 (EWS 1.0/2.0)

It’s easy to get up and running with Tomcat on OpenShift and the experience will be very similar to the experience of running it on any Linux system. OpenShift supports both source and WAR file deploys and modification of server.xml. One important caveat - applications will not have write permissions to the webapps directory, so you will have to write content to another directory.

OpenShift uses JBoss EWS 1.0 and 2.0 for Tomcat 6 and 7 respectively. EWS is a hardened and Red Hat supported version of Apache Tomcat. Both versions use Java OpenJDK 1.7.

EWS has had the clustering modules removed so you can not do Tomcat clustering with EWS.

Step 1: Create a Tomcat Application

This tutorial walks through the creation of an application titled mytomcatapp under the domain mydomain. Before going through the rest of the tutorial, make sure to have created an OpenShift account and installed the RHC command line tools.

Once that is completed, open a terminal on a local machine and change into a directory where the source code will be located. Then at the command prompt enter the following command to create a Tomcat application:

$ rhc app-create mytomcatapp tomcat7


$ rhc app-create mytomcatapp tomcat6

The output will look something like this:

Using jbossews-2.0 (Tomcat 7 (JBoss EWS 2.0)) for 'tomcat7'

Application Options
Domain:     mydomain
Cartridges: jbossews-2.0
Gear Size:  default
Scaling:    no

Creating application 'mytomcatapp' ... done

Waiting for your DNS name to be available ... done

Cloning into 'mytomcatapp'...
Warning: Permanently added ',' (RSA) to the list of known hosts.

Your application 'mytomcatapp' is now available.

  URL: (1)
  SSH to:
  Git remote: ssh://
  Cloned to:  /home/me/git_demo/mytomcatapp (2)

Run 'rhc show-app mytomcatapp' for more details about your app.
1 Public URL of application
2 Location of local Git repository

The application will now be running and accessible at the URL (1) listed in the output. A local git repository for your application was also created in the directory listed under Cloned to (2).

Step 2: Make the First Change

A developer on OpenShift can make code changes on a local machine, check those changes in locally, and then push those changes to OpenShift. One of the primary advantages of Git is that it does not require a continuous online presence in order to run. A developer can easily check in (in Git terminology, commit) and revert changes locally before deciding to upload those changes to OpenShift.

Using the Git Repository

To make the first change, edit index.html in the mytomcatapp/src/main/webapp directory of the local Git repository. Go to the file in the terminal and edit with a command line editor like VIM or EMacs. Alternatively, edit the file using any text editor or IDE. Strip out everything between the two <body> tags and change the content to look like this:

        <h1>Hello world!</h1>

Now that you have made this incredibly complicated code change, the code must be deployed to the server. Accomplish this task using Git.

  1. To add the change to the Git repository’s index and stage it for the next commit, use the command git add:

    $ git add --all .
  2. Next commit the staged changes to the Git repository, with a log message to explain the changes:

    $ git commit -m "Your commit message"
  3. Finally, push these changes to the remote OpenShift application.

    $ git push

The output of the push command will first show the git push and then the build process and deployment for the OpenShift application. When the build is finished, go back to the application’s URL ( and see a page which just says "Hello World" in nice big font.

This is the basic process to follow when developing an application: git add, git commit, and finally git push.

If you are curious about Git or would like to learn more, the Pro Git book is a great resource.

Step 3: Deploying WAR files

OpenShift also supports WAR files deployment. There are several processes which are each very simple. Please visit the deployment options page for more information.

Other Tips


Most of the behavior of Tomcat can be controlled through the server.xml file. In OpenShift you can find server.xml inside your application’s Git repository.

server.xml can be found in the {git repo}/.openshift/config/ directory. Please be careful when making a change to the file. Also, make sure the Tomcat server restarts after making the change.

Hot Deploy and Other Markers

With a normal git push as outlined above, Openshift starts and stops the Tomcat server on each build. For Java applications, a WAR file can be built and deployed without restarting the server. See Hot Deployment for more information on how OpenShift uses a marker in the git repository to turn on this build style.

Other Markers

Adding marker files to .openshift/markers will have the following effects:

Marker Effect


Will enable the JPDA socket based transport on the java virtual machine running the Tomcat server. This enables you to remotely debug code running inside Tomcat.


Maven build step will be skipped


Will start the build process by removing all non-essential Maven dependencies. Any current dependencies specified in your pom.xml file will then be re-downloaded.


Will run Tomcat with Java7 if present. If no marker is present then the baseline Java version will be used (currently Java6)

Adding a Database to an Appliction

Find out how to add a database to your application by going to the Adding a Database guide.

You should only use environment variables to specify the connection parameters for your database. Using hard coded names, ports, or credentials limits the resusability of your app and can potentially break your app during OpenShift maintenance.

By default MySQL, Postgresql, and MongoDB have JNDI entries in your server.xml. As noted above, you can edit your server.xml, which allows you to delete or add other JNDI sources to your application. The syntax is standard syntax, there are no modifications needed for OpenShift, other than using the proper Environment Variables for the DB.

Configuring JVM properties

Environment variables can also be used to configure JVM properties. By setting the JAVA_OPTS_EXT environment variable, extra JAVA_OPTS can be added before the JVM is invoked. Here is an example setting the setting other garbage collection properties.

$ rhc env-set JAVA_OPTS_EXT="-XX:+PrintGCDetails  -Xloggc:$OPENSHIFT_LOG_DIR/gc.log" --app mytomcatapp

Please note that the startup parameters already set for Tomcat cannot be overwritten or changed. The parameters can be viewed via SSH’ing into your application gear using the following command:

$ ps axwwww | grep java

Next Steps

The best next step is to create an application using OpenShift.

Look at the application gallery and developer spotlight to see what other developers have created on OpenShift.

Browse our quickstarts and community cartridges to see other exciting technology you can use in your applications.

Finally, if at any point you have questions or issues, please visit the Help Center for a full list of options.