Deploying a Java EE application on OpenShift Express with AS7 support

  • Save

During the past few years, I’ve been hearing about “cloud” services more and more. Initially I wasn’t really curious to try them out. But a few months (a year?) back, I decided to see what it was all about. I have been involved with Java EE development for more than 7 years now, so I decided to see what it takes to deploy my Java EE application to the cloud. I set out looking for documentation and other usual blog articles and such. At that point, whichever cloud services I thought of trying out, would require me to provide my credit card details even to try out a trial application. I wasn’t too keen to provide my credit card details just to try out a few applications of mine. So I kind of gave up on trying out my applications on cloud, although I kept reading about what other developers were doing to deploy their applications on cloud.

Enter OpenShift

But this month, the OpenShift announcement about being able to deploy your JBoss AS7 Java EE applications to cloud, caught my eye. By the way, I do work for RedHat and am part of the JBoss AS7 team, but I wasn’t keeping a watch on what the OpenShift team was upto, so this announcement came as a pleasant surprise! So I decided to give it a try. After reading some of the documentation on the project site, I found out that OpenShift offers two different services. One was “OpenShift Express” and the other “OpenShift Flex“. OpenShift Express is free to use (that was one more good news for me) while OpenShift Flex requires your Amazon EC2 credentials and you’ll be charged for the EC2 usage (there’s however a free trial going on currently). I decided to give OpenShift Express a try since it was free and suits my current needs of just trying out a quick and simple Java EE application deployment and access to that application.

So here’s what I did to be able to deploy my Java EE application which uses the technologies available in Java EE6 webprofile and which deploys fine on my local AS7 instance, to OpenShift Express. You might have already guessed that I’m no expert about OpenShift (or cloud services in general), so in this article doesn’t have any advanced technical details, but contains more of a how-to on deploying Java EE applications to OpenShift Express.

So let’s start then.

1. Sign Up

The first step is to sign up here to create an account for yourself. The sign up just requires a valid email address to which your account details will be dispatched. On signing up, you’ll receive a mail which contains a link to activate your account and will take you to the login screen. Login using the email id and password that you used to register.

2. Get Access to OpenShift Express

So let’s got the OpenShift Express page. On that page you will notice a “Get Access to Express” button on left hand side. Click on it to get access to “Express”. You’ll be notified (immediately) through a mail to the email id which you registered. Check the mail which will contain a link to a quick start guide, to help you get started with OpenShift Express.

3. Install Client Tools

The quick start contains the instructions to get you started with the installation procedure. The first step includes installing a few client tools on your system to help you interact with OpenShift. Follow those instructions to install the client tools (I won’t repeat them here, since it’s well explained in that guide).

4. Create Domain

Now once we have the client tools, we are now ready to setup our “domain” on the OpenShift cloud. Setting up a domain will create a unique domain name that you can use for your applications. The domain name will be part of the URL which you will use to access the application and which you’ll publish to your users for access. The command to create the domain is easy:

rhc-create-domain -l -n 

Running that command will ask you for the password that you used to register. Enter that password and let the command complete (a few seconds).

The “rhc-create-domain” is part of the client tool that you installed earlier. If you haven’t yet installed those tools, then you won’t be able to use these commands, so don’t miss that step! The “rhc-create-domain” accepts a few more optional parameters. To see the list of accepted parameters, you can run the following command:

rhc-create-domain --help

5. Create a JBossAs-7.0 Application

Once you have successfully create a domain, your next step is to create an “application”. Currently OpenShift Express supports different “types” of applications, each of them backed by Git (which is a version control system). At the point of writing this post, the supported application types are jbossas-7.0, perl-5.10, rack-1.1, wsgi-3.2 and php-5.3. I’m interested in deploying a Java EE application, so I’ll be creating a “jbossas-7.0” application. This type of application provides you a JBoss AS 7.0.0 instance in the OpenShift cloud to which you can deploy your applications. So let’s now create an application of type jbossas-7.0.

Note that the term “application” can be a bit confusing (atleast I found it a bit confusing) because all you are doing at this point is setting up JBoss AS7 server.

The command to create an application is rhc-create-app. The rhc-create-app accepts multiple options. For a complete list of options run:

rhc-create-app --help

To create a jbossas-7.0 application, we’ll run the following command:

rhc-create-app -a -l -t jbossas-7.0 -r 

Running that command will ask you for the password that you used to register. Enter that password and let the command complete (a few seconds).

The -a option lets you specify the name for your application. This name will be part of the URL that you use to access your application. If your application name is “foo” and (the previously created) domain name is “bar”, then the URL to access your application will be

The -t option in that command, specifies the application type. In our case, we are interested in jbossas-7.0

The other option of importance is the -r option which you’ll use to point to a folder on your local filesystem where OpenShift will store all the data related to your application. Part of that data will be a local copy of the git repo (version control system). We’ll see this in more detail later on in this blog.

6. Access Your Server URL

So once you run the command and it successfully completes, it will print out the URL where the application is available. You can (immediately) use that URL to access the application. On accessing that URL you’ll notice a welcome page, which is an indication that the application has been installed successfully and available for access. For me, the URL to the newly created application was

So at this point, we have created a domain and then an application and have made sure that it’s accessible to the world. In short, your cloud server is up and running and you can now deploy your Java EE applications to that server.

7. Create and Deploy a Java EE Application

So let’s now move to the step of creating and deploying a Java EE application. I didn’t have any specific application in mind, but wanted to deploy an application which would involve accessing a database. Instead of creating a brand new application, I decide to use one of the quick start applications that come with JBoss AS7. The quick start applications for JBoss AS7 are available for download here. Once you have downloaded the quick start archive, unzip it to a location of your choice. Building the quick start examples will require Maven build tool be installed on your system. The details about the quick start applications and how to build them can be found here. Those interested in trying it out themselves, might want to look at that guide.

I chose the “kitchensink” application from those quick starts. The kitchensink application uses Java Persistence API (JPA) for persistence and by default uses the java:jboss/datasources/ExampleDS which is shipped by default by JBoss AS7. The ExampleDS uses H2 as its database.This is how the persistence.xml looks like:

<!–?xml version="1.0" encoding="UTF-8"?–>

<!– If you are running in a production environment, add a managed data source, the example data source is just for proofs of concept! –>

<!– Properties for Hibernate –>

That’s enough for me now, to show how to deploy the application and also show the DB support available in OpenShift Express.

After building the application, the deployable war is named jboss-as-kitchensink.war and is available on my local file system. My next step would be to deploy it my JBoss AS7 server which we have setup on the OpenShift Express cloud. Let’s see how that’s done.

8. Deploy the Application to OpenShift Express

Remember, while creating the “application” using the rhc-create-app command, we used the -r option to point to a folder on our local file system to create a local copy of the application repository. That’s the place which will be used now for deploying our applications. In my case, I used /home/jpai/OpenShift/myapps/demo as the repo location. This is how that folder looks like:

|--- deployments
|--- pom.xml
|--- src

There’s more than one way to deploy your application to OpenShift Express. One way is to write your code and commit the source code within the src folder of your local repository and then push your changes to the remote git repository. This will then trigger a Maven build for your project on the remote repository. More details about this approach is available in this blog.

In our case, we’ll focus on how to deploy an already built Java EE application to your OpenShift Express cloud server. In the previous step, we built the jboss-as-kitchensink.war. Now, copy that war file to the “deployments” subfolder of your local git repository. In this case, it’s /home/jpai/OpenShift/myapps/demo/deployments:

cp /home/jpai/jboss-as-quickstarts-7.0.0.Final/kitchensink/target/jboss-as-kitchensink.war /home/jpai/OpenShift/myapps/demo/deployments


Once you have copied it here, your next step is to “commit” this change using the git commit command:

jpai@jpai-laptop:demo$ git add deployments/jboss-as-kitchensink.war
jpai@jpai-laptop:demo$ git commit -m "Deploy kitchensink application" deployments/jboss-as-kitchensink.war
[master 1637c21] Deploy kitchensink application
1 files changed, 0 insertions(+), 0 deletions(-)
create mode 100644 deployments/jboss-as-kitchensink.war

So at this point your kitchensink application has been commited to your local git repo. Next we should “push” this commit to the remote git repo:

jpai@jpai-laptop:openshift$ git push origin master
Counting objects: 6, done.
Delta compression using up to 2 threads.
Compressing objects: 100% (4/4), done.
Writing objects: 100% (4/4), 393.71 KiB, done.
Total 4 (delta 1), reused 0 (delta 0)
remote: Stopping application…
remote: done
remote: Found .openshift/config/standalone.xml… copying to …
remote: Starting application…done
To ssh://[email protected]/~/git/jaikiran.git/
6e57976..1637c21 master -> master

(trimmed some logs from the above output).

So with this “push” we have now deployed our application to the remote OpenShift Express JBoss AS7 server. The jboss-as-kitchensink.war will be deployed at the “jboss-as-kitchensink” web application context. So the URL to access the application will be Go ahead and access that URL. The application does nothing fancy – it allows you to add a user name, email and phone number which will then be stored in the database.

Jboss App Server
  • Save

Like I mentioned earlier, the kitchensink application uses ExampleDS datasource which is backed by H2 database. So all the data will be stored remotely in the H2 database.

9. Using MySQL Database available in OpenShift Express

OpenShift Express sets up a MySQL datasource template for you when you create a jbossas-7.0 application type. The details of the database can be found in the <path-to-local-repo>/.openshift/config/standalone.xml:

<subsystem xmlns="urn:jboss:domain:datasources:1.0">
        <datasource jndi-name="java:jboss/datasources/ExampleDS" enabled="true" use-java-context="true" pool-name="H2DS">
        <datasource jndi-name="java:jboss/datasources/MysqlDS" enabled="false" use-java-context="true" pool-name="MysqlDS">
            <driver name="h2" module="com.h2database.h2">
            <driver name="mysql" module="com.mysql.jdbc">

You’ll notice that apart from the ExampleDS that comes by default in AS7, OpenShift Express has setup a MySQL datasource which will be available at java:jboss/datasources/MysqlDS. The important piece to note here is that it is disabled (i.e. enabled=false) by default. Also notice that the password is “changeme”. Basically, this datasource configuration for MysqlDS in the standalone.xml is there as a template. In order to enable that datasource, we first have to create a MySQL database for our application. That can be done by using the following command:

jpai@jpai-laptop:openshift$ rhc-ctl-app -a <application-name> -l <email-id-we-used-to-register> -e add-mysql-5.1

The rhc-ctl-app is passed the application name (which is the one that we used during rhc-create-app) and also our account id. Additionally, we use the -e option to specify what we want to do. In this case, we issue a “add-mysql-5.1” command. Running that command will ask you for your account password and on successful completion will show the output similar to:

Mysql 5.1 database added. Please make note of these credentials:
Root User: admin
Root Password: as43n34023n
Connection URL: mysql://

Note down the user name, password and the connection url. Now open the /.openshift/config/standalone.xml in a text editor and update the MysqlDS configuration to use the connection URL, the user name and the new password. Also set the enabled flag to “true” so that the datasource is enabled. Ultimately the datasource configuration will look like:

<datasource jndi-name="java:jboss/datasources/MysqlDS" enabled="true" use-java-context="true" pool-name="MysqlDS">

Pay attention to the connection-url. It has to be of the format jdbc:mysql:///dbname. Typically, you don’t have to touch that connection-url at all, since the rhc-ctl-app add-mysql-5.1 and the datasource template are in sync with the IP/port. The important pieces to change are the password and the enabled flag.

Once this file is updated, save the changes and commit it to your local git repo:

jpai@jpai-laptop:demo$ git commit -m "Enable the MysqlDS and fix the password" ./
[master dd7b58a] Fix the datasource password
1 files changed, 1 insertions(+), 1 deletions(-)
Push these changes to remote repo:
jpai@jpai-laptop:openshift$ git push origin master
Counting objects: 9, done.
Delta compression using up to 2 threads.
Compressing objects: 100% (4/4), done.
Writing objects: 100% (5/5), 494 bytes, done.
Total 5 (delta 2), reused 0 (delta 0)
remote: Stopping application…
remote: done
remote: Starting application…done
To ssh://[email protected]/~/git/jaikiran.git/
2d38fa8..dd7b58a master -> master

So we now have added MySQL DB and enabled the MysqlDS datasource which is available at java:jboss/datasources/MysqlDS jndi name on the server. So if the kitchensink application has to use MySQL as its database, instead of H2, then all it has to do is use the java:jboss/datasources/MysqlDS. Let’s now edit the persistence.xml file that we saw earlier and use the MysqlDS instead:

<?xml version="1.0" encoding="UTF-8"?>
<persistence version="2.0" xmlns="" xmlns:xsi="" xsi:schemaLocation="">
<persistence-unit name="primary">
<!– Changed to use MysqlDS –>
<!– Properties for Hibernate –>
<property name="" value="create-drop" />
<property name="hibernate.show_sql" value="false" />


Additionally, just to “show” that this new application has been updated to use MySQL database, I also edited the index.xhtml page of the kitchensink application, to add a message on that page about MySQL database being used:

<span style="color: red;">
This application uses MySQL database as its persistence store

Next, I’ll build the kitchensink application locally using Maven, to reflect these changes and generate the new jboss-as-kitchensink.war. Once built, let’s now again copy it to our local git repo and then commit the change and push it to the remote git repo:

 jpai@jpai-laptop:kitchensink$ cp target/jboss-as-kitchensink.war /home/jpai/OpenShift/myapps/demo/deployments
jpai@jpai-laptop:demo$ git commit -m "Use MySQL database for kitchensink application" ./
[master ded2445] Use MySQL database for kitchensink application
1 files changed, 0 insertions(+), 0 deletions(-)
jpai@jpai-laptop:openshift$ git push origin master
Counting objects: 7, done.
Delta compression using up to 2 threads.
Compressing objects: 100% (4/4), done.
Writing objects: 100% (4/4), 1.35 KiB, done.
Total 4 (delta 2), reused 0 (delta 0)
remote: Stopping application...
remote: done
remote: Found .openshift/config/standalone.xml... copying to...
remote: Starting application...done
To ssh://[email protected]/~/git/jaikiran.git/
1637c21..ded2445 master ->; master

(trimmed some logs from the output)

So at this point we have now changed our kitchensink application to use MySQL database and have deployed it to our OpenShift Express AS7 server. So let’s access the application URL again As you see, that page now prominently displays our message about MySQL DB being used. Go ahead and try out that app by adding some dummy user information.

Jboss AS 7
  • Save

That’s it! We have successfully deployed our application to OpenShift Express server and the application is available for use.


It’s been a pleasant experience so far with OpenShift. I plan to try out a few more things with OpenShift, in the coming days and blog about any interesting details.

Useful Resources

While working on deploying this application, I had to use some documents and help from the OpenShift community to understand how this is all setup,. Here’s a list of useful resources related to OpenShift in general:

OpenShift Express User guide
OpenShift forums
OpenShift IRC #openshift on The folks here are very helpful!
Scott Stark’s blog. Scott’s blogs contain a lot of useful information about AS7 on OpenShift and OpenShift in general. Scott’s blog is definitely a must read!

Where to Look for Help

OpenShift questions in general are answered in the OpenShift forums. For questions around AS7 on OpenShift, the best place to ask questions is the JBoss Cloud Group.