h1. Openshift module

Openshift is Red Hat's free, auto-scaling, cloud-based platform-as-a-service for Java, Perl, PHP, Python, and Ruby applications.

With this module, you'll be able to easily deploy and manage your play applications on Red Hat's cloud platform, with just a couple of keystrokes from the command line.

The module does not depend on any external Java libray. You'll just need an openshift account, git and the openshift command line tools installed on your workstation.

Source code is available at <a href="https://github.com/opensas/openshift">https://github.com/opensas/openshift</a>
Written by Sebastián Scarano (<a href="http://www.twitter.com/develsas">@develsas</a>)

h2. Sample application

There's a sample application at samples_and_tests/openshift-demo. Just 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.

!images/demo_app!

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.

h2. <a name="getting_started">Prerequisites</a>

Before being able to deploy your play application to openshift, you have to:

* "install java jdk 1.5 or 1.6":[http://www.oracle.com/technetwork/java/javase/downloads/index.html] (at the moment openshift doesn't support play apps compiled against jdk 1.7.x)

* "install play framework":[http://www.playframework.org/documentation/latest/install]

* "sign up for openshift":[https://openshift.redhat.com/app/user/new/express]

* "install openshift's command line tools":[https://www.redhat.com/openshift/community/kb/kb-e1000/installing-openshift-express-client-tools-on-non-rpm-based-systems] 0.84.15 or higher.

* and finally "create a domain":[http://docs.redhat.com/docs/en-US/OpenShift_Express/2.0/html/User_Guide/sect-User_Guide-Working_With_Domains.html#sect-User_Guide-Working_With_Domains-Creating_a_Domain]

h2. <a name="getting_started">Getting started</a>

To install Openshift module add it as a dependency in your dependencies.yml file:

bc. require:
      -play -> openshift {version}

Then execute:

bc. play deps

After that, deploying your play application to openshift is as easy as:

bc. play rhc:deploy -o

Ant that's all!

The module will ask you for you openshift account (the email you signed up with) and your password. Then it will create your app at openshift if it's not already there, compile and package your app as a war folder, commit it in yout local git repository and then push it to openshift. Moreover, the @-o@ parameter tells openshift module to automatically open your newly deployed app in a web browser.

h2. Configuration

Openshift module allows you to define the following command line parameters directly on the application.conf file, so that you may avoid specifying them. You can always override them from the command line.

h3. openshift.rhlogin: your Red Hat login account

Red Hat login (RHN or OpenShift login with OpenShift Express access) account is a mandatory parameter. It's the email address you used to register at openshift. You can specify it using the @-l@ or @--rhlogin@ command line parameter or adding an @openshift.rhlogin@ option in you application.conf file. If none of these are specified, openshift command line tools will use you git configured email account. For more info check "Set your user name, email and GitHub token":[http://help.github.com/set-your-user-name-email-and-github-token/].

h3. openshift.password: your Red Hat login password

Red Hat login password is a mandatory parameter. You can specify it using the @-p@ or @--password@ command line parameter or adding an @openshift.password@ option in you application.conf file. 

h3. openshift.application.name: application name

The application name is a mandatory parameter. You can specify it using the @-a@ or @--app@ command line parameter or adding an @openshift.application.name@ option in you application.conf file. If none of these are specified, openshift module will read the application's file from the @application.name@ entry in your application.conf file. Notice that openshift application's name can only contain alphanumeric characters. So if you created a play app names my-demo, it will fail beacause of the dash. In that case you can use this parameter to specify another application name for openshift.

h3. openshift.application.subdomain: application subdomain

By default your play application will be deployed to openshift according to the following scheme:

bc. http://<application name>-<domain-name>.rhcloud.com

You can have it deployed on a subdomain specifing it with the @-s@ or @--subdomain@ command line parameter or adding an @openshift.application.subdomain@ option in you application.conf file. In that case you'll be able to reach you application at:

bc. http://<application name>-<domain-name>.rhcloud.com/<application subdomain>

h3. openshift.timeout

You can optionally specify a timeout, in seconds, for connection, using the @--timeout@ command line parameter or adding an @openshift.timeout@ option in you application.conf file.

h3. openshift.debug

You can tell Openshift module to print extra debug info, to help you troubleshoot and analyze any problem you encounter, using the  @-d@ or @--debug@ command line parameter or adding an @openshift.debug=enabled@ option in you application.conf file.

h2. Usage

Using openshift module is quite straightforward. First you should create an @openshift.rhlogin@ and @openshift.password@ configuration in your application.conf file, to avoid having to enter them on every command. 

After that, it's a good idea to check that you have fullfilled all the prerequisites. So issue:

bc. play rhc:chk

The module will then check that you have every needed prerequisite installed (jdk 1.5 or 1.6, git, ruby, ruby gems, openshift command line tools). The module will also check that the application has been created on openshift, if it's not, it will ask you to create it right away.

p(note). 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 app and replace it with the contents of your remote repo.

To deploy your application on openshift you just have to run:

bc. play rhc:deploy

With this command, the module will compile and package you app as an exploded war file at @deployments/ROOT.war@, add this to your local git repository index, commit it, and then push it all to openshift. After that openshift will automatically redeploy your application (you can see it in action with @play rhc:logs@). If you want the module to open a web browser with your application running on openshift after deploying, just issue @play rhc:deploy -o@.

To have a look at your server logs, issue:

bc. play rhc:logs

!images/logs!

Finally, if you think you want to remove your application from openshift, just run:

bc. play rhc:destroy

h2. Commands

h3. rhc:chk

Check openshift prerequisites, application and git repo.

h3. rhc:fetch

Deletes your local application an replaces it with your application hosted at openshift.

h3. rhc:info

Displays information about user and configured applications.

h3. rhc:open

Open the application deployed on openshift in web browser.

h3. rhc:deploy

Deploys application on openshift.

h3. rhc:destroy

Destroys application on openshift.

h3. rhc:logs

Show the logs of the application on openshift.

h2. Known issues

In the current version of the module, Windows os is not supported. This is because git doesn't work in the standard shell, you have to use it from the "git bash option".

h2. History

* Version 0.1.2 - Mar 07, 2012
** Updated module to use new cartridge name (changed from jboss-7.0 to jboss-7)

* Version 0.1.1 - Mar 06, 2012
** Fixed error with applications with upper case characters in it's name
** Avoid contacting openshift when creating app

* Version 0.1.0 - Feb 09, 2012