Getting Started with OpenShift

Chapter 4. Adding Application Components

OpenShift cartridges provide the components for building your application infrastructure. Our example Python app currently utilizes a single cartridge, Python 2.7. In this chapter, we will demonstrate how to add cartridges that provide additional capabilities, such as data storage, task scheduling, and monitoring. We will also explain how to find and use third-party cartridges created by the open-source community or OpenShift partner organizations.

Tip

This chapter shows how to add cartridges to an OpenShift application after it has been created. However, you can also select multiple cartridges when you create your app. To do this, add the extra cartridge names or URLs after the primary cartridge name. For example, to create a PHP 5.4 application with Cron and a MySQL 5.5 database, you could use the following command:

rhc app create appname php-5.4 mysql-5.5 cron-1.4

Database-Related Cartridges

The cartridges most commonly added to OpenShift applications after creation are database cartridges, such as PostgreSQL, MySQL, and MongoDB. If the application is not scalable, the database cartridge will be installed on the same gear as the primary application cartridge. If the application is scalable, the database cartridge will be added on its own gear. This enables the gear hosting the application cartridge to be replicated, without affecting the database. It also prevents the application server and the database from sharing the memory and disk space of a single gear.

Cartridges can be added with the command rhc cartridge add, and removed with rhc cartridge remove. Other RHC cartridge management commands include list, status, start, restart, stop, and storage; rhc cartridge --help will display the full list of options.

Here we add a PostgreSQL 9.2 cartridge to our running example, Insult App:

[me@localhost ~/insultapp]$ rhc cartridge add postgresql-9.2

Adding postgresql-9.2 to application 'insultapp' ... done

postgresql-9.2 (PostgreSQL 9.2)
--------------------------------
  Gears:          Located with python-2.7
  Connection URL: postgresql://$OPENSHIFT_POSTGRESQL_DB_HOST:
  $OPENSHIFT_POSTGRESQL_DB_PORT
  Database Name:  insultapp
  Password:       SLat4aTfsSt1
  Username:       adminm4rvN42

PostgreSQL 9.2 database added.  Please make note of these credentials:

   Root User: adminm4rvN42
   Root Password: SLat4aTfsSt1
   Database Name: insultapp

Connection URL: postgresql://$OPENSHIFT_POSTGRESQL_DB_HOST:
$OPENSHIFT_POSTGRESQL_DB_PORT

We can see from the output that the PostgreSQL cartridge has been added and is located on the same gear as the Python cartridge; this is because our demo application is not scalable. RHC has also displayed some useful information about the database set-up, including the database root user’s username and password.

There are multiple ways to connect to your OpenShift database. Spoiler alert: we will show you how to connect to a DB in your application code in Chapter 6; there are some other topics we need to cover first before we get there. We will demonstrate how to connect to the gear hosting the database via SSH and how to view the environment variables related to database (and other) cartridges in Chapter 5. To find out how to use port forwarding to connect to an OpenShift database, see Chapter 7.

Tip

There are additional cartridges you can add to your OpenShift application to help you manage some databases: for example, the phpMyAdmin, RockMongo, and MongoDB Monitoring Service cartridges. See Finding Cartridges and QuickStarts for tips on where to find OpenShift cartridges.

Nondatabase Cartridges

Our discussion so far has been focused on OpenShift cartridges that provide programming language runtimes, application servers, web frameworks, and databases. These are the major building blocks of OpenShift applications, but the platform can also provide complementary functionality. At the end of the previous section, we briefly mentioned some of the cartridges available to assist with database administration and management. In this section, we will examine some of the other cartridges you may like to add to your app to facilitate tasks such as job scheduling, continuous integration, and metrics collection.

Cron

The Cron cartridge allows users to schedule jobs to be executed periodically, using the Linux cron utility. This tool can be used for tasks such as deleting temporary files, generating reports, backing up data, or Rickrolling friends regularly. To use cron, first add the Cron cartridge to your application with the rhc cartridge add command, as shown here for our Insult App:

[me@localhost ~/insultapp]$ rhc cartridge add cron
Using cron-1.4 (Cron 1.4) for 'cron'
Adding cron-1.4 to application 'insultapp' ... done

cron-1.4 (Cron 1.4)
--------------------
  Gears: Located with python-2.7, postgresql-9.2

To schedule your scripts to run on a periodic basis, add the scripts to
your application's .openshift/cron/{minutely,hourly,daily,weekly,monthly}/
directories (and commit and redeploy your application).

Example: A script .openshift/cron/hourly/crony added to your application
         will be executed once every hour.
         Similarly, a script .openshift/cron/weekly/chronograph added
         to your application will be executed once every week.

If we run the rhc app show command, we can see that our example application still has one gear but now lists three cartridges, Python 2.7, PostgreSQL 9.2, and Cron 1.4:

[me@localhost ~/insultapp]$ rhc app show
insultapp @ http://insultapp-osbeginnerbook.rhcloud.com/
(uuid: 6e7672676e61676976757570)
------------------------------------------------------------------------------
  Domain:     osbeginnerbook
  Created:    Mar 14  1:59 PM
  Gears:      1 (defaults to small)
  Git URL:    ssh://[e-mail]
  .com/~/git/insultapp.git/
  SSH:        [e-mail]
  Deployment: auto (on git push)

  python-2.7 (Python 2.7)
  -----------------------
    Gears: Located with postgresql-9.2, cron-1.4

  postgresql-9.2 (PostgreSQL 9.2)
  -------------------------------
    Gears:          Located with python-2.7, cron-1.4
    Connection URL: postgresql://$OPENSHIFT_POSTGRESQL_DB_HOST:
    $OPENSHIFT_POSTGRESQL_DB_PORT
    Database Name:  insultapp
    Password:       SLat4aTfsSt1
    Username:       adminm4rvN42

  cron-1.4 (Cron 1.4)
  -------------------
    Gears: Located with python-2.7, postgresql-9.2

To make use of our new Cron cartridge, we need to place a script in our local Git repository in one of the .openshift/cron directories. The directory we choose will dictate whether the job is performed every minute, hour, day, week, or month. The script needs to be executable (chmod +x scriptname) and should be added, committed, and pushed with Git, as described in Chapter 3.

Here is an example script that we will set to run every minute, so that it sends some special output to the cartridge log directory every half an hour:

#!/bin/bash
# .openshift/cron/minutely/ricktock

MIN=$(date '+%M')
LOG=${OPENSHIFT_PYTHON_LOG_DIR}/ricktock.log
MSG1="Never gonna give you up\nNever gonna let you down\nNever gonna run around
and desert you"
MSG2="Never gonna make you cry\nNever gonna say goodbye\nNever gonna tell a lie
and hurt you"

if [ $MIN == 15 ]; then
  echo -e `date` $MSG1 >> $LOG
fi

if [ $MIN == 45 ]; then
  echo -e `date` $MSG2 >> $LOG
fi

exit

Now we add this script, called ricktock, to our example application on OpenShift:

[me@localhost ~/insultapp]$ chmod +x .openshift/cron/minutely/ricktock
[me@localhost ~/insultapp]$ git add .openshift/cron/minutely/ricktock
[me@localhost ~/insultapp]$ git commit -m "Adding ricktock minutely Cron script"
[master 2548477] Adding ricktock minutely Cron script
 1 file changed, 18 insertions(+)
 create mode 100755 .openshift/cron/minutely/ricktock
[me@localhost ~/insultapp]$ git push

Once the script has been deployed (and we’ve waited a little while), we can see the glorious result in the application log output with the rhc tail command. This command reads the last lines of all the files in the log directory and sends the output to your local console:

[me@localhost ~/insultapp]$ rhc tail
==> python/logs/ricktock.log <==
Fri Mar 14 14:15:44 EST 2014 Never gonna give you up
Never gonna let you down
Never gonna run around and desert you

For more information about viewing application logs, see Log Access. For an example of a Cron script to back up your OpenShift database, see Writing a Cron Script.

Continuous Integration

Another capability you may wish to add to your OpenShift applications is support for continuous integration. In this section we will show how to create an instance of the open source Jenkins continuous integration server on OpenShift, as well as how to configure your apps to build on this server. It is also possible to build OpenShift applications on Travis CI, but that is an advanced discussion so it will not be covered in this book.

Before we can configure our OpenShift application to build on Jenkins, we need to create a Jenkins server app. While we are using a small gear again, given how memory-intensive Jenkins can be we highly recommend using a medium or large gear if you want to make heavy use of it. The process for this is the same as for any other OpenShift application; we can use rhc app create, as shown here:

[me@localhost ~/insultapp]$ cd ..
[me@localhost ~]$ rhc app create jenkins jenkins-1
Application Options
-------------------
  Domain:     osbeginnerbook
  Cartridges: jenkins-1
  Gear Size:  default
  Scaling:    no

Creating application 'jenkins' ... done

  Jenkins created successfully.  Please make note of these credentials:

   User: admin
   Password: iYddhaBUvg2m

Note:  You can change your password at: https://jenkins-osbeginnerbook.rhcloud
.com/me/configure

Waiting for your DNS name to be available ... done

Cloning into 'jenkins'...
The authenticity of host 'jenkins-osbeginnerbook.rhcloud.com (19.77.5.25)' can't
be established.
RSA key fingerprint is 54:68:65:46:6f:72:63:65:69:73:73:74:72:6f:6e:67.
Are you sure you want to continue connecting (yes/no)? yes
Warning: Permanently added 'jenkins-osbeginnerbook.rhcloud.com,19.77.5.25' (RSA)
to the list of known hosts.

Your application 'jenkins' is now available.

  URL:        http://jenkins-osbeginnerbook.rhcloud.com/
  SSH to:     [e-mail]
  Git remote: ssh://[e-mail]/
  ~/git/jenkins.git/
  Cloned to:  /home/codemiller/code/book/jenkins

Run 'rhc show-app jenkins' for more details about your app.

Once we have a Jenkins server in our OpenShift domain we can add the client Jenkins cartridge to our example application. The client cartridge is used to indicate that you want to use your domain’s Jenkins server to build this application:

[me@localhost ~]$ cd insultapp
[me@localhost ~/insultapp]$ rhc cartridge add jenkins-client-1
Adding jenkins-client-1 to application 'insultapp' ... done

jenkins-client-1 (Jenkins Client)
---------------------------------
  Gears:   Located with python-2.7, postgresql-9.2, cron-1.4
  Job URL: https://jenkins-osbeginnerbook.rhcloud.com/job/insultapp-build/

Associated with job 'insultapp-build' in Jenkins server.

Adding the client cartridge has prompted OpenShift to create a job for the insult application, called insultapp-build, on the Jenkins server. When we push changes to OpenShift, the application will now be built on Jenkins. If the build and any tests are successful, the result will be deployed to the application gear or gears. If the build is unsuccessful, the OpenShift application will continue to run without downtime.

Tip

For more information about Jenkins, see the “Build with Jenkins” section on OpenShift.com.

Metrics and Monitoring

Another category of cartridges you may wish to add to support your application is cartidges for metrics collection and monitoring.

At the time of writing, the OpenShift Metrics cartridge was at version 0.1 and still under development. It is designed to be able to be embedded with any primary application cartridge type. To add it to your application, use the command rhc cartridge add metrics-0.1 -a appname. Once it is installed, you can access real-time statistics about your application’s resource usage at http://appname-domain.rhcloud.com/metrics, as shown in Figure 4-1. The cartridge gives visibility to some key information, including the amount of CPU and RAM use (and how that relates to the gear limit), how much swap space is being utilized, application process IDs, and whether or not your application is in an idle state.

Figure 4-1. The OpenShift Metrics cartridge interface

Another monitoring option is the Monit cartridge, which uses the open source Monit process supervision tool. The cartridge comes with some predefined rules for checking OpenShift application availability, storage, and memory use. It will send email notifications when significant events occur, such as your gear reaching 80 percent of its quota or your app becoming unavailable. Additional rules can be added to check different application metrics and to take actions based on the results, such as restarting a cartridge. See Adding Third-Party Cartridges to learn how to install Monit and other community cartridges.

If your OpenShift application is scalable, it will include the HAProxy cartridge for load balancing. Although its primary function is not monitoring, it is worth noting that HAProxy includes a page that allows you to view some useful data about your application, available at http://appname-domain.rhcloud.com/haproxy-status. This status page shows how many application gears you have running, if all the gears are online, how many users are connecting to your app, and how much data the app is streaming.

Tip

For those using MongoDB, another monitoring cartridge that may come in handy is the MongoDB Monitoring Service (MMS) cartridge.

Given that OpenShift is open source, new cartridges are being developed by the community all the time; the next section offers tips on finding them and shows how to utilize third-party cartridges.

Tip

OpenShift partner organization New Relic offers a mature application monitoring solution, with free standard accounts available. There was no New Relic OpenShift cartridge at the time of writing, but there are instructions on how to add New Relic to your Java/JBoss application. Another OpenShift partner, AppDynamics, has created an OpenShift QuickStart for its monitoring software.

Finding Cartridges and QuickStarts

One of the joyous consequences of having an open source platform is that the community is always creating exciting new things for it. When you run the command rhc cartridge list, the result shows supported cartridges (Table 4-1 shows the list as of March 2014); these are the components that are maintained by Red Hat and receive updates such as security patches. However, this is not the extent of the cartridges available. There are many more OpenShift cartridges that have been created by the community and partner organizations. There are also many QuickStarts, which combine one or more cartridges with preconfigured code and libraries to enable you to quickly and easily launch a given application on OpenShift.

Table 4-1. Supported cartridges for OpenShift Online (as of March 2014)

[me@localhost ~]$ rhc cartridge list
jbossas-7	JBoss Application Server 7	web
jbosseap-6 (*)	JBoss Enterprise Application Platform 6	web
jenkins-1	Jenkins Server	web
nodejs-0.10	Node.js 0.10	web
nodejs-0.6	Node.js 0.6	web
perl-5.10	Perl 5.10	web
php-5.3	PHP 5.3	web
zend-5.6	PHP 5.3 with Zend Server 5.6	web
php-5.4	PHP 5.4	web
zend-6.1	PHP 5.4 with Zend Server 6.1	web
python-2.6	Python 2.6	web
python-2.7	Python 2.7	web
python-3.3	Python 3.3	web
ruby-1.8	Ruby 1.8	web
ruby-1.9	Ruby 1.9	web
jbossews-1.0	Tomcat 6 (JBoss EWS 1.0)	web
jbossews-2.0	Tomcat 7 (JBoss EWS 2.0)	web
diy-0.1	Do-It-Yourself 0.1	web
10gen-mms-agent-0.1	10gen Mongo Monitoring Service Agent	addon
cron-1.4	Cron 1.4	addon
jenkins-client-1	Jenkins Client	addon
mongodb-2.4	MongoDB 2.4	addon
mysql-5.1	MySQL 5.1	addon
mysql-5.5	MySQL 5.5	addon
metrics-0.1	OpenShift Metrics 0.1	addon
phpmyadmin-4	phpMyAdmin 4.0	addon
postgresql-8.4	PostgreSQL 8.4	addon
postgresql-9.2	PostgreSQL 9.2	addon
rockmongo-1.1	RockMongo 1.1	addon
switchyard-0	SwitchYard 0.8.0	addon
haproxy-1.4	Web Load Balancer	addon

(*) denotes a cartridge with additional usage costs.

Tip

Web cartridges can be added only to new applications.

There are several places you can go to look for OpenShift cartridges and QuickStarts. A decent place to start is OpenShift.com; some downloadable cartridges and many QuickStarts are listed there. You can browse the OpenShift-maintained offerings and some partner and community offerings in the OpenShift Web Console.

Another good website to help you find ready-made applications and app components is the OO-Index. Its sole purpose is to index OpenShift cartridges and QuickStarts.It was in active development at the time of this writing and the production URL was not yet known, but you should be able to find the link at OpenShift’s website.

Given that a lot of cartridge code is hosted on GitHub, another way of finding a cartridge or QuickStart for a particular technology is to search for OpenShift and the technology name on the GitHub website. Search engine results may also help you to unearth treasures, especially if the programmers have written blog posts about their work.

Tip

If you cannot find an existing cartridge or QuickStart for the programming language, framework, or other technology you want to run on OpenShift, it does not mean all hope is lost. Most things that can run on Red Hat Enterprise Linux can run on OpenShift. You may be able to use the DIY cartridge (available via rhc app create) and install the technology manually. For example, Steve has written a blog post on how to run Minecraft on OpenShift. Alternatively, you could create your own cartridge. Demonstrating how to create cartridges is beyond the scope of this book.

Popular downloadable cartridges and QuickStarts include:

• ActiveMQ
• Django
• Drupal
• Flask
• Ghost
• Go
• Jekyll
• Rails
• Redis
• Spring
• Vert.x
• WordPress

Adding Third-Party Cartridges

To add a third-party cartridge to your application, you need to provide RHC with the URL to its manifest file, which will be called manifest.yml. This file is found within the metadata directory in the cartridge source repository. You can use this URL in RHC commands instead of a cartridge type such as python-3.3 or postgresql-9.2; it can be used with the rhc app create and rhc cartridge add commands.

For example, to add the Monit cartridge mentioned in Metrics and Monitoring to our Insult App application, we could use the following command (alternatively, we could use the shorter version that redirects to the manifest URL, which the cartridge author provided in the documentation):

[me@localhost ~/insultapp]$ rhc cartridge add https://raw2.github.com/mfojtik/
openshift-origin-cartridge-monit/master/metadata/manifest.yml
The cartridge 'https://raw2.github.com/mfojtik/openshift-origin-cartridge-monit/
master/metadata/manifest.yml' will be downloaded and installed
Adding https://raw2.github.com/mfojtik/openshift-origin-cartridge-monit/master/
metadata/manifest.yml to application 'insultapp' ... done

mfojtik-monit-5.6 (monit 5.6)
-----------------------------
  From:  https://raw2.github.com/mfojtik/openshift-origin-cartridge-monit/master/
  metadata/manifest.yml
  Gears: Located with python-2.7, postgresql-9.2, cron-1.4

Please set the email you want to receive monit alerts:

$ rhc env set MONIT_ALERT_EMAIL=[e-mail] -a insultapp
$ rhc cartridge restart monit -a insultapp

Monit Server Manager is running at: https://insultapp-osbeginnerbook.rhcloud.com/
monit-status
Username: admin
Password: Ny4nc=pt

You can add custom monitoring rules by editing ~/.monitrc file

Warning

Unlike the supported cartridges maintained by OpenShift, community cartridges do not receive automatic security updates and upgrades.

If we later wish to remove the cartridge, we can reference it with the short name provided, as shown here:

[me@localhost ~/insultapp]$ rhc cartridge remove mfojtik-monit-5.6
Removing a cartridge is a destructive operation that may result in loss of data
associated with the cartridge.

Are you sure you wish to remove mfojtik-monit-5.6 from 'insultapp'? (yes|no):
yes

Removing mfojtik-monit-5.6 from 'insultapp' ... removed

In this chapter, we have seen how to go beyond the required web cartridge to add extra components to an OpenShift application. Additional cartridges can be used to provide databases, metrics and monitoring, job scheduling, and other useful capabilities. OpenShift Online provides a suite of supported cartridges that receive automatic updates; however, there are also an array of partner-provided and community cartridges and QuickStart applications available. Furthermore, developers can create their own cartridges to bring new technologies to OpenShift; the Cartridge Developer’s Guide details how to do so.

In the next chapter, we will show how to perform a mixed bag of tasks for managing your OpenShift application, such as accessing your gears and database via SSH, viewing the logs, and setting environment variables.