OpenShift is RedHat’s PaaS offering that provides support for running Java EE 6 application in the cloud. Java EE 6 support is currently provided by JBoss AS 7.1.0.Final that users are allowed to customize and extend. Recently released GateIn 3.2.0.Final comes with support for JBoss AS 7.1.0.Final, which means it automatically nicely fits into OpenShift as well.

In this article I’ll show how to create an OpenShift account, and deploy GateIn 3.2.0.Final to OpenShift Express.

Let’s get started.

Setting up OpenShift account

Go to openshift.redhat.com, and sign up for a free account. It takes about a minute! You’ll receive an email, use it to log in with the password you supplied, and press I Accept (you know … Terms and Conditions thingy).

The email serves as your OpenShift login, also known as your RHLogin. We'll refer to it later in the article.

Setting up OpenShift Express client tools

Follow step 1 of instructions in OpenShift Express Getting Started: https://openshift.redhat.com/app/getting_started.

Choose the instructions for your operating system. This step may be very quick or it may take a while, dependening on your OS, and currently installed tools.

Creating a new domain

In order to deploy applications to OpenShift you need to create a new domain for yourself. Domain is part of your applications’ URL and has to be unique within OpenShift - it’s possible that the one you’ll think of first has been taken already.

You create your domain once, and deploy multiple applications in it.

{noformat}
rhc domain create -n YOUR_DOMAIN --rhlogin YOUR_LOGIN{noformat}

As mentioned above, if domain creation fails try with another name.

Creating a new application

Now, let’s create a new JBoss AS7 based application. Let’s call it ‘portal’:

{noformat}
rhc app create -a portal -t jbossas-7{noformat}

When you create an application its name will become part of the URL as well. If for example I create a domain called ‘gateintest’, and an application called ‘portal’, the URL to access the application would be: http://portal-gateintest.rhcloud.com.

When application is successfully created its access URL will be displayed, as well as a git URL used to push the deployment archives and configurations to the server.

Deploying GateIn to the cloud

Next, download GateIn 3.2.0.Final jboss-as7 distribution:

{noformat}curl http://downloads.jboss.org/gatein/Releases/3.2.0.Final/GateIn-3.2.0.Final-jbossas7-preview.zip
unzip GateIn-3.2.0.Final-jbossas7-preview.zip{noformat}

When we created our ‘portal’ application a subdirectory with the same name was created for us. The directory contains a Git repository that allows us to push deployment modules and configurations to OpenShift, where a dedicated JBoss AS 7 instance will start up for our application.

Let’s ‘cd’ to ‘portal’ directory and prepare files to push to the server.

{noformat}
cd portal
{noformat}

We assume that OpenShift is using JBoss AS 7.1.0.Final - the exact same version that is packaged with GateIn 3.2.0.Final jboss-as7 distribution. This is important, as JBoss AS version mismatch would cause the integration described below to fail.


First, GateIn comes with a set of modules that we have to add to modules repository:

{noformat}
cp -r ../GateIn-3.2.0.Final-jbossas7-preview/gatein/modules .openshift/config
{noformat}

We also have to override org.jboss.as.web module, by adding a dependency into its modules.xml file. We just copy the whole patched-up module:

{noformat}
mkdir -p .openshift/config/modules/org/jboss/as/web
cp -r ../GateIn-3.2.0.Final-jbossas7-preview/modules/org/jboss/as/web .openshift/config/modules/org/jboss/as
{noformat}

Next, we copy GateIn configuration directory:

{noformat}
cp -r ../GateIn-3.2.0.Final-jbossas7-preview/standalone/configuration/gatein .openshift/config/
{noformat}

We’re almost done, we still have to copy GateIn deployment archives. We want a streamlined GateIn instance, so we only copy the main portal deployment archive without samples:

{noformat}
cp -r ../GateIn-3.2.0.Final-jbossas7-preview/standalone/deployments/gatein.ear* deployments
{noformat}

There's an asterisk in there to also pick up gatein.ear.dodeploy file - required for triggering automatic deployment.

We also have to edit the main JBoss AS 7 configuration file - standalone.xml where we enable ‘gatein’ subsystem.

There’s a catch though! We have to set some system properties through this file, which are otherwise specified through run scripts. On OpenShift we can't fiddle with run scripts so we use standalone.xml for setting the system properties. These properties point to directory locations and at the moment can’t refer to other system properties like jboss.server.configuration.dir. To set these properties we’ll therefore use absolute paths. And that's the catch part since an absolute path contains a directory equal to USER_ID - a system login used to remotely access the instance via SSH.

Issue the following command to determine your USER_ID:

{noformat}
less .git/config | grep url
{noformat}

This will display something like:

{noformat}
url = ssh://USER_ID@portal-RH_LOGIN.rhcloud.com/~/git/portal.git/
{noformat}

Where USER_ID is a hash string, and RH_LOGIN is your RHLogin.

Now download the version of standalone.xml that I have prepared which is compatible with current OpenShift Express ('Stickshift' release).

{noformat}
curl -o .openshift/config/standalone.xml https://raw.github.com/mstruk/gatein-openshift/stickshift/config/standalone.xml
{noformat}

Open .openshift/config/standalone.xml for editing, and replace the two occurrences of ${USER_ID} with your actual value. Also replace the two occurrences of ${APP_NAME} with the name of our OpenShift application - 'portal'.

That's it.

For a complete review of changes in this file you can issue a git diff command:

{noformat}
git diff HEAD .openshift/config/standalone.xml
{noformat}

We’re done with standalone.xml - make sure to save the changes.


One final thing - we don’t care much about the template web application that ‘rhc app create’ prepared for us, so we tell the tooling to skip building, and deploying it:

{noformat}
touch .openshift/markers/skip_maven_build
{noformat}

That’s it! Let’s cross our fingers now, and hope that we didn’t mess up any of the above steps, and let’s push the deployment to OpenShift.

{noformat}
git add .openshift/config/gatein/
git add .openshift/config/modules/*
git add .openshift/markers/skip_maven_build
git add deployments/*
git commit -a -m “Initial commit”
 
git push
{noformat}

If everything went as it should have, then you have just deployed GateIn to OpenShift, and can see your running application at:

http://portal-RH_LOGIN.rhcloud.com/portal

Where RH_LOGIN is your RHLogin.

Hopefully you can see GateIn home page.

If not, the best way to check what went wrong is to ssh to your OpenShift account:

{noformat}
ssh USER_ID@portal-RH_LOGIN.rhcloud.com
{noformat}

Once you’re there, check boot.log first to see if there are any ‘standalone.xml’ parsing errors:

{noformat}
cd portal/logs
less boot.log{noformat}

Then check server.log for any deployment errors:

{noformat}
less server.log{noformat}

This may give you enough information to troubleshoot the issue. Otherwise, try our forums: https://community.jboss.org/en/gatein?view=discussions.