Step 12.5 deploy to openshift

Step 12.5 - deploy to openshift

Purpose: in this step we will see how to deploy you app to openshift, redhat's cloud computing platform.

cd ~/devel/apps
git clone git://github.com/opensas/play-demo.git
cd play-demo
git checkout origin/12.5-deploy_to_openshift

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. On a debian based linux distribution is as easy as:

sudo apt-get install ruby rubygems ruby-dev

and then

sudo gem install rhc

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.

Follow these instructions to add openshift tools on windows, mac or linux. You can also see this video.

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-create-domain -n my_domain -l [email protected] -p my_password

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.

Generating OpenShift Express ssh key to /home/sas/.ssh/libra_id_rsa
Generating public/private rsa key pair.
Enter passphrase (empty for no passphrase): 
Enter same passphrase again: 
Your identification has been saved in /home/sas/.ssh/libra_id_rsa.
Your public key has been saved in /home/sas/.ssh/libra_id_rsa.pub.
The key fingerprint is:
26:86:45:1d:7e:01:81:bd:ac:b6:77:52:0e:0d:1d:23 sas@sas-box
The key's randomart image is:
+--[ RSA 2048]----+
|      .+++.      |
|     ...E o.     |
|      ...+.o     |
|     o  +..      |
|    . o.So       |
|     .oo. o      |
|     . . +       |
|      . o o      |
|       . o       |
+-----------------+
Contacting https://openshift.redhat.com
Creation successful

You can go to openshift's console to see your newly created domain.

Creating your first openshift app

Create a directory like ~/devel/apps/openshift and issue the following command:

rhc-create-app -l [email protected] -p my_password -t jbossas-7.0 -a playdemo

Here we are creating a jboss application named playdemo.

You can go to https://openshift.redhat.com/app/dashboard to see your brand new app. You can even see it running at http://playdemo-playdemo.rhcloud.com/. Openshift has also created and cloned a git repository for us.

Deploying your first play app to openshift

There are two ways to deploy an application to openshift.

You can upload your content in a maven src structure and on 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.
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:

cd ~/devel/apps/openshift/playdemo
rm -fr pom.xml src
git add -A
git commit -m "get rid of useless application"

Now we'll just create a dummy application in another directory with

cd ~/devel/apps
play new playdemo

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

Lastly, create a ROOT.war.dodeploy file to tell jboss to go ahead and deploy our app.

touch ~/devel/apps/openshift/playdemo/deployments/ROOT.war.dodeploy

If no file has changed, but you want to force a redeploy, you just have update the contents of the .dodeploy file and push it to your openshift repo.

Now we'll commit our changes and push them to openshift to deploy our app.

cd ~/devel/apps/openshift/playdemo
git add -A
git commit -m "deploy dummy play application"
git push origin

In order to check the logs and see what's going on in our server on red hat's cloud, open another terminal and issue the following command rhc-tail-files -a playdemo.

The first time it will take several minutes to complete the deploy, because git is pushing play libraries, but further deploys will just push the modified files so it will be much faster.

Currently openshift will not work with a war compiled with JDK 7, so be sure to use a JDK 1.6.x version. Check it with the java -version command.

Now you can check that your application is up and running at http://playdemo-playdemo.rhcloud.com/.

Deploying an app that it is already on a git repo

If you already have your app in a git repo, like in our case, it is easier to configure openshift repo as a remote, and then just push to that repository.

Let's first clone the app to a local repository:

cd ~/devel/apps
git clone https://github.com/opensas/play-demo.git
cd play demo
git checkout origin/12.5-deploy_to_openshift

Now we'll add our openshit repo as a remote

git remotes add openshift ssh://[email protected]/~/git/playdemo.git/ 
git fetch openshift
git branch -b openshift/master
rm -fr pom.xml src
rm .gitignore
git add -A
git commit -m "remove useless application"

Then we'll just merge that repo with ours, to include deployments and .openshift folder in our repo.

git checkout master
git merge openshift/master

You can also set a .gitignore file to avoid committing unnecesary files to your repo. Take this file as an example:

target

# Extracted from https://github.com/ulrich/macaron-factory/blob/master/.gitignore
# Ignore all dotfiles...
.*
# except for .gitignore
!.gitignore
!.openshift

# Ignore Play! working directory #
/db
/eclipse
/log
/logs
/precompiled
/tmp
/test-result
/eclipse
/server.pid

!deployments

And now, we'll just have to package our app and push it to openshift

touch deployments/ROOT.war.dodeploy
play war -o deployments/ROOT.war --exlude deployments
git add -A
git commit -m "my play application deployed to openshift"
git push openshift

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

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 apps files to the openshift git repo.

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

cd ~/devel/apps
cp -r play-demo/app/ openshift/playdemo/
cp -r play-demo/conf/ openshift/playdemo/
cp -r play-demo/jar/ openshift/playdemo/
cp -r play-demo/lib/ openshift/playdemo/
cp -r play-demo/modules/ openshift/playdemo/
cp -r play-demo/public/ openshift/playdemo/
cp -r play-demo/test/ openshift/playdemo/

In fact you can copy all your app, the only folfer you should take care not to overwrite are .git, .openshift and deployments.

Then edit conf/application.conf file adjust set the name of the app to playdemo

application.name=playdemo

And now create the war file (notice the --exclude param to avoid entering an infinite loop), commit the files and push to openshift

play war -o deployments/ROOT.war --exclude deployments
git add -A
git commit -m "play demo application deployed to openshift"
git push

In order to let play create the database tables, you'll have to uncomment jpa.ddl=update in the application.conf file.

Now open a browser and navigate to http://playdemo-playdemo.rhcloud.com/, you should see the app running.

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:

%war.db.driver=org.h2.Driver
%war.db.url=jdbc:h2:file:${OPENSHIFT_DATA_DIR}play;MODE=MYSQL
%war.db.user=sa
%war.db.pass=

You can find more info about H2 configuration parameters at the H2 documentation page.

Add persistence with mysql

Openshift provides us with several services (cartridges) we can use. To see the list of available cartridges issue the following command:

rhc-ctl-app -a playdemo -L

List of supported embedded cartridges:

mysql-5.1, phpmyadmin-3.4

Let's install mysql-5.1 cartridge.

rhc-ctl-app -a playdemo -e add-mysql-5.1
Mysql 5.1 database added.  Please make note of these credentials:

   Root User: admin
   Root Password: xxxx(2VJeSXSc11QL)
   Database Name: playdemo

Connection URL: mysql://127.1.3.1:3306/

You can manage your new Mysql database by also embedding phpmyadmin-3.4.

Openshift is telling us that phpmyadmin cartridge is also available, so we'll follow his advice.

rhc-ctl-app -a playdemo -e add-phpmyadmin-3.4

RESULT:
phpMyAdmin 3.4 added.  Please make note of these credentials:
   Root User: admin
   Root Password: xxxx (2VJeSXSc11QL)
URL: https://playdemo-playdemo.rhcloud.com/phpmyadmin/

Just 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.

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

Configure our application to use openshift's mysql database

Play framework allows you to specify different configurations for differente deployment enviroments. 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 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:

# openshift production config
%war.db.url=jdbc:mysql://${OPENSHIFT_DB_HOST}:${OPENSHIFT_DB_PORT}/playdemo
%war.db.driver=com.mysql.jdbc.Driver
%war.db.user=playdemo
%war.db.pass=demo

Here we configure the the database host and port by reading the OPENSHIFT_DB_HOST and OPENSHIFT_DB_PORT environment variables.

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:

# development config
db.url=jdbc:mysql://localhost:3306/play
db.driver=com.mysql.jdbc.Driver
db.user=play-demo
db.pass=demo

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: