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

Consider voting for Play framework native support on 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:

sudo apt-get install ruby rubygems ruby-dev
sudo gem install rake
sudo gem install rhc
rhc setup

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.

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.

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 app create -t jbossas-7 -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 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.
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 create a local repo by cloning the demo application:

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 openshift repo as a remote

git remotes add openshift ssh://017fd61e37f5444e96a5279f08b93ca9@playdemo-playdemo.rhcloud.com/~/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 unnecessary 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.

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.

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 folfers you should take care not to overwrite are .git, .openshift and deployments.

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

application.name=playdemo

And now create the war file, 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.

Persist data to a mysql database

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
   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
URL: https://playdemo-playdemo.rhcloud.com/phpmyadmin/

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:

rhc-port-forward -a my_app -p my_pass
Checking available ports...

Binding httpd -> 127.1.23.130.2:8080...
Binding java -> 127.1.23.130.1:8080...
Binding mysqld -> 127.1.23.130.1:3306...

Use ctl + c to stop

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:

# 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=password

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

Alternatively, you can use the mysql datasource proveded by openshift. Add the following to your application.conf:

# openshift production config - mysql database
%war.db=java:jboss/datasources/MysqlDS
%war.jpa.dialect=org.hibernate.dialect.MySQLDialect

And then you can adjust the user and password editing the file .openshift/config/standalone.xml

<datasource jndi-name="java:jboss/datasources/MysqlDS" enabled="${mysql.enabled}" use-java-context="true" pool-name="MysqlDS">
    <connection-url>jdbc:mysql://${OPENSHIFT_DB_HOST}:${OPENSHIFT_DB_PORT}/${OPENSHIFT_APP_NAME}</connection-url>
    <driver>mysql</driver>
    <security>
      <user-name>playdemo</user-name>
      <password>password</password>
    </security>
</datasource>

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=playdemo
db.pass=password

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: