Play framework on the cloud made easy: Openshift module

Sebastian ScaranoFebruary 15th, 2012Last Updated: October 21st, 2012

1 42 9 minutes read

Just a couple of years ago finding an afordable hosting solution for a java web application was a hard task, and looking for a free one was an impossible mission. Not to mention that even thinking about things like auto-scaling, one-command deploy, continuos integration, and that sort of stuff was plain science fiction.
This last year has witnessed a cloud revolution, and nowdays there’s a really appalling amount of alternatives to choose from. It seemed like every medium-to-large size IT player had to come out with their own Platform as a Service (PaaS) cloud offering.

In this scenario, an offering from Red Hat couldn’t go unnoticed. Red Hat engineers really know a lot about managing servers, and, lucklily for us, they also know a lot about java web applications. Fortunately, they took the challenge, and what they have to offer would certainly not disappoint us.

Isn’t that panda bear cute?

So, here comes Openshift. Openshift is Red Hat’s free, auto-scaling, cloud-based platform-as-a-service for Java, Perl, PHP, Python, and Ruby applications. It’s a quickly evolving platform, that managed to shape a vibrant and helpful community supporting it. Moreover, it’s free offering largely surpases anything that the competence has to offer. Just by entering you email and choosing a password, you get five applicacions namespaces, each of them with a git repository and half GB of data (code + database) to use as you like it. Add to that support for mysql (with phpmyadmin), PostgreSQL, MongoDB 2.0 (with MongoRock) and even a fully functional Jenkins instance to have a continuous integration environment.

Deploying a java web application to openshift is really easy, just git add, git commit, git push… and that’s it. But we, play developers, spoiled by our beloved framework as we are, would rather just type something like play rhc:deploy and forget about it.
That’s what openshift module for play framework is about.

The short story

So you have everything set up to deploy a play framework application to openshift. That means you have installed JDK 1.6 or 1.5, play framework, ruby, ruby gems, openshift client tools, and that you have signed up at openshift and also created a domain.
In that case, you just have to:

$ play install openshift

and then

$ play new <my app> --with openshift
$ cd <my app>
$ play rhc:deploy -o

… and that’s it.

Your application is ready… and running on Openshift!

Every time you want to deploy your changes to openshift, just issue once again play rhc:deploy -o. The -o parameters just tells the module to open your application on a web browser right after deployment.

From zero to the cloud

Just as a reminder to myself, here are the steps required to go from a bare linux installation to deployment on openfhit:

1. Install Java jdk 1.6
on debian based linux distributions (like ubuntu, mint and others)

$ sudo apt-get install openjdk-6-jdk

on rmp based linux distributions (like fedora, red hat, centos, and others)

$ sudo yum install java-1.6.0-openjdk-devel.i686

2. Install play framework
Here’s my quick and dirty list of commands to install play framework.

$ cd ~
$ mkdir dev
$ cd dev
$ wget http://download.playframework.org/releases/play-1.2.4.zip
$ unzip play-1.2.4.zip 

$ echo "export PATH=$PATH:~/dev/play-1.2.4" >> ~/.profile

$ source ~/.profile

And then test it with:

$ play version
~        _            _ 
~  _ __ | | __ _ _  _| |
~ | '_ \| |/ _' | || |_|
~ |  __/|_|\____|\__ (_)
~ |_|            |__/   
~
~ play! 1.2.4, http://www.playframework.org
~
1.2.4

Note: If you are running on fedora, you might need to issue sudo yum remove sox, because the sox package comes with it’s own play command that conflicts with play framework.

3. Sign up for openshift
Go to https://openshift.redhat.com/app/user/new/express enter your email and choose a password.

4. Install, git and ruby gems
On a Debian based linux distro:

$ sudo apt-get install git ruby rubygems

Rpm version:

$ sudo yum install git ruby rubygems

5. Install openshift client tools
Once you have installed ruby gems, installing red hat cloud tools is as easy as:

$ sudo gem install rhc

6. Create a domain
Your domain namespace is used to help identify your applications and as part of the URLs to your applications. It’s unique to you across all of openshift. For example, let’s say you have the namespace awesome, when you create a new app called wicked, you’ll find it at http://wicked-awesome.rhcloud.com. When you create a new app called freakin, it’ll be at http://freakin-awesome.rhcloud.com.

So go to your openshift control panel at https://openshift.redhat.com/app/control_panel and click on edit on the NAMESPACE section. Then enter something like playdemo (well, that one is already taken) and click save.

7. Create and register your SSH keys
Now you’ll have to create a pair of keys, a private and a public one.., so that openshift can validate that it’s really you the one trying to push something to the remote git repository. Just follow the steps at http://help.github.com/linux-set-up-git/, you just have to open a terminal and then

$ cd ~/.ssh

If you get a No such file or directory error, don’t worry, it means that you didn’t have any SSH key on your system. On the other hand, if you already have a SSH key, it would be a good idea to make a backup.

$ ssh-keygen -t rsa -C "<my email>"
Generating public/private rsa key pair.
Enter file in which to save the key (/home/sas/.ssh/id_rsa): 
Enter passphrase (empty for no passphrase): 
Enter same passphrase again: 
Your identification has been saved in /home/sas/.ssh/id_rsa.
Your public key has been saved in /home/sas/.ssh/id_rsa.pub.
The key fingerprint is:
22:7b:cd:f3:98:4f:92:de:80:1d:ad:d6:ea:73:20:c2 <my email>
The key's randomart image is:
+--[ RSA 2048]----+
|                 |
|                 |
|                 |
|         .       |
|   .. . S .      |
|    Eo.*.=       |
|    ..o.@.o      |
|     . o.@.      |
|       .*++      |
+-----------------+

And then, you can setup your username and email, like this:

$ git config --global user.name "<my name>"
$ git config --global user.email "<my email>"

Now you have to register this key at openshift. Just copy the content of the id_rsa.pub (be careful not to copy the file id_rsa, it’s your private key, and you should keep that to yourself) and add it as a new SSH KEY from your control panel.

On Fedora is pretty annoying having to enter your passphrase on every git operation. To avoid it, just run ssh-add and enter your passphrase for the last time.

Alternatively, you can also use the following command

$ rhc-create-domain -l <your email> -p <your password> -n <pick a domain>

and let openshift create a a pair of private and public keys as libra_id_rsa and libra_id_rsa.pub at your .ssh/ directory. I had a couple of conflicts between my own SSH keys and the libra ones created by openshift, so I prefer to handle the ssh keys myself.

Note: You won’t be able to push anything to your git repository unless you have a valid public key registered at openshift. Take into account that you can add as many keys as needed.

Go to your control panel at https://openshift.redhat.com/app/control_panel to check that everything is right.

Going to the cloud

And now yes, we are ready to deploy our play framework application to the cloud.

$ play install openshift
$ play new <my app> --with openshift
$ cd <my app>

Now, for every command you’ll have to enter, at least, your username and password. You can spare yourself this trouble by adding the following keys to your conf/application.conf file:

# Openshift module configuration
openshift.rhlogin=<my login>
openshift.password=<my password>

After that you should check that you have installed all the prerequisites. Just run:

$ play rhc:chk

It will check for a java 1.6 or 1.5 install, git, ruby, rubygem, and openshift client tools 0.84.15 or higher. It will also check that the application exists on openshift, otherwise it will ask you to create it, and finally it will check that you have a local git repository pointing at the remote repository at openshift.
Then you can deploy your app with:

$ play rhc:deploy -o

The first time it will take quite some time to issue the deploy, because the module has to upload all of the play framework libraries. After that initial deploy, subsequent commits will be much faster, because git is smart enough to send only the changed files. Moreover, the module will ask your permission to create the app on openshift, and also to create a local repo. If you just want the script to create everything without asking for permission, just add a --bypass or -b parameter to the command.
Your application will now be available at: http://<my app>-<my domain>.rhcloud.com.
If you have already deployed your application to openshift, and you just want to retrieve it from your remote git repository, just issue:

$ play rhc:fetch

Take into account that this is a destructive operation. It will completely remove your local application and replace it with the contents of your remote repository.
To have a look at your server logs, issue:

$ play rhc:logs

Having a look at openshift log files with “play rhc:logs”

To display information about your applications on openshift run:

$ play rhc:info

Which is just a short-hand for the rhc-domain-info command.
You can open your application at openshift anytime issuing:

$ play rhc:open

Which is also a short-hand for opening a web browser at http://<my app>-<my domain>.rhcloud.com.
Finally, if you think you want to remove your application from openshift, just run:

$ play rhc:destroy

Installing the openshift module

There are two ways to install openshift module. One is just to issue play install openshift, which will install the module directly with your framework, at <play install folder>/modules/openshift-0.1.0. That way it will be available to every app you create with

$ play new my-app --with openshift

The other way is to manually configure it as a dependency. Just add the following line to your conf/dependencies.yml file:

# Application dependencies
require:
    - play
    - play -> openshift 0.1.0

And then issue

play deps

Note: play keeps a cache of fetched dependencies at ~/.ivy2/cache. If you are having troubles with dependencies just clean that diectory and try again.

Along with the module there’s a sample application at <openshift module folder>/samples_and_tests/openshift-demo. Just go to that folder and issue play deps and then play run to see it running locally. It just displays play configuration and the host environment variables to let you check that your app is running on openshift.

Openshift module demo application

Then run play rhc:chk to verify that you have installed all the prerequisites. After that issue play rhc:deploy -o to create your remote application at openshift, create a local git repo, package your app as a war file, commit your new app, and deploy to openshift. Thanks to the -o parameter the module will open your openshift app in a web browser after deployment.

Getting help

You can have a look at the module’s commands issuing:

$ play help
~        _            _ 
~  _ __ | | __ _ _  _| |
~ | '_ \| |/ _' | || |_|
~ |  __/|_|\____|\__ (_)
~ |_|            |__/   
~
~ play! 1.2.4, http://www.playframework.org
~

[...]
~
~ Modules commands:
~ ~~~~~~~~~~~~~~~~~
~ rhc:chk             Check openshift prerequisites, application and git repo.
~ rhc:deploy          Deploys application on openshift.
~ rhc:destroy         Destroys application on openshift.
~ rhc:fetch           Fetches application from remote openshift repository.
~ rhc:info            Displays information about user and configured applications.
~ rhc:logs            Show the logs of the application on openshift.
~ rhc:open            Opens the application deployed on openshift in web browser.
~
~ Also refer to documentation at http://www.playframework.org/documentation
~

Then you can get more help about parameters with the -h or --help parameter:

$ play rhc:chk -h

~        _            _ 
~  _ __ | | __ _ _  _| |
~ | '_ \| |/ _' | || |_|
~ |  __/|_|\____|\__ (_)
~ |_|            |__/   
~
~ play! 1.2.4, http://www.playframework.org
~
Usage: play [options]

Options:
  -h, --help            show this help message and exit
  -a APP, --app=APP     Application name  (alphanumeric) (required)
  -s SUBDOMAIN, --subdomain=SUBDOMAIN
                        Application subdomain, root by default  (alphanumeric)
                        (optional)
  -l RHLOGIN, --rhlogin=RHLOGIN
                        Red Hat login (RHN or OpenShift login with OpenShift
                        Express access)
  -p PASSWORD, --password=PASSWORD
                        RHLogin password  (optional, will prompt)
  -d, --debug           Print Debug info
  -m MESSAGE, --message=MESSAGE
                        Commit message
  --timeout=TIMEOUT     Timeout, in seconds, for connection
  -o, --open            Open site after deploying
  -b, --bypass          Bypass warnings

You can also specify these options in the conf/application.conf file with the following keys:

openshift.rhlogin: Red Hat login (RHN or OpenShift login with OpenShift Express access)
openshift.password: RHLogin password  (optional, will prompt)
openshift.application.name: Application name  (alphanumeric) (required)
openshift.application.subdomain: Application subdomain, root by default  (alphanumeric)
openshift.debug: Print Debug info
openshift.timeout: Timeout, in seconds, for connection

You can see all versions of the module at the openshift module’s page on http://www.playframework.org/modules/openshift.
You can check the documentation at http://www.playframework.org/modules/openshift-0.1.0/home, or running locally your app in dev mode with play run, and then going to http://localhost:9000/@documentation/modules/openshift/home.

Browsing module documentation locally

You can ask questions at the play framework discussion list at https://groups.google.com/group/play-framework, or you can try with it’s spanish cousin at https://groups.google.com/group/play-latam.

Known issues

Unfortunately, right now the openshift module doesn’t work with windows. That’s because the module issues many git commands, and you can’t do that on windows from the standard shell, it requires a special “git bash” prompt.

Further steps

In the next version I’ll be exploring the possibility of building a java only version of the module using openshift’s java api. That way we won’t be needing git, ruby, nor the rhc tools installation. Morevoer, we should be able to use it all from windows as well.