Deploy WebSocket Web Applications With JBoss Wildfly

Wildfly application server on OpenShift

Wildfly is the new name for the community edition of the JBoss Application Server. The current development version of Wildfly (8.0) will be adding support for Java EE 7. Java EE 7 brings a lot of goodies for Java(EE) developers. One of the features of Java EE 7 is the JSR 356 Java API for WebSockets, which specifies a Java API that developers can use to integrate WebSockets into their applications — both on the server side as well as on the Java client side. In case you are new to WebSockets or JSR 356, please refer to my earlier blog post on this subject. In this blog post, we will install Wildfly on OpenShift using the DIY cartridge and look at the sample WebSocket application bundled with the quickstart.

OpenShift already has best in class Java support with Tomcat 6, Tomcat 7, JBoss AS7, and JBoss EAP 6 bundled with it. You can also run Jetty or GlassFish on it using the DIY cartridges. In addition, OpenShift provides support for Jenkins continuous integration server.


Before we can start building the application, we’ll have to do a few setup tasks :

  1. Sign up for an OpenShift Account. 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.

  2. Install the rhc client tool on your machine. The rhc is a ruby gem so you need to have ruby 1.8.7 or above on your machine. To install rhc, just typesudo gem install rhc. If you already have one, make sure it is the latest one. To update your rhc, execute the command shown below.sudo gem update rhc. For additional assistance setting up the rhc command-line tool, see the following page:

  3. Setup your OpenShift account using rhc setup command. This command will help you create a namespace and upload your ssh keys to the OpenShift server.

Installing Wildfly on OpenShift in Under Two Minutes

It takes less than two minutes to spin up a Wildfly instance on OpenShift. All you need to do is run the following commands at a terminal prompt. The OpenShift Wildfly quickstart is available on github at To write this quickstart I have taken help from this blog post.

$ rhc app create wildfly diy
$ cd wildfly
$ rhc app stop --app wildfly
$ git rm diy/index.html
$ git rm diy/testrubyserver.rb 
$ git remote add upstream -m master
$ git pull -s recursive -X theirs upstream master
$ git push

The commands shown above first creates an OpenShift DIY application, stops the default ruby HTTP server, deletes template files, adds a git remote repository where the Wildfly quickstart exists, then pulls all the source code to your local machine, and finally pushes changes to your OpenShift gear where the application is running.

After the git push successfully finishes, the Wildly application server will be accessible at http://wildfly-{domain-name}

Wildfly application server on OpenShift

The sample WebSocket application bundled with the quickstart is accessible at http://wildfly-{domain-name} The application simply reverses the message and echos back to the user.

Wildfly WebSocket demo application

Under the Hood

Now that we have Wildfly up and running on OpenShift, let’s look at what we have done in the commands mentioned in the previous section. When we pushed the source code, OpenShift invoked certain action hooks. The action hooks give developers a chance to hook into the application life cycle. We have written two action hooks — start and stop under .openshift/action_hooks folder. In the start hook, we wrote a few bash commands to download the current version of Wildfly, make changes to the Wildfly standalone.xml configuration file , and then start the Wildfly server. The start hook is shown below. You can view the full start hook here.

if [ -d $OPENSHIFT_DATA_DIR/wildfly-8.0.0.Alpha3 ]
    cd $OPENSHIFT_DATA_DIR/wildfly-8.0.0.Alpha3
    nohup bin/ -b $OPENSHIFT_DIY_IP -bmanagement=$OPENSHIFT_DIY_IP > $OPENSHIFT_DIY_DIR/logs/server.log 2>&1 &
    // configure standalone.xml
    // start Wildfly application server

Similarly, we have overwritten the stop action hook. The stop action hook stops the Wildfly application server.

jps | grep jboss-modules.jar | cut -d ' ' -f 1 | xargs kill
exit 0

Testing WebSocket Support

To test the Wildfly WebSocket support, I have written a very simple WebSocket application. The application is available on github. The application just has one Java class — ReverseEchoWebSocketServerEndpoint. It is a WebSocket server endpoint which reverses the message and then sends the message back to the client.

public class ReverseEchoWebSocketServerEndpoint {
    private final Logger logger = Logger.getLogger(this.getClass().getName());
    public void onConnectionOpen(Session session) {"Connection opened ... " + session.getId());
    public String onMessage(String message) {
        if (StringUtils.isBlank(message)) {
            return "Please send message";
        return StringUtils.reverse(message);
    public void onConnectionClose(Session session) {"Connection close .... " + session.getId());

The class shown above exposes a WebSocket endpoint at the /echo URL. The URL is relative to the root of the web socket container and must begin with a leading “/”. If the application is available at http://wildfly-{domain-name} then the WebSocket URL will be ws://wildfly-{domain-name} or wss://wildfly-{domain-name} connection). Please note that in OpenShift, WebSockets are available over ports 8000 and 8443. Please refer to this blog post by Marek Jelen to learn more about OpenShift WebSocket support.

The client side of the application is HTML5 and we use the WebSocket JavaScript API to connect with the backend server. On page load, we create an instance of WebSocket object and listen to various WebSocket events as shown below.

var wsUrl;
if (window.location.protocol == 'http:') {
    wsUrl = 'ws://' + + ':8000/websocket-reverse-echo-example/echo';
} else {
    wsUrl = 'wss://' + + ':8443/websocket-reverse-echo-example/echo';
console.log('WebSockets Url : ' + wsUrl);
var ws = new WebSocket(wsUrl);
ws.onopen = function(event){
    console.log('WebSocket connection started');
ws.onclose = function(event){
     console.log("Remote host closed or refused WebSocket connection");
ws.onmessage = function(event){

When the user presses the send button, the application writes a message over the WebSocket connection. The message is sent to the server which reverses it and sends it back to the client. The client then writes to the output text area on the right side.

    var message = $('textarea#inputMessage').val();
    console.log('Input message .. '+message);


In this blog post, we learned how to install the Wildfly application server on OpenShift and deploy our WebSocket based web applications on it. If you are a Java EE developer and want to try out Java EE 7 features, OpenShift is a great choice.

What’s Next?

Java, OpenShift Online
Comments are closed.