Creating an account at openshift

Creating an account at openshift is straightforward. Just go to
openshift express homepage and click on signup to create a new account, enter a valid email address and follow the instructions you'll receive by mail.

Installing openshift client tools

Before installing openshift client tools, you'll have to install git and ruby gems. You'll also have to install the rake gem. On a debian based linux distribution is as easy as:

On some distributions the gem installation directory is not automatically added to the path. Find the location of your gems with gem environment and add it to you system's PATH environment variable. For more details have a look at this stack overflow question and this thread at openshift's forum.

If you get the error invalid date format in specification you'll have to edit json_pure gem's specification file and enter a date like 2011-09-18. Check this openshift thread for more info.

Keeping your rhc gem up to date: to see the currently installed version of the rhc gem, issue gem list rhc. To see the latest version available run gem list -r rhc. To update it run gem update rhc. Finally, to get rid of older versions you can run gem cleanup.

Creating a domain for your applications

Before actually deploying any app to openshift, you should first create a domain, which will appear in the URL of your apps according to the following scheme:

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

Create a domain with the following command:

rhc domain create -n playdemo

Here you will have to enter the mail and password you used to register your account at openshift, not your email's password.

Openshift will then create a pair of private and public keys as libra_id_rsa and libra_id_rsa.pub at you .ssh directory. It will ask you for a password to access the private key.

Deploying your first play app to openshift

There are two ways to deploy an application to openshift.

1) You can upload your content in a maven src structure and on every git push have the application built and deployed. So you can just edit the files at /src folder and let openshift build the app with the pom.xml file once you push it.

2) You can git push prebuilt wars (with the corresponding .dodeploy file for exploded wars) into deployments/, which is what we'll do next.

In fact, deploying any play app to openshift can be as simple as that. Just issue a play war application -o <deployments folder> against the deployments folder of an openshift repo, add the files to the index, commit and push.

We will just push our application as an exploded war, so we won't be needing the pom.xml file nor the src folder. Go to the newly created repo and run:

Edit app/views/Application/index.html file and replace the welcome tag with something like Hello from openshift. Then issue the following command to generate the war exploded folder to our openshift app's git repo. (adjust folder names accordingly)

play war ~/devel/apps/playdemo -o ~/devel/apps/openshift/playdemo/deployments/ROOT.war

Notice that this time we push to openshift instead of origin. Notice also the --exclude param to avoid entering an infinite loop.

You can read this article on openshift's knowledge base to get more info on synchronizing your own git repo with openshift's one.

Deploying an existing app to openshift

If we have an existing app, instead of just generating the war file to the deployments folder, it's a good idea to use openshift git repo to manage our sources. So we'll just move all the app's files to the openshift git repo.

Copy the app from ~/devel/apps/play-demo to ~/devel/apps/openshift/playdemo folder.

Tip: right now we are using the in-memory H2 database, which will be reinitialized after each deploy. We can tell play to save it to a file in the openshift's data directory (which is persisted between pushes) with the following configuration:

Open a browser and go to https://playdemo-playdemo.rhcloud.com/phpmyadmin/, then login as admin with the password generated by openshift. It is a good idea to create another user with limited privileges. We'll create a playdemo user with select, insert, update, delete, create, index and drop permissions on database playdemo.

Look ma, no phpMyAdmin!

In recent versions openshift added support for port forwarding. This will let us work with our mysql database from a client at your workstation, like the mysql console or Mysql Workbench. Just be sure to update your red hat client tools with gem update rhc and then issue:

Then you can connect using that ip, or you can run mysql console with mysql –uadmin –p –h 127.1.23.130. You can for example upload a large backup with the following command:

mysql -uadmin -p -h 127.1.23.130 < really_laaarge_backup.sql

When you're done just press ctrl+c to stop port forwarding.

If you are a hardcore guy, you can also open a ssh and get your hands dirty working directly with the mysql console. Run rhc-info -l my_mail@mail.com -p my_password and copy the xxxxxxxxxxxxx@my_app-my_domain.rhcloud.com. Then run ssh xxxxxxxxxxxxx@my_app-my_domain.rhcloud.com and you'll be working directly at your remote workstation on openshift. There you can access the mysql command with mysql -h $OPENSHIFT_DB_HOST -P $OPENSHIFT_DB_PORT -u $OPENSHIFT_DB_USERNAME --password="$OPENSHIFT_DB_PASSWORD".

Configure our application to use openshift's mysql database

Now we will configure our application to use openshift's mysql database when it is running on the cloud.

Play framework allows you to specify different configurations for different deployment environments. To specify a particular configuration you use a different framework ID.

When an application is deployed as a war file, play automatically sets the framework ID to war when it is being executed.

You can also manually specify the framework ID with the play id command. Type play help id at the command line for more information.

Openshift exposes it's configuration setting using environment variables that we will be reading from out application.conf file.

Tip: To get a full list of environment variables, simply add a line in your .openshift/action_hooks/build script that says export and push.

In our conf/application.conf file we'll enter the following configuration:

It's advisable to install a local mysql server to troubleshoot any issue you might find. On a debian based linux distro is as easy sudo apt-get install mysql. Then you can configure the local database adding these lines to your application.conf file:

Keeping your openshift environment clean and tidy

Every Openshift Express application, by default, comes with a storage quota of 500 MB. This storage includes all libraries, tmp folders, data, git repos, application files (copy of HEAD revision from master branch of git repo), logs and application storage specific to that application.

If we were deploying our app as a zipped war file, we would be increasing our git repo size on each push, like it's explained in this article, but we are deploying an exploded war file and git is smart enough to only upload changed files.

In order to find out how your storage quota is being used, you can dowload a snapshot of your whole application with the following command:

rhc-snapshot -a playdemo

You will soon find out that jboss keeps a copy of every deployment in jbossas-7.0/standalone/tmp/vfs folder, so it's wise to clean it on each deploy. To do that, just add the following command to the .openshift/action_hooks/build file.

# do some clean up
rm -fr $OPENSHIFT_APP_DIR/jbossas-7.0/standalone/tmp/vfs/*

Summary

On this step we haven't really touched the application code, we just played with the application.conf file and git repo in order to deploy to openshift.

We saw how to:

Register an account at openshift

Install client tools

Create our own domain at rhcloud

Deploy a new play application to openshift

Add a remote openshift git repo to our own repo to deploy an existing app