So for a while now, I have been using Heroku for my hosting of Play applications. It is easy, very fast to deploy and therefore first into my mantra for development (be productive). My only issue with Heroku is the database. When I created the Play developer map, I knew that the database size was likely to be an issue, so I worked around the problem, by using a cloud database that I already had an account for.

Recently however, I have been working with some friends and we wanted to build a site which again would likely break the Heroku limit of 10K rows in the database. However, this time I didn’t want to be mixing my personal cloud db account with an application that we may want to scale up at any time. So, I went looking for an alternative solution. The options are actually pretty limited if you don’t want to splash out immediately. So the one that intrigued me the most was OpenShift. It gives you 1Gb, regardless of whether this is used for DB, application files or other.

The downside of OpenShift, is that Play is not supported as a native application server, and I needed the native features (too many potential surprises when using a WAR wrapper around a Play application). OpenShift has the concept of DIY cartridges though, that allow you to install whatever Java process you like, as long as it binds to the correct port number. So it can be done!

I spent a good few days messing around with different configurations, following other’s blog posts and installing VMs (the Play OpenShift module doesn’t work on Windows, so I tried using a Ubuntu VM on VirtualBox to trial that approach!).
Anyway, the good news is that it is relatively straightforward, once you have jumped over the hurdles in your way, so this is intended to save anyone who wants an alternative to Heroku a great deal of time in deploying an OpenShift application natively.

In a nutshell, the steps are

  1. Sign up to OpenShift
  2. Install Ruby and GIT (I deployed from Windows, so used Ruby for Windows and GIT for windows)
  3. Install RHC (red hat console) using the Ruby Gem — gem install rhc
  4. Create an application on OpenShift using a DIY cartridge
  5. Put your application code in the cloned directory
  6. Copy the open-shift hooks (see code below) into the hooks directory, which will install Play on the DIY cartridge, and correctly start/stop Play when needed
  7. Set up the application.conf to work with OpenShift ports/db/etc
  8. GIT Add/Commit/Push, to push the code to OpenShift, and watch the magic happen!

Step 1 – 3 will only ever need doing once. Once configured, each modification simply needs a GIT add/commit/push to see your changes running (Step 8). Step 4 to 7 should be a case of copy/paste. So, hopefully, we can have you up and running in no time.

The Detail

Steps 1, 2 and 3 – SignUp and Install Software
I won’t go into detail on Step 1 to 3, as the OpenShift information does a very good job of doing so. So, follow steps 1, 2 and 3 on the OpenShift Setup page and install the necessary tools for your platform (Ruby, GIT and RHC) plus sign up for an account and set up RHC.

Step 4 – Create an application
Before running the following command, make sure a directory with the same name of the app you want to create doesn’t already exists, otherwise the git clone will fail. Once you are happy, run the following code from the command prompt.
rhc app create #appname# diy-0.1

Replacing #appname# with the name of your application. This will create a DIY cartridge for you. This will automatically call GIT clone, to clone the application on to your local machine. If for some reason you have created an application using the Web site at OpenShift, you can use git clone to clone the repo to you local machine, but in our example, you don’t need to do this.

The output will also tell you the URL where you will be able to access your application, so keep a note of it at this point!

If you want a Database (which was kind of my whole reason for coming to OpenShift), then follow this command with

rhc cartridge add mysql-5.1 -a #appname#

Again, replace #appname# with your application name you set up in the previous command.

Step 5 – Develop your Play application
Store all your play application code inside the cloned repository, in the standard Play structure. If you have already started a play app, and are just looking to deploy it, you can safely just copy all the play code into the cloned repo, so that app, public, conf, lib etc are all at the same level as the .openshift directory. If you are starting a new application, create a new application with a different name (otherwise Play will complain a directory already exists), and copy the contents of the new application into the cloned repo.

You directory structure should look something like

|+ .openshift
|+ app
|+ conf
|+ diy
|+ lib
|+ misc
|+ public

You can still run play run from this structure as you did before.

Step 6 – Get the open_shift hooks!
The open shift hooks are a set of bash scripts that are executed at certain stages of the server’s lifecycle. It has scripts for things such as pre-build, start, stop etc. These are the scripts that will, install Play if it doesn’t already exist (so it will only install it once, unless you specify a new version), start the server and shutdown the server when OpenShift spins up and spins down instances. This is the bulk of the work for an OpenShift DIY cartridge. Fortunately, you can copy the code verbatim.

When you created the app, and the repo was cloned, a set of empty action_hooks were created and downloaded. There should have been 6 in total. These are

  • Build – We can leave this blank
  • Deploy – We can leave this blank
  • Post-Deploy – We can leave this blank
  • Pre-Deploy – This is where we will download and configure Play
  • Start – This will start a Play instance
  • Stop – This will stop a Play instance

So, we have 3 scripts we need to populate, and to make things easier, we will also create a shared script to help set up the configuration variables which will allow us to get data from our Play application.conf as well. These scripts were written by opensas, but I have updated them as there have been a few platform changes since his version was published.

Copy the following code into the action_hooks directory, and we are almost good to go!

Go to, and copy the files into your action hooks directory.

NOTE: In the start script, I have configured the timezone to be for London (as OpenShift is US based, and most of my web apps are for UK based). If you don’t care about the default timezone, just delete the
in the start script, or if you want a different timezone, update the value before you deploy your application.

Step 7 – Set up the application conf
Inside the scripts above, Play is configured to start with the ID of openshift. This means that we can keep our openshift config and local config completely separated. So, inside of your application.conf, place the following pieces of config.

# Openshift id configuration
# ~~~~~

# openshift mysql database
# ~~~~~

Replace #appname# with the name of your application (the same name as you set up in step 4). This allows Play to use the short db configuration, rather than the 4 individual parameters.

Step 8 – Commit and Deploy

Finally, we are ready to deploy our app. So quite simply we run three simple GIT commands.

cd #appname#
git add .
git commit -m "deploy to OpenShift"
git push

If you want to see the log files for your app running, you can tail the logs by running
rhc tail #appname#

Again, replace #appname# with the application name set up in step 4.

Now, all you need to do is to browser to the URL that you noted in Step 4, and you are done!


I hope this saves you hours of effort. The time it has taken me to type this up hopefully will be less than the time it would take you to figure all this out through trial and error, like I did. Enjoy.

And for those following the Yalp progress. I will create a Quick starter guide for Yalp as well, when it gets closer to a release candidate.


A new life for Play!yalP

Posted: March 2, 2013 in Play Framework

It’s been a while since I blogged last. The world of Play (certainly Play 1.x) has slowed, I guess as would have been expected when it was put into maintenance mode. I have also been doing lots of things Play related, but certainly nothing new. Suddenly, within a week of each other, I have 2 Play related stories to share.

First of all, Play is getting new life pumped into it. Secondly, I have been playing with OpenShift. I’ll come back to OpenShift later (maybe tomorrow), but for now let’s talk about Yalp.

After months of talking about the concept of forking Play and creating a new framework, the community has finally kicked into life and a new framework has been initialised. There have been a number of discussions on the playone discussion group (separated because of the noise of Play 2 in the Play google-group was making it hard to see Play 1 issues).

The first things have been to decide on a name, figure out some framework level issues (like the build system) and get the guiding principles in place. Helena Hjerten pointed out that searchable is a key issue, and a name that isn’t generic is a huge plus, so Nico suggested Yalp! Following a democratic survey, the name has been agreed, and the process of forking away from Play 1 has started.

It is early days and the community could really do with your help. If you have not already moved across to Play 2, and don’t intend to, then maybe join in on the discussion for the direction, scope and requirements of this evolving framework.

I for one hope that it is a success. I don’t have anything against Play 2, I think for certain requirements it is excellent, but for the majority of web applications I am building at the moment, the simplicity and productivity Play 1 gave me would still make me choose Play 1. The only downside is it’s no longer evolving and hopefully Yalp will solve this.

Community Split in Two?

Posted: April 1, 2012 in Play Framework

I have just returned from a short trip to Rome on business. I didn’t have much access to email, so I came back to a large number of emails, many of which were from the ever increasing play framework digest emails I get from Google groups. Nothing to different yet, except when I started reading, I was amazed by the reactions to the “Open Letter” thread. If you haven’t read it, then feel free to go to Google Groups and have a read, but in summary it simple read ‘I don’t like Play 2, I don’t like Scala, the Play guys have messed up’.

Quite simply, the haters are wrong, simple as that. The Play team created a fantastic framework in Play 1.x. Even at 1.0 it was way ahead of the other frameworks, and continued to push the boundaries through 1.1 and 1.2. In Play 2.0, the team have taken a different direction from what made Play 1.x special, but have again built a fantastic framework.

Now, if I were to build a new web application, of course I would choose Play. Next question would be which one? Well, it depends on the project I am undertaking, but as of yet I have not come across a problem that Play 1.x could not solve. So, I would probably stick with Play 1.

I don’t feel proficient enough in Scala to jump onto the Scala version of Play, so if I did decide to go for a Play 2 app, I would choose Java. Indeed, I am looking forward to Nicolas’s book on Play 2 with Java. I will more than likely also get Peter Hilton’s book (Play 2 with Scala), but the Java book will be much more beneficial for me. Many people have argued that you need to know Scala to write views etc, but that is not true. I had never used Groovy before I started building Play apps, but I picked groovy up in no-time writing my views, and I have already found the same is true in Play 2. Also, as a side note, you can simply use the Groovy plugin and write your views in good-old Groovy.

Now, I understand why people aren’t fully bought into Play 2 yet, I get it. I am still so happy with Play 1.x, I am not ready to move across yet. But what I don’t get is why people are so upset that Play 2 exists? It has its place, and will grow into another great framework, and I will be a better professional for knowing both technologies.

Be grateful to Guillaume and the team for open sourcing the Play framework and continuing to support both 1.x and 2.x. They saved the Java world from the tedium of J2EE frameworks and made developing fun again. If you don’t like Play 2.0, don’t use it, continue to use Play 1.x.

So, what did you do over the Christmas break? Presents, plenty of family time, kick back a little? I did all that and wrote a little web application as well. I thought I would share a little insight into how I got on.


A while back, I created a publicly shared google map so that anyone interested in Play framework could add themselves to the map. A decent number of people signed up, but it was a pain to maintain. There was no control over who could put what where. For example, someone could delete someone else’s pinpoint, change someone else’s details, or the most common issue, overwrite the play framework description and URL’s. So, I decided to create a web application that would allow the community to have a developer map, but without the issues of a simple shared google map.

The tools

Obviously, I used the Playframework, but additionally I decided to Bootstrap from Twitter. Bootstrap, if you haven’t used it yet, is a CSS base that offers a way to develop clean designs and neat interfaces. There are plenty of blogs already about how to use bootstrap, and the documentation itself is pretty complete, but suffice to say, it made the job of building the UI significantly easier. As I am not a naturally artistic person, Bootstrap has allowed me to build a UI I am proud of, without having to suffer for the cause. It fits in with the “just-works” approach of Play, it makes what should be simple, simple.

Secondly, I used Google Maps to render the maps and the icons on top of the maps. I have used Google Maps before, but decided to check out Bing Maps before making my final choice. Put simply, I found Google Maps to do everything I needed, with relative ease, and found no reason why Bing maps could be a better choice.

Quite simply, Play, Bootstrap and GoogleMaps work amazingly well together.


As most people tend to do, I decided to deploy the code onto Heroku. I have used Heroku a few times previously, and have had good experiences with it. I was tempted to try something else, due to the limit on the database size of the free account, but as I already have hosting elsewhere, I decided to just use the database on my paid-for hosting alongside Heroku as the application server. Even with this separation, the response times for the application are excellent. It has made me wonder whether there is a gap in the market for a low-end Database-as-a-Service facility to bridge the gap between the Heroku Postgres offerings.

I did have one issue with the deployment, which you may want to be aware of. My views were all lowercase HTML files, rather than camelCase, which was the case for my controller actions. On my Macbook Pro this made no difference, but as soon as I deployed to Heroku I started getting errors. It took me a while to figure this out, because the error logging wasn’t working ver well. Unfortunately I had already committed my code to the local git repository on my mac, which did not care about case differences, so I had to fight with a few git mv commands to move the files to uppercase equivalents. Other than that, the whole thing has worked out pretty well.

Next Steps

Well, its still in beta, so if you guys like it, and it starts to take off, expect more features to start appearing. What I am hoping for is for the word to spread, so that more and more people add themselves to the maps (why not start with the play framework map). Additionally, I would hope that people will create maps for other technologies that they are interested in.

If you have any thoughts or comments, please feel free to get in touch!

Play Hackathon

Posted: October 16, 2011 in Play Framework

Get Hacking!

Inspired by the National Novel Writing Month (NaNoWriMo), this competition is aimed at teams of Play developers to produce awesome applications during the month of November. At the end of November, the finished applications will be judged (by the Play Community) to see who has the best application, and which team has won.


  • Start developing 1st November 2011
  • Finish developing 30th November 2011
  • Judging will start 1st December for 1 week
  • Winners will be announced 8th December
  • Teams up to 5 members
  • Your application must have an about page, or popup, stating it was developed as part of this event and using the Play Framework

Sponsors and Prizes

If you would like to be a sponsor, or donate prizes for this event, please get in contact with me.

To sign up and register for the event, just go along to the Registration page, hosted on Heroku.

I will post another short blog later this week on how simple it was to get up and running on Heroku.


Today, an interesting question was raised at Stackoverflow regarding if it were possible to define Dev/Prod mode specific routes in the Routes file.

The simple answer, was that I didn’t know, but I had an theory that this could be possible, so I threw together a quick prototype to see if it would work.

The premise of the idea was that the routes file does allow scripting to take place, which I have used before to define a Context, which is the agreed way to for managing the war context when deploying to Tomact and other Servlet containers.

So, taking the idea that scriptlets are possible in the routes file, I wondered if this could be taken a step further, whereby logic could be carried out in the routes file, rather than simple assignment scriptlets.

The prototype

The prototype itself was pretty simple. I started a new play project

play new routesproto

and started the Play server.

play run routesproto

I then modified the to have a few actions, which simply returned a little text to show the action completed successfully. There was simply no need to write templates for the actions, as that was not what I wanted to prove.

public class Application extends Controller {

    public static void index() {
    public static void noDev() {
    public static void noProd() { 

I then went about making my routes file Dev and Prod specific. I created a few routes per environment as follows.

# Home page
GET     /                                       Application.index

# Ignore favicon requests
GET     /favicon.ico                            404
# Map static resources from the /app/public folder to the /public path
GET     /public/                                staticDir:public

%{ if (play.mode.isProd()) { }%
GET		/route1									Application.noDev
GET		/route2									Application.noDev
GET		/route3									Application.noDev
%{ } }%

%{ if (play.mode.isDev()) { }%
GET		/route4									Application.noProd
GET		/route5									Application.noProd
GET		/route6									Application.noProd
%{ } }%

*       /{controller}/{action}                  {controller}.{action}

So, what’s going on in here? Well, all the main (shared) routes are held at the top of the routes file, and then anything that becomes specific to Dev or Prod mode are placed at the bottom. As usually is the case, the catch-all should be last, so after the second if tag is closed, we follow it with the catch-all route.

The following line is responsible for the logic in our routes file.

%{ if (play.mode.isDev()) { }%

and all routes between this piece of logic, and the closing of the if statement, indicated by the following line, are enabled.

%{ } }%

This simple line simply checks what Mode the application is running in, and if it is running in Dev mode, then the routes defined in between the opening and closing parenthesis become available.


I do not expect this syntax to immediately find its way in to every Play application routes file, but I no doubt think that it will be useful to many of us Players. Indeed, without the Stackoverflow question, I would never have even considered experimenting whether this method was actually possible or not, so thanks to Roshan for raising the question.

Websockets in Play

Posted: April 25, 2011 in Play Framework
Tags: ,

It has been nearly 4 months since I released the first beta of the Play Framework eBook, quickly followed by the final release accompanied with the paperback edition. Comments and feedback have been fantastic, so thank you all!

I released the book fully updated to the 1.1 version of Play, and now 4 months later, Play 1.2 has been released with a host of new features. As a quick snapshot these features include

  • Dependency Management – using Apache Ivy
  • Evolutions – for tracking and organising changes to your database schemas
  • H2 in memory database – replaces the older HSQLDB, and comes with a web console accessible using the URL /@db
  • Updates to the TestRunner
  • Plus many bug fixes and small enhancements to the Play codebase

All of these features sound absolutely great, but there is one set of features that I have been really looking forward to, and that is WebSockets!

Using WebSockets
So, why so exciting? Well quite simply put, a few years ago, in my spare time I used to write Java Swing based multi-player turn based games. Usually they were clones of popular board games, but they had a real problem! No-one really enjoyed downloading and installing a game. They wanted it on-demand, in a browser, easily accessible. But Web programming did not really lend itself well to this type of world. Play made it very easy to come close using AJAX and its long-polling method (discussed in Chapter 12) of suspending the HTTP request until there is an update, but for me I was eager for Websockets.

I finally got round to playing with Websockets this weekend and I must say, I am impressed. The Play Dev guys have done a great job with this. The documentation is not fantastically verbose, so this post is an attempt to make life a little easier for anyone wanting to play with Websockets using my favourite framework!

What do you need
Quite simply, you need Play 1.2 and a web browser that support websockets. So, switch off IE (even if you have IE9!), and use Chrome. If you have Firefox or Opera, the websocket protocol has been disabled due to some security issues, which is disappointing, but these will be cleared up at some point, so for now I will keep learning and playing with Websockets as they will be a great competitive advantage later.

Let’s try it out
Unlike the Long Polling method, which would check the database for changes to the model at predefined intervals, the idea of a websocket is to be always open, waiting for an event, and then broadcasting that event to everyone who needs to know. Therefore, the way to achieve this in Play is to have a Stateful object residing on the server side. I know this breaks a lot of the stateless, RESTful ideals of Play, but it is the only way to make this work. So, lets start with out Stateful Model.

Create a new application called websocket.

play new websocket

Now, create a new file called in the app/models directory and add the following code.

package models;

import play.libs.F;

public class StatefulModel {
   public static StatefulModel instance = new StatefulModel();
   public final F.EventStream event = new F.EventStream();

   private StatefulModel() { }

So, a very simple class. It is has a private constructor and a single static instance variable to enforce the Singleton pattern, meaning only a single instance of this model can exist on the server. The only other attribute is an EventStream object. This is an important piece. The EventStream is the core of the WebSockets implementation in Play. It allows events to be published, which notifies any waiting listeners that an event has been published. In this example, we are using a standard EventStream, which just gives access to the current event. Play also provides an ArchivedEventStream (check out the chat sample application to see it in action), which gives access to all the archived messages as well. To explain this EventStream concept in more detail, lets take a look at the Controller.

Open the in the app/controllers directory, and add the following code.

package controllers;

import play.mvc.*;
import models.*;

public class Application extends Controller {

   public static void index() {

   public static class WebSocket extends WebSocketController {

      public static void listen() {
         while(inbound.isOpen()) {
            String event = await(StatefulModel.instance.event.nextEvent());

So, not a lot going on here either. The index action will simply render the index page, and then we have a listen action inside a WebSocket static class. The WebSocket static class implements a new type of controller introduced in Play 1.2 called WebSocketController. The difference between a WebSocketController and a standard Controller is that it does away with the request/response model, and in its place has an inbound and outbound model. Here, the code simply loops while the inbound is open (which means the browser is still open, and the web socket is still connected). We then wait for a new event from our StatefulModel’s EventStream, by calling nextEvent.

The await function replaces the suspend function in play1.1. The await function will suspend the http request, freeing up the play framework to continue to process requests, until a new event is added to our Stateful Model, at which point the code will continue processing from the point where it left off. This is another important change in Play1.2. It does not call the method from the beginning again, it carries on where it left off, making the code more readable.
Once the code continues it sends the data from the event to the outbound, which sends the event back to the web browser.

So, how does the browser deal with it? Well, it is again really simple.
Open views/application/index.html and add the following code.

#{extends 'main.html' /}
#{set title:'Home' /}

<div id="socketout"></div>

<script type="text/javascript">
    // Create a socket
    var socket = new WebSocket('@@{Application.WebSocket.listen}')

    // Message received on the socket
    socket.onmessage = function(event) {
        $('#socketout').append("<br />");

So, all we have here is a DIV tag where we will output our Web Socket events, and a bit of javascript that, a) creates the websocket connection, and b) deals with the on message event by appending the data to the DIV.

One final piece before we start to add events to our websocket, is the routes file. Unlike the normal Catch-All request, this does not work, as the catch all works on Controller.action name, and we have also a static class to contend with as well. Therefore, for our routing to work, we also need to add a route. Open the routes file and add the following route next to the homepage

WS      /socket                                 Application.WebSocket.listen

Note, the WS as the HTTP Request type, to describe a WebSocket request. The rest of the route is accessed as you would expect any other route to be configured.

That is our websocket implementation up and running. The final part however is to start adding some events. If we started our application now, we would just see a blank page. Our websocket would be open, but there would be no data coming back to us from the server. So, lets create an asynchronous job to start putting some messages on the EventStream.

Create a new directory called app/jobs, and then create a file called Add the following code.

package job;

import models.StatefulModel;

@OnApplicationStart(async = true)
public class Startup extends Job {
   public void doJob() throws InterruptedException {
      int i = 0;

      while (true) {
         StatefulModel.instance.event.publish("On step " + i);

This is a simple startup job, that has been set to run asynchronously. It simply loops forever (or until the server is stopped) and on each iteration, it sleeps for 1 second, and then publishes an event to our StatefulModel’s EventStream with a String saying “On Step ” followed by the count. This will continue until the server is stopped.

To get this code to execute, we needed to specify the @OnApplicationStart was to run in async mode. Without this setting, the Bootstrap job would be configured so that it MUST complete before the first request can be executed. This makes sense, as if we are using the Bootstrap job to read runtime settings for our application, we would not want it to start until it had done all of its work. In this case however, we just want it to run in parallel.

If you now start the server with

play run websocket

Now point your browser at localhost:9000, you should see your browser start counting up from 1. But what if you open another web browser? You will see that it will start counting in time with the other browser. The event is effectively broadcasted to all listening browsers. Obviously this is by design and you could tailor the way in which you build your application, but the concept is a powerful one.

And before I sign off, another big thank you to the Play developers. This request for Websockets came directly from the very active Play community, and the Play Dev guys implemented superbly whilst staying true to the framework. A fine piece of software engineering.