Getting Started with JBoss AS 7 on OpenShift

It’s easy to get up and running with JBoss AS 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 standalone.xml. One important caveat - applications will not have write permissions to the {AS Home}/standalone/deployments directory, so you will have to write content to another directory. Finally, given the usual memory requirements of Java applications, it is recommended to use a Large or Medium gear size.

Step 1: Create a JBoss AS) Application

This tutorial walks through the creation of an application titled myjbossasapp 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. At the command prompt enter the following command to create a JBoss AS application:

$ rhc app-create myasapp jbossas

The output will look something like this:

$ rhc app create myjbossasapp jbossas
Using jbossas-7 (JBoss Application Server 7) for 'jbossas'

Application Options
Domain:     osexample
Cartridges: jbossas-7
Gear Size:  default
Scaling:    no

Creating application 'myjbossasapp' ... done

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

Cloning into 'myjbossasapp'...

Your application 'myjbossasapp' is now available.

  URL: (1)
  SSH to:
  Git remote: ssh://
  Cloned to:  /Users/<user>/Desktop/myjbossasapp (2)

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

The application is now 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

You 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. You 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 myjbossasapp/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 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 the deployment of WAR files. There are several processes which are each very simple. Please visit the deployment options page to learn more about deploying WAR files on OpenShift Online.

Other Tips

standalone.xml and Modules

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

standalone.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 EAP server restarts after making the change. You will also find a directory titled modules in the same directory. If you are using Jboss Modules to load classes outside of the server or application provided classes - for example custom drivers for a JDBC/JNDI connection - you would place them in this location.

To learn more about the standalone.xml file and the Modules directory, please refere to the Official Documentation.

Hot Deploy and Other Markers

With a normal git push as outlined above, Openshift starts and stops the EAP server on each build. For Java applications, a WAR/EAR 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

In addition to the hot_deploy marker, the other markers probably of most use are enable_jpda, which turns on the jpda transport for debugging and force_clean_build which forces Maven to re-download all the dependencies for the application. The markers for JBoss AS can be found here.

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 and Postgresql have JNDI entries in your standalone.xml. As noted above, you can edit your standalone.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 myjbossasapp

Please note that the startup parameters already set for JBoss AS cannot be overwritten or changed. The parameters can be viewed by SSH’ing into your application gear and executing 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.