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 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
$ 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
$ 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-addand 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.
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
-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
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.
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
$ 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|
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.
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.
- Play framework openshift module page: http://www.playframework.org/modules/openshift
- Latest version: http://www.playframework.org/modules/openshift-0.1.0/home
- Project at github: https://github.com/opensas/openshift
- Detailed tutorial about how to deploy a Play Framework application to openshift: https://github.com/opensas/play-demo/wiki/Step-12.5—deploy-to-openshift
- Excellent tutorial about deploying java applications to openshift: https://gist.github.com/1637464#file_tutorial.rst
- A couple of articles on jboss planet:
Reference: Play framework on the cloud made easy: Openshift module from our JCG partner Sebastian Scarano at the Having fun with Play framework! blog.