This repository has been archived by the owner. It is now read-only.
Permalink
Switch branches/tags
tuned-profiles-openshift-node-0.2.1-1 tuned-profiles-openshift-node-0.1.2-1 tuned-profiles-openshift-node-0.1.1-1 stickshift-selinux-1.0.3-1 stickshift-selinux-1.0.2-1 stickshift-selinux-1.0.1-1 stickshift-selinux-0.1.1-1 stickshift-port-proxy-0.3.3-1 stickshift-port-proxy-0.3.2-1 stickshift-port-proxy-0.3.1-1 stickshift-port-proxy-0.2.4-1 stickshift-port-proxy-0.2.3-1 stickshift-port-proxy-0.2.2-1 stickshift-port-proxy-0.2.1-1 stickshift-port-proxy-0.1.4-1 stickshift-port-proxy-0.1.3-1 stickshift-port-proxy-0.1.2-1 stickshift-port-proxy-0.1.1-1 stickshift-port-proxy-0.0.2-1 stickshift-port-proxy-0.0.1-1 stickshift-mcollective-agent-0.4.3-1 stickshift-mcollective-agent-0.4.2-1 stickshift-mcollective-agent-0.4.1-1 stickshift-mcollective-agent-0.3.2-1 stickshift-mcollective-agent-0.3.1-1 stickshift-mcollective-agent-0.2.2-1 stickshift-mcollective-agent-0.2.1-1 stickshift-mcollective-agent-0.1.6-1 stickshift-mcollective-agent-0.1.5-1 stickshift-mcollective-agent-0.1.4-1 stickshift-mcollective-agent-0.1.3-1 stickshift-mcollective-agent-0.1.2-1 stickshift-mcollective-agent-0.1.1-1 stickshift-mcollective-agent-0.0.5-1 stickshift-mcollective-agent-0.0.4-1 stickshift-mcollective-agent-0.0.3-1 stickshift-mcollective-agent-0.0.2-1 stickshift-mcollective-agent-0.0.1-1 stickshift-broker-0.6.10-1 stickshift-broker-0.6.9-1 stickshift-broker-0.6.8-1 stickshift-broker-0.6.7-1 stickshift-broker-0.6.6-1 stickshift-broker-0.6.5-1 stickshift-broker-0.6.4-1 stickshift-broker-0.6.3-1 stickshift-abstract-0.17.9-1 stickshift-abstract-0.17.8-1 stickshift-abstract-0.17.7-1 stickshift-abstract-0.17.6-1 stickshift-abstract-0.17.5-1 stickshift-abstract-0.17.4-1 stickshift-abstract-0.17.3-1 stickshift-abstract-0.17.2-1 stickshift-abstract-0.17.1-1 stickshift-abstract-0.16.4-1 stickshift-abstract-0.16.3-1 stickshift-abstract-0.16.2-1 stickshift-abstract-0.16.1-1 stickshift-abstract-0.15.7-1 stickshift-abstract-0.15.6-1 stickshift-abstract-0.15.5-1 stickshift-abstract-0.15.4-1 stickshift-abstract-0.15.3-1 stickshift-abstract-0.15.2-1 stickshift-abstract-0.15.1-1 stickshift-abstract-0.14.9-1 stickshift-abstract-0.14.8-1 stickshift-abstract-0.14.6-1 stickshift-abstract-0.14.5-1 stickshift-abstract-0.14.4-1 stickshift-abstract-0.14.3-1 stickshift-abstract-0.14.2-1 stickshift-abstract-0.14.1-1 stickshift-abstract-0.13.7-1 stickshift-abstract-0.13.6-1 stickshift-abstract-0.13.5-1 stickshift-abstract-0.13.4-1 stickshift-abstract-0.13.2-1 stickshift-abstract-0.13.1-1 stickshift-abstract-0.12.5-1 stickshift-abstract-0.12.4-1 stickshift-abstract-0.12.3-1 stickshift-abstract-0.12.2-1 stickshift-abstract-0.12.1-1 stickshift-abstract-0.11.9-1 stickshift-abstract-0.11.8-1 stickshift-abstract-0.11.7-1 stickshift-abstract-0.11.6-1 stickshift-abstract-0.11.5-1 stickshift-abstract-0.11.4-1 stickshift-abstract-0.11.3-1 stickshift-abstract-0.11.2-1 stickshift-abstract-0.11.1-1 stickshift-abstract-0.10.5-1 stickshift-abstract-0.10.4-1 stickshift-abstract-0.10.3-1 stickshift-abstract-0.10.2-1 stickshift-abstract-0.10.1-1 stickshift-abstract-0.9.6-1
Nothing to show
Find file Copy path
2522 lines (1814 sloc) 109 KB

OpenShift Origin User’s Guide

Table of Contents

Platform as a Service is changing the way developers approach developing software. Developers typically use a local sandbox with their preferred application server and only deploy locally on that instance. For instance, developers typically start JBoss EAP locally using the startup.sh command and drop their .war or .ear file in the deployment directory and they are done. Developers have a hard time understanding why deploying to the production infrastructure is such a time consuming process.

System Administrators understand the complexity of not only deploying the code, but procuring, provisioning and maintaining a production level system. They need to stay up to date on the latest security patches and errata, ensure the firewall is properly configured, maintain a consistent and reliable backup and restore plan, monitor the application and servers for CPU load, disk IO, HTTP requests, etc.

OpenShift Origin provides developers and IT organizations an open source auto-scaling cloud application platform for quickly deploying new applications on secure and scalable resources with minimal configuration and management headaches. This means increased developer productivity and a faster pace in which IT can support innovation.

Building Apps on OpenShift Origin

This document assumes that you are working against an OpenShift Origin installation that is distinct from OpenShift Online (http://www.openshift.com). If you do not have OpenShift Origin yet, you will want to refer to the OpenShift Origin Installation Guide.

How is OpenShift Origin Different from OpenShift Online?

The rhc tools work interchangeably with OpenShift Online and OpenShift Origin, however, OpenShift Origin gives the administrator complete flexibility in assigning resources (like RAM and disk space) to application gears. OpenShift Origin can also be deployed on a private network, making it a better fit for enterprise and secure development environments.

1. Setting Up a Development Environment

Servers used
  • localhost

Tools used
  • rhc

In order to work with OpenShift applications from the command line, you will need to install the rhc utility on your client system. See the Client Tools installation Guide for instructions on how to do this.

1.1. Configuring rhc

By default, the RHC command line tool will attempt to connect the publicly hosted OpenShift environment at www.openshift.com. If you are going to work against a different OpenShift deployment, you will need to tell rhc where the deployment’s Broker host can be found. To provide this information, run the setup command with the --server flag:

$ rhc setup --server <broker hostname>

Getting to a Broker Running Inside a Virtual Machine
If you are running OpenShift Origin from the all-in-one VM, you will need to experiment to determine the best way to communicate with the Broker inside. In a recent troubleshooting session, we found that external rhc clients could not connect to an Origin virtual machine with a NATed network configuration. Using a "bridged" network configuration seemed to solve the problem. The specific network configuration options will vary by virtual machine service (Virtual Box, VMWare, etc.)

Once you enter in that command, you will be prompted for the username that you would like to authenticate with. If you are using the OpenShift Origin virtual machine, you can authenticate with user "demo", password "changeme".

The next step in the setup process is to create and upload our SSH key to the broker server. This is required for pushing your source code, via git, up to the OpenShift Origin server.

Finally, you will be asked to create a namespace for the provided user account. The namespace is a unique name which becomes part of your application URL. It is also commonly referred to as the users domain. The namespace can be at most 16 characters long and can only contain alphanumeric characters. There is currently a 1:1 relationship between usernames and namespaces. For the examples in the document, the namespace <yourdomain> will be used.

1.2. What rhc setup Does

This utility ensures that the user’s operating system is configured properly to create and manage applications from the command line. Additionally, it creates a .openshift directory in the user’s home directory and places a file there called express.conf. The contents of that file are as follows:

# Default user login
default_rhlogin='<your username>'

# Server API
libra_server = '<your Broker hostname or IP>'

This information will be provided to the rhc command line tool for every future command that is issued. If you want to run commands as a different user than the one listed above, you can either change the default login in this file or provide the -l switch to the rhc command.

2. Application Development

Servers used
  • localhost

  • node host

Tools used
  • rhc

Having completed the rhc setup, we are ready to start using OpenShift Origin to create our first application. To create an application, we will be using rhc app. In order to view all of the available setting options, enter the following command:

$ rhc app -h

This will provide you with the following output:

Creates and controls an OpenShift application.  To see the list of all applications use the rhc domain show command.
Note that delete is not reversible and will stop your application and then remove the application and repo from the
remote server. No local changes are made.

List of Actions
  configure     Configure several properties that apply to an application
  create        Create an application
  delete        Delete an application from the server
  deploy        Deploy a git reference or binary file of an application
  force-stop    Stops all application processes
  reload        Reload the application's configuration
  restart       Restart the application
  show          Show information about an application
  start         Start the application
  stop          Stop the application
  tidy          Clean out the application's logs and tmp directories and tidy up the git repo on the server

2.1. Create a New Application

The command to create an application is rhc app create and it requires two mandatory arguments:

  • Application Name: The name of the application. The application name can only contain alpha-numeric characters and at max contain only 32 characters.

  • Cartridge: The cartridge type that specifies which language runtime to use.

If you haven’t done so, create a directory to hold your OpenShift code projects:

$ cd ~
$ mkdir apps
$ cd apps

To create an application called "firstphp" that uses the php runtime, issue the following command:

$ rhc app create firstphp php-5.3

After entering that command, you should output similar to:

 Application Options
 -------------------
  Domain:     <yourdomain>
  Cartridges: php-5.3
  Gear Size:  default
  Scaling:    no

Creating application 'firstphp' ... done


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

Cloning into 'firstphp'...
The authenticity of host 'firstphp-<yourdomain>.<appsdomain>.com (1.1.1.1)' can't be established.
RSA key fingerprint is aa:11:aa:11:aa:11:aa:11:aa:11:aa:11:aa:11:aa:11.
Are you sure you want to continue connecting (yes/no)? yes
Warning: Permanently added 'firstphp-<yourapp>.<appsdomain>.com,1.1.1.1' (RSA) to the list of known hosts.
Checking connectivity... done

Your application 'firstphp' is now available.

  URL:        http://firstphp-<yourdomain>.<appsdomain>.com/
  SSH to:     01aa10a0110111a01100a011@firstphp-<yourdomain>.<appsdomain>.com
  Git remote: ssh://01aa10a0110111a01100a011@firstphp-<yourdomain>.<appsdomain>.com/~/git/firstphp.git/
  Cloned to:  /home/<you>/apps/firstphp

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

You should also be able to verify that your application was created correctly by opening up a web browser and entering the following URL:

http://firstphp-<yourdomain>.example.com

You should see the default template that OpenShift Origin uses for a new application.

image

2.2. What rhc app create Does

After you entered the command to create a new PHP application, a lot of things happened under the covers:

  • A request was made to the broker application host to create a new php application

  • A message was dropped using MCollective and ActiveMQ to find a node host to handle the application creation request

  • A node host responded to the request and created an application / gear for you

  • All SELinux and cgroup policies were enabled for your application gear

  • A userid was created for your application gear

  • A private git repository was created for your gear on the node host

  • The git repository was cloned on your local machine

  • BIND was updated on the broker host to include an entry for your application

2.3. Node Host Directory Structure

It is important to understand the directory structure of each OpenShift Origin application gear. For the PHP application that we just created, we can verify and examine the layout of the gear on the node host. SSH to your node host and execute the following commands:

# cd /var/lib/openshift
# ls

You will see output similar to the following:

e9e92282a16b49e7b78d69822ac53e1d

The above is the unique user id that was created for your application gear. Lets examine the contents of this gear by using the following commands:

# cd e9e92282a16b49e7b78d69822ac53e1d
# ls -al

You should see the following directories:

total 44
drwxr-x---.  9 root e9e92282a16b49e7b78d69822ac53e1d 4096 Jan 21 13:47 .
drwxr-xr-x.  5 root root                             4096 Jan 21 13:47 ..
drwxr-xr-x.  4 root e9e92282a16b49e7b78d69822ac53e1d 4096 Jan 21 13:47 app-root
drwxr-x---.  3 root e9e92282a16b49e7b78d69822ac53e1d 4096 Jan 21 13:47 .env
drwxr-xr-x.  3 root root                             4096 Jan 21 13:47 git
-rw-r--r--.  1 root root                               56 Jan 21 13:47 .gitconfig
-rw-r--r--.  1 root root                             1352 Jan 21 13:47 .pearrc
drwxr-xr-x. 10 root root                             4096 Jan 21 13:47 php-5.3
d---------.  3 root root                             4096 Jan 21 13:47 .sandbox
drwxr-x---.  2 root e9e92282a16b49e7b78d69822ac53e1d 4096 Jan 21 13:47 .ssh
d---------.  3 root root                             4096 Jan 21 13:47 .tmp
[root@node e9e92282a16b49e7b78d69822ac53e1d]#

During the rhc setup, our SSH key was uploaded to the server to enable us to authenticate to the system without having to provide a password. The SSH key we provided was actually appended to the authorized_keys file. To verify this, use the following command to view the contents of the file:

# cat .ssh/authorized_keys

You will also notice the following three directories:

  • app-root - Contains your core application code as well as your data directory where persistent data is stored.

  • git - Your private git repository that was created upon gear creation.

  • php-5.3 - The core PHP runtime and associated configuration files. Your application is served from this directory.

2.4. Localhost Directory Structure

When you created the PHP application using the rhc app create command, the private git repository that was created on your node host was cloned to your local machine.

$ cd firstphp
$ ls -al

You should see the following information:

total 8
drwxr-xr-x   9 gshipley  staff   306 Jan 21 13:48 .
drwxr-xr-x   3 gshipley  staff   102 Jan 21 13:48 ..
drwxr-xr-x  13 gshipley  staff   442 Jan 21 13:48 .git
drwxr-xr-x   5 gshipley  staff   170 Jan 21 13:48 .openshift
-rw-r--r--   1 gshipley  staff  2715 Jan 21 13:48 README
-rw-r--r--   1 gshipley  staff     0 Jan 21 13:48 deplist.txt
drwxr-xr-x   3 gshipley  staff   102 Jan 21 13:48 libs
drwxr-xr-x   3 gshipley  staff   102 Jan 21 13:48 misc
drwxr-xr-x   4 gshipley  staff   136 Jan 21 13:48 php

2.4.1. The .git Directory

If you are not familiar with the git revision control system, this is where information about the git repositories that you will be interacting with is stored. For instance, to list all of the repositories that you are currently setup to use for this project, issue the following command:

$ cat .git/config

You should see the following information which specifies the URL for our repository that is hosted on the OpenShift Origin node host:

[core]
    repositoryformatversion = 0
    filemode = true
    bare = false
    logallrefupdates = true
    ignorecase = true
[remote "origin"]
    fetch = +refs/heads/*:refs/remotes/origin/*
    url = ssh://e9e92282a16b49e7b78d69822ac53e1d@firstphp-<yourdomain>.example.com/~/git/firstphp.git/
[branch "master"]
    remote = origin
    merge = refs/heads/master
[rhc]
    app-uuid = e9e92282a16b49e7b78d69822ac53e1d
Note
You are also able to add other remote repositories. This is useful for developers who also use github or have private git repositories for an existing code base.

2.4.2. The .openshift Directory

The .openshift directory is a hidden directory where a user can create action hooks, set markers, and create cron jobs.

Action hooks are scripts that are executed directly so can be written in Python, PHP, Ruby, shell, etc. OpenShift Origin supports the following action hooks:

Table 1. Action Hooks
Action Hook Description

pre_build

Executed on your CI system if available. Otherwise, executed before the build step

build

Executed on your CI system if available. Otherwise, executed before the deploy step

prepare

Executed just prior to a deployment ID being calculated and before the deployment is ready to use

deploy

Executed after dependencies are resolved but before application has started

post_deploy

Executed after application has been deployed and started

Note: On Windows, the execute permissions of an action hook files will be lost during the git push. To fix this problem, you can run this command:

# git update-index --chmod=+x .openshift/action_hooks/*
# git push

OpenShift Origin also supports the ability for a user to schedule jobs to be ran based upon the familiar cron functionality of linux. Any scripts or jobs added to the minutely, hourly, daily, weekly or monthly directories will be ran on a scheduled basis (frequency is as indicated by the name of the directory) using run-parts. OpenShift supports the following schedule for cron jobs:

  • daily

  • hourly

  • minutely

  • monthly

  • weekly

The markers directory will allow the user to specify settings such as enabling hot deployments or which version of Java to use.

2.4.3. The libs directory

The libs directory is a location where the developer can provide any dependencies that are not able to be deployed using the standard dependency resolution system for the selected runtime. In the case of PHP, the standard convention that OpenShift Origin uses is providing PEAR modules in the deplist.txt file.

2.4.4. The misc directory

The misc directory is a location provided to the developer to store any application code that they do not want exposed publicly.

2.4.5. The php directory

The php directory is where all of the application code that the developer writes should be created. By default, two files are created in this directory:

  • index.php - The OpenShift template that we saw after application creation in the web browser.

2.5. Environment Variables

OpenShift builds the execution environment which is made available to application scripts and other code. The environment contains a variety of variables related to OpenShift and the application itself which can only be determined at runtime. In addition to the standard environment variables exposed to the application, cartridges may also expose custom variables for the application to consume; consult the specific cartridge documentation for more information about what the cartridge makes available.

2.5.1. Standard OpenShift Environment Variables

The following is a comprehensive list of the predefined environment variables available regardless of the cartridges in use for a given application.

  • HOME alias for OPENSHIFT_HOMEDIR

  • HISTFILE bash history file

  • OPENSHIFT_APP_DNS the application’s fully qualified domain name that your cartridge is a part of

  • OPENSHIFT_APP_NAME the validated user assigned name for the application. Black list is system dependent.

  • OPENSHIFT_APP_UUID OpenShift assigned UUID for the application

  • OPENSHIFT_DATA_DIR the directory where your cartridge may store data

  • OPENSHIFT_GEAR_DNS the gear’s fully qualified domain name that your cartridge is a part of. May or may not be equal to OPENSHIFT_APP_DNS

  • OPENSHIFT_GEAR_NAME OpenShift assigned name for the gear. May or may not be equal to OPENSHIFT_APP_NAME

  • OPENSHIFT_GEAR_UUID OpenShift assigned UUID for the gear

  • OPENSHIFT_HOMEDIR OpenShift assigned directory for the gear

  • OPENSHIFT_REPO_DIR the directory where the developer’s application is "archived" to and will be run from.

  • OPENSHIFT_TMP_DIR the directory where your cartridge may store temporary data

  • TMPDIR alias for OPENSHIFT_TMP_DIR

  • TMP alias for OPENSHIFT_TMP_DIR

2.5.2. Cartridge-Specific Environment Variables

Although cartridges may expose further arbitrarily named environment variables, there are several variables which are generated by OpenShift for every cartridge based on well-defined standards incorporating cartridge metadata.

To learn more about these variables, consult the following pieces of documentation from the Cartridge Author guide.

2.6. Modifying and Deploying Updated Code

To get a good understanding of the development workflow for a user, let’s change the contents of the index.php template that is provided on the newly created gear. Edit the file and look for the following code block:

<h1>
    Welcome to OpenShift
</h1>

Update this code block to the following and then save your changes:

<h1>
    Welcome to OpenShift Origin
</h1>

Once the code has been changed, we need to commit our change to the local git repository. This is accomplished with the git commit command:

$ git commit -am "Changed welcome message."

Now that our code has been committed to our local repository, we need to push those changes up to our repository that is located on the node host.

$ git push

You should see the following output:

Counting objects: 7, done.
Delta compression using up to 8 threads.
Compressing objects: 100% (4/4), done.
Writing objects: 100% (4/4), 395 bytes, done.
Total 4 (delta 2), reused 0 (delta 0)
remote: restart_on_add=false
remote: httpd: Could not reliably determine the server's fully qualified domain name, using node.example.com for ServerName
remote: Waiting for stop to finish
remote: Done
remote: restart_on_add=false
remote: ~/git/firstphp.git ~/git/firstphp.git
remote: ~/git/firstphp.git
remote: Running .openshift/action_hooks/pre_build
remote: Running .openshift/action_hooks/build
remote: Running .openshift/action_hooks/deploy
remote: hot_deploy_added=false
remote: httpd: Could not reliably determine the server's fully qualified domain name, using node.example.com for ServerName
remote: Done
remote: Running .openshift/action_hooks/post_deploy
To ssh://e9e92282a16b49e7b78d69822ac53e1d@firstphp-<yourdomain>.example.com/~/git/firstphp.git/
   3edf63b..edc0805  master -> master

Notice that we stop the application runtime (Apache), deploy the code, and then run any action hooks that may have been specified in the .openshift directory.

Verifying Code Changes
If you have completed all of the steps in this chapter correctly, you should be able to verify that your application was deployed correctly by opening up a web browser and entering the following URL:

http://firstphp-<yourdomain>.example.com

You should see the updated code for the application.

image

2.7. Adding a New PHP File

Adding a new source code file to your OpenShift Origin application is an easy and straightforward process. For instance, to create a PHP source code file that displays the server date and time, create a new file located in php directory and name it time.php. After creating this file, add the following contents:

<?php
// Print the date and time
echo date('l jS \of F Y h:i:s A');
?>

Once you have saved this file, the process for pushing the changes involve adding the new file to your git repository, committing the change, and then pushing the code to your OpenShift Origin gear:

$ git add .
$ git commit -am "Adding time.php"
$ git push

Verifying Code Changes
To verify that we have created and deployed the new PHP source file correctly, open up a web browser and enter the following URL:

http://firstphp-<yourdomain>.example.com/time.php

You should see the updated code for the application.

image

2.8. Action Hooks

OpenShift provides application developers entry points into various application and platform lifecycle operations. These entry points are referred to as "action hooks", and have a special location within the application’s Git repository:

<repository>/.openshift/action_hooks

During any OpenShift process which supports an action hook, the application action hook directory will be checked for an executable file matching the specified name. If such a file is present, it will be executed before returning control to the process.

Unless otherwise documented, OpenShift generally imposes no implementation requirement on action hooks other than they be executable files.

These scripts will be executed by the system directly. See Notes on Script Execution in the Cartridge Developers Guide for more information.

2.8.1. Cartridge Control Action Hooks

Cartridges implement a standard set of named control actions which allow them to function within OpenShift. Each time OpenShift invokes one of these cartridge actions, a standard set of application action hooks are executed to give the application developer an opportunity to integrate more closely with specific cartridges.

To use these hooks in your application create a file in:

<repository>/.openshift/action_hooks

with the same name as the event you want to trigger.

Note
Cartridge-scoped action hooks are special in that they are sourced in into the same shell environment used to execute the action they surround. This allows cartridge hooks to modify the environment the action executes within.

All the hooks listed below are available to application developers as well cartridge developers. The order of execution will be first the platform/cartridge script and then the application developers.

The following is a list of all possible action hooks executed in association with a single cartridge control action. For each control action, a set of pre and post action hooks surround the control action. In the action hook names, {Name} refers to the Name cartridge manifest element.

  • start control action:

    • pre_start

    • pre_start_{Name} [1]

    • post_start

    • post_start_{Name} [1]

  • stop control action:

    • pre_stop

    • pre_stop_{Name} [1]

    • post_stop

    • post_stop_{Name} [1]

  • reload control action:

    • pre_reload

    • pre_reload_{Name} [1]

    • post_reload

    • post_reload_{Name} [1]

  • restart control action:

    • pre_restart

    • pre_restart_{Name} [1]

    • post_restart

    • post_restart_{Name} [1]

  • tidy control action:

    • pre_tidy

    • pre_tidy_{Name} [1]

    • post_tidy

    • post_tidy_{Name} [1]

For details about the control actions (including what they represent and when they are called), refer to the control script documentation in the Cartridge Developers Guide guide.

2.8.2. Build Action Hooks

During a Git push, applications using the default OpenShift build lifecycle are given an opportunity to participate in the build/deploy workflow via another set of action hooks. The workflow and sequence of actions for the build lifecycle is described in detail in the OpenShift Builds section of the Cartridge Developers Guide guide.

The list of action hooks supported during the default build lifecycle are:

  • pre_build

  • build

  • deploy

  • post_deploy

Refer to the OpenShift Builds guide for details about when these action hooks are invoked.

2.8.3. Custom Cartridge Action Hooks

Cartridges may support custom action hooks available to application developers. Consult the documentation for individual cartridges to learn which hooks are supported and how to correctly implement them.

3. Application Management

Servers used
  • localhost

  • node host

Tools used
  • rhc

3.1. Start, Stop and Restart

OpenShift Origin provides commands to start,stop, and restart an application. If at any point in the future you decided that an application should be stopped for some maintenance, you can stop the application using the rhc app stop command. After making necessary maintenance tasks you can start the application again using the rhc app start command.

To stop an application execute the following command:

$ rhc app stop -a firstphp

RESULT:
firstphp stopped

Verify that your application has been stopped with the following curl command:

$ curl http://firstphp-<yourdomain>.example.com/health

<!DOCTYPE HTML PUBLIC "-//IETF//DTD HTML 2.0//EN">
<html><head>
<title>503 Service Temporarily Unavailable</title>
</head><body>
<h1>Service Temporarily Unavailable</h1>
<p>The server is temporarily unable to service your
request due to maintenance downtime or capacity
problems. Please try again later.</p>
<hr>
<address>Apache/2.2.15 (Red Hat) Server at myfirstapp-<yourdomain>.example.com Port 80</address>
</body></html>

To start the application back up, execute the following command:

$ rhc app start -a firstphp

RESULT:
firstphp started

Verify that your application has been started with the following curl command:

$ curl http://firstphp-<yourdomain>.example.com/health

1

You can also stop and start the application in one command as shown below.

$ rhc app restart -a firstphp

RESULT:
firstphp restarted

3.2. View Application Details

All of the details about an application can be viewed by the rhc app show command. This command will list when the application was created, unique identifier of the application, git URL, SSH URL, and other details as shown below:

$ rhc app show -a firstphp
Password: ****


firstphp @ http://firstphp-<yourdomain>.example.com/
===========================================
  Application Info
  ================
    UUID      = e9e92282a16b49e7b78d69822ac53e1d
    Git URL   = ssh://e9e92282a16b49e7b78d69822ac53e1d@firstphp-<yourdomain>.example.com/~/git/firstphp.git/
    Gear Size = small
    Created   = 1:47 PM
    SSH URL   = ssh://e9e92282a16b49e7b78d69822ac53e1d@firstphp-<yourdomain>.example.com
  Cartridges
  ==========
    php-5.3

3.3. View Application Status

The state of application gears can be viewed by passing the state switch to the rhc app show command as shown below:

rhc app show --state -a firstphp
Password: ****


RESULT:
Geargroup php-5.3 is started

3.4. Clean Up an Application

As users start developing an application and deploying changes to OpenShift Origin, the application will start consuming some of the available disk space that is part of their quota. This space is consumed by the git repository, log files, temp files, and unused application libraries. OpenShift Origin provides a disk space cleanup tool to help users manage the application disk space. This command is also available under rhc app and performs the following functions:

  • Runs the git gc command on the application’s remote git repository

  • Clears the application’s /tmp and log file directories. These are specified by the application’s OPENSHIFT_LOG_DIR* and OPENSHIFT_TMP_DIR environment variables.

  • Clears unused application libraries. This means that any library files previously installed by a git push command are removed.

To clean up the disk space on your application gear, run the following command:

$ rhc app tidy -a firstphp

3.5. SSH to an Application Gear

OpenShift allows remote access to the application gear by using the Secure Shell protocol (SSH). Secure Shell (SSH) is a network protocol for securely getting access to a remote computer. SSH uses RSA public key cryptography for both the connection and authentication. SSH provides direct access to the command line of your application gear on the remote server. After you are logged in on the remote server, you can use the command line to directly manage the server, check logs and test quick changes. OpenShift Origin uses SSH for:

  • Performing Git operations

  • Remote access your application gear

The SSH keys were generated and uploaded to OpenShift Origin during rhc setup. You can verify that SSH keys are uploaded by logging into the OpenShift Origin web console and clicking on the "My Account" tab as shown below.

image

Note
If you don’t see an entry under "Public Keys" then you can either upload the SSH keys by clicking on "Add a new key" or run the rhc setup command again. This will create a SSH key pair in /.ssh folder and upload the public key to the OpenShift Origin server.

After the SSH keys are uploaded, you can SSH into the application gear as shown below. SSH is installed by default on most UNIX like platforms such as Mac OS X and Linux. For windows, you can use PuTTY. Instructions for installing PuTTY can be found on the OpenShift website.

$ ssh UUID@appname-namespace.example.com

You can get the SSH URL by running rhc app show command as shown below:

$ rhc app show -a firstphp
Password: ****


firstphp @ http://firstphp-<yourdomain>.example.com/
===========================================
  Application Info
  ================
    Created   = 1:47 PM
    UUID      = e9e92282a16b49e7b78d69822ac53e1d
    SSH URL   = ssh://e9e92282a16b49e7b78d69822ac53e1d@firstphp-<yourdomain>.example.com
    Gear Size = small
    Git URL   = ssh://e9e92282a16b49e7b78d69822ac53e1d@firstphp-<yourdomain>.example.com/~/git/firstphp.git/
  Cartridges
  ==========
    php-5.3```

Now you can ssh into the application gear using the SSH URL shown above:

$ ssh e9e92282a16b49e7b78d69822ac53e1d@firstphp-<yourdomain>.example.com

    *********************************************************************

    You are accessing a service that is for use only by authorized users.
    If you do not have authorization, discontinue use at once.
    Any use of the services is subject to the applicable terms of the
    agreement which can be found at:
    https://openshift.redhat.com/app/legal

    *********************************************************************

    Welcome to OpenShift shell

    This shell will assist you in managing OpenShift applications.

    !!! IMPORTANT !!! IMPORTANT !!! IMPORTANT !!!
    Shell access is quite powerful and it is possible for you to
    accidentally damage your application.  Proceed with care!
    If worse comes to worst, delete your application with 'rhc app delete'
    and recreate it
    !!! IMPORTANT !!! IMPORTANT !!! IMPORTANT !!!

    Type "help" for more info.

You can also view all of the commands available on the application gear shell by running the help command as shown below:

[firstphp-<yourdomain>.example.com ~]\> help
Help menu: The following commands are available to help control your openshift
application and environment.

ctl_app         control your application (start, stop, restart, etc)
ctl_all         control application and deps like mysql in one command
tail_all        tail all log files
export          list available environment variables
rm              remove files / directories
ls              list files / directories
ps              list running applications
kill            kill running applications
mysql           interactive MySQL shell
mongo           interactive MongoDB shell
psql            interactive PostgreSQL shell
quota           list disk usage

3.6. View Log Files

Logs are very important when you want to find out why an error is happening or if you want to check the health of your application. OpenShift Origin provides the rhc tail command to display the contents of your log files. To view all the options available for the rhc tail command, issue the following:

$ rhc tail -h
Usage: rhc tail <application>

Tail the logs of an application

Options for tail
  -n, --namespace namespace Namespace of your application
  -o, --opts options        Options to pass to the server-side (linux based) tail command (applicable to tail command only) (-f is implicit.  See the linux tail man page full
list of options.) (Ex: --opts '-n 100')
  -f, --files files         File glob relative to app (default <application_name>/logs/*) (optional)
  -a, --app app             Name of application you wish to view the logs of

The rhc tail command requires that you provide the application name of the logs you would like to view. To view the log files of our firstphp application, use the following command:

$ rhc tail -a firstphp

You should see information for both the access and error logs. While you have the rhc tail command open, issue a HTTP get request by pointing your web browser to http://firstphp-<yourdomain>.example.com. You should see a new entry in the log files that looks similar to this:

10.10.56.204 - - [22/Jan/2013:18:39:27 -0500] "GET / HTTP/1.1" 200 5242 "-" "Mozilla/5.0 (Macintosh; Intel Mac OS X 10.8; rv:19.0) Gecko/20100101 Firefox/19.0"

The log files are also available on the gear node host in the php-5.3/logs directory.

3.7. View Disk Quota

The Comprehensive Deployment Guide discusses how to set disk quotas for applications. You can view the quota of your currently running gear by connecting to the gear node host via SSH. Once you are connected to your application gear, enter the following command:

$ quota -s

If the quota information that we configured earlier is correct, you should see the following information:

Disk quotas for user e9e92282a16b49e7b78d69822ac53e1d (uid 1000):
     Filesystem  blocks   quota   limit   grace   files   quota   limit   grace
/dev/mapper/VolGroup-lv_root
                  22540       0   1024M             338       0   80000

To view how much disk space your gear is actually using, you can also enter in the following:

$ du -h

3.8. Add a Custom Domain

OpenShift Origin supports the use of custom domain names for an application. For example, suppose we want to use http://www.somesupercooldomain.com domain name for the application firstphp (from the example in Create a New Application). The first thing you need to do before setting up a custom domain name is to buy the domain name from domain registration provider.

After buying the domain name, you have to add a CNAME record for the custom domain name. Once you have created the CNAME record, you can let OpenShift Origin know about the CNAME by using the rhc alias command.

$ rhc alias add firstphp www.mycustomdomainname.com

Technically, what OpenShift Origin has done under the hood is set up a virtual host in Apache to handle the custom URL.

3.9. Back Up an Application

Use the rhc snapshot save command to create backups of your OpenShift Origin application. This command creates a gzipped tar file of your application and of any locally-created log and data files. This snapshot is downloaded to your local machine and the directory structure that exists on the server is maintained in the downloaded archive.

$ rhc snapshot save -a firstphp
Password: ****

Pulling down a snapshot to firstphp.tar.gz...
Waiting for stop to finish
Done
Creating and sending tar.gz
Done

RESULT:
Success

After the command successfully finishes you will see a file named firstphp.tar.gz in the directory where you executed the command. The default filename for the snapshot is $Application_Name.tar.gz. You can override this path and filename with the -f or --filepath option.

Note
This command will stop your application for the duration of the backup process. NOTE: The application original state will be preserved, so if your application was stopped before doing snapshot, it will remain stopped after the snapshot is completed.

3.10. Delete an Application

You can delete an OpenShift Origin application by executing the rhc app delete command. This command deletes your application and all of its data on the OpenShift Origin server but leaves your local directory intact. This operation can not be undone so use it with caution.

$ rhc app delete -a someAppToDelete

Are you sure you wish to delete the 'someAppToDelete' application? (yes/no)
yes

Deleting application 'someAppToDelete'

RESULT:
Application 'someAppToDelete' successfully deleted

There is another variant of this command which does not require the user to confirm the delete operation. To use this variant, pass the --confirm flag.

$ rhc app delete --confirm -a someAppToDelete

Deleting application 'someAppToDelete'

RESULT:
Application 'someAppToDelete' successfully deleted

3.11. Restore From Backup

Not only you can take a backup of an application but you can also restore a previously saved snapshot. This form of the rhc command restores the git repository, as well as the application data directories and the log files found in the specified archive. When the restoration is complete, OpenShift Origin runs the deployment script on the newly restored repository. To restore an application snapshot, run the following command:

$ rhc snapshot restore -a firstphp -f firstphp.tar.gz
Note
This command will stop your application for the duration of the restore process. NOTE: This command will preserve the state of your application as it was before restore. If your application was stopped, before this command it will remain stopped after restore

Verify that the application has been restored
Open up a web browser and point to the following URL:

http://firstphp-<yourdomain>.example.com

If the restore process worked correctly, you should see the restored application just as it was before the delete operation.

3.12. View a Thread Dump

This can be performed on Ruby and JBoss EAP / JBoss EWS application types.

You can trigger a thread dump for Ruby and JBoss EAP / JBoss EWS applications using the rhc threaddump command. A thread dump is a snapshot of the state of all threads that are part of the runtime process. If an application appears to have stalled or is running out of resources, a thread dump can help reveal the state of the runtime, identify what might be causing any issues and ultimately to help resolve the problem. To trigger a thread dump execute the following command:

$ rhc threaddump -a ApplicationName

After running this command for a JBoss EAP, JBoss EWS or Ruby application, you will be given a log file that you can view in order to see the details of the thread dump. Issue the following command, substituting the correct log file:

$ rhc tail ApplicationName -f ruby-1.9/logs/error_log-20130104-000000-EST -o '-n 250'

4. Using Cartridges

Servers used
  • localhost

  • node host

Tools used
  • rhc

  • mysql

  • tail

  • git

  • PHP

Cartridges provide the actual functionality necessary to run applications. Currently, there are several cartridges available to support different programming languages, databases, monitoring and management. Cartridges are designed to be extensible so the community can add support for any programming language, database or any management tool not officially supported by OpenShift Origin. Please refer to the official OpenShift Origin documentation for how you can write your own cartridge.

4.1. View Available Cartridges

To view all of the available commands for working with cartridges on OpenShift Origin, enter the following command:

$ rhc cartridge -h

4.2. List Available Cartridges

To see a list of all available cartridges to users of this OpenShift Origin deployment, issue the following command:

$ rhc cartridge list

You should see the following output:

RESULT:
cron-1.4, mysql-5.5, haproxy-1.4, postgresql-8.4

4.3. Example: Add a MySQL Cartridge to an Application

In order to use a cartridge, we need to embed it into our existing application. As an example, we will add a MySQL cartridge. OpenShift Origin provides support for version 5.1 of this popular open source database. To enable MySQL support for the firstphp application, issue the following command:

$ rhc cartridge add mysql-5.5 -a firstphp

You should see the following output:

Password: *********

Adding 'mysql-5.5' to application 'firstphp'
Success
mysql-5.5
=========
  Properties
  ==========
    Username       = admin
    Password       = aFh_GsHP63fV
    Connection URL = mysql://127.1.244.1:3306/
    Database Name  = firstphp

4.3.1. Using MySQL

Developers will typically interact with MySQL by using the mysql shell command on OpenShift Origin. In order to use the mysql shell, refer to using SSH to connect to an application gear. Once you have been authenticated, issue the following command:

[firstphp-<yourdomain>.example.com ~]\> mysql

You will notice that you did not have to authenticate to the MySQL database. This is because OpenShift Origin sets environment variables that contains the connection information for the database.

When embedding the MySQL database, OpenShift Origin creates a default database based upon the application name. That being said, the user has full permissions to create new databases inside of MySQL. Let’s use the default database that was created for us and create a users table:

mysql> use firstphp;
Database changed

mysql> create table users (user_id int not null auto_increment, username varchar(200), PRIMARY KEY(user_id));
Query OK, 0 rows affected (0.01 sec)

mysql> insert into users values (null, 'gshipley@redhat.com');
Query OK, 1 row affected (0.00 sec)

Verify that the user record has been added by selecting all rows from the users table:

mysql> select * from users;
+---------+---------------------+
| user_id | username            |
+---------+---------------------+
|       1 | gshipley@redhat.com |
+---------+---------------------+
1 row in set (0.00 sec)

To exit out of the MySQL session, simply enter the exit command:

mysql> exit

4.3.2. MySQL Environment Variables

As mentioned above, OpenShift Origin creates environment variables that contain the connection information for your MySQL database. If a user forgets their connection information, they can always retrieve the authentication information by viewing these environment variables:

Execute the following on the application gear:

[firstphp-<yourdomain>.example.com ~]\> env |grep MYSQL

You should see the following information return from the command:

OPENSHIFT_MYSQL_DB_PORT=3306
OPENSHIFT_MYSQL_DB_HOST=127.1.244.1
OPENSHIFT_MYSQL_DB_PASSWORD=aFh_GsHP63fV
OPENSHIFT_MYSQL_DB_USERNAME=admin
OPENSHIFT_MYSQL_DB_SOCKET=/var/lib/openshift/e9e92282a16b49e7b78d69822ac53e1d//mysql-5.1/socket/mysql.sock
OPENSHIFT_MYSQL_DB_URL=mysql://admin:aFh_GsHP63fV@127.1.244.1:3306/
OPENSHIFT_MYSQL_DB_LOG_DIR=/var/lib/openshift/e9e92282a16b49e7b78d69822ac53e1d//mysql-5.1/log
OPENSHIFT_MYSQL_VERSION=5.5

To view a list of all OPENSHIFT environment variables, you can use the following command:

[firstphp-<yourdomain>.example.com ~]\> env | grep OPENSHIFT

4.3.3. Viewing MySQL Logs

Given the above information, you can see that the log file directory for MySQL is specified with the OPENSHIFT_MYSQL_DB_LOG_DIR environment variable. To view these log files, simply use the tail command:

[firstphp-<yourdomain>.example.com ~]\> tail -f $OPENSHIFT_MYSQL_DB_LOG_DIR/*

4.3.4. Connecting to the MySQL Cartridge from PHP

Now that we have verified that our MySQL database has been created correctly, and have created a database table with some user information, let’s connect to the database from PHP in order to verify that our application code can communicate to the newly embedded MySQL cartridge. Create a new file in the php directory of your firstphp application named dbtest.php. Add the following source code to the dbtest.php file:

<?php
$dbhost = getenv("OPENSHIFT_MYSQL_DB_HOST");
$dbport = getenv("OPENSHIFT_MYSQL_DB_PORT");
$dbuser = getenv("OPENSHIFT_MYSQL_DB_USERNAME");
$dbpwd = getenv("OPENSHIFT_MYSQL_DB_PASSWORD");
$dbname = getenv("OPENSHIFT_APP_NAME");

$connection = mysql_connect($dbhost, $dbuser, $dbpwd);

if (!$connection) {
        echo "Could not connect to database";
} else {
        echo "Connected to database.<br>";
}

$dbconnection = mysql_select_db($dbname);

$query = "SELECT * from users";

$rs = mysql_query($query);
while ($row = mysql_fetch_assoc($rs)) {
    echo $row['user_id'] . " " . $row['username'] . "\n";
}

mysql_close();

?>

Once you have created the source file, add the file to your git repository, commit the change, and push the change to your OpenShift Origin gear.

$ git add .
$ git commit -am "Adding dbtest.php"
$ git push

After the code has been deployed to your application gear, open up a web browser and enter the following URL:

http://firstphp-<yourdomain>.example.com/dbtest.php

You should see a screen with the following information:

Connected to database.
1 gshipley@redhat.com

4.4. Manage Cartridges

OpenShift Origin provides the ability to embed multiple cartridges in an application. For instance, even though we are using MySQL for our firstphp application, we could also embed the cron cartridge as well. It may be useful to stop, restart, or even check the status of a cartridge. To check the status of our MySQL database, use the following command:

$ rhc cartridge status -a firstphp -c mysql-5.5

To stop the cartridge, enter the following command:

$ rhc cartridge stop -a firstphp -c mysql-5.5

Verify that the MySQL database has been stopped by either checking the status again or viewing the following URL in your browser:

http://firstphp-<yourdomain>.example.com/dbtest.php

You should see the following message returned to your browser:

Could not connect to database

Start the database back up using the start switch.

$ rhc cartridge start -a firstphp -c mysql-5.5

OpenShift Origin also provides the ability to list important information about a cartridge by using the show switch. For example, if a user has forgotten their MySQL connection information, they can display this information with the following command:

$ rhc cartridge show mysql-5.5 -a firstphp

The user will then be presented with the following output:

Password: ****

mysql-5.5
=========
  Properties
  ==========
    Username       = admin
    Password       = aFh_GsHP63fV
    Database Name  = firstphp
    Connection URL = mysql://127.1.244.1:3306/

4.5. Port Forwarding

At this point, you may have noticed that the database cartridge is only accessible via a 127.x.x.x private address. This ensures that only the application gear can communicate with the database.

With OpenShift Origin port forwarding, developers can connect to remote services with local client tools. This allows the developer to focus on code without having to worry about the details of configuring complicated firewall rules or SSH tunnels. To connect to the MySQL database running on our OpenShift Origin gear, you have to first forward all the ports to your local machine. This can be done using the rhc port-forward command. This command is a wrapper that configures SSH port forwarding. Once the command is executed, you should see a list of services that are being forwarded and the associated IP address and port to use for connections as shown below:

$ rhc port-forward -a firstphp

Checking available ports...
Binding httpd -> 127.11.144.1:8080...
Binding mysqld -> 127.11.144.1:3306...
Forwarding ports, use ctl + c to stop

In the above snippet, you can see that mysql database, which we added to the firstphp gear, is forwarded to our local machine. If you open http://127.11.144.1:8080 in your browser you will see the application.

Note
At the time of this writing, there is an extra step to enable port forwarding on Mac OS X based systems. You will need to create an alias on your loopback device for the IP address listed in output shown above.
sudo ifconfig lo0 alias 127.11.144.1

Now that you have your services forward, you can connect to them using local client tools. To connect to the MySQL database running on the OpenShift Origin gear, run the mysql command as shown below:

$ mysql -uadmin -p -h 127.11.144.1
Note
The above command assumes that you have the MySQL client installed locally.

4.6. Enable hot_deploy

If you are familiar with PHP, you will probably be wondering why we stop and start apache on each code deployment. Fortunately, we provide a way for developers to signal to OpenShift Origin that they do not want us to restart the application runtime for each deployment. This is accomplished by creating a hot_deploy marker in the correct directory. Change to your application root directory, for example ~/code/<yourdomain>/firstphp and issue the following commands:

$ touch .openshift/markers/hot_deploy
$ git add .
$ git commit -am "Adding hot_deploy marker"
$ git push

Pay attention to the output:

Counting objects: 7, done.
Delta compression using up to 8 threads.
Compressing objects: 100% (4/4), done.
Writing objects: 100% (4/4), 403 bytes, done.
Total 4 (delta 2), reused 0 (delta 0)
remote: restart_on_add=false
remote: Will add new hot deploy marker
remote: App will not be stopped due to presence of hot_deploy marker
remote: restart_on_add=false
remote: ~/git/firstphp.git ~/git/firstphp.git
remote: ~/git/firstphp.git
remote: Running .openshift/action_hooks/pre_build
remote: Running .openshift/action_hooks/build
remote: Running .openshift/action_hooks/deploy
remote: hot_deploy_added=false
remote: App will not be started due to presence of hot_deploy marker
remote: Running .openshift/action_hooks/post_deploy
To ssh://e9e92282a16b49e7b78d69822ac53e1d@firstphp-<yourdomain>.example.com/~/git/firstphp.git/
   4fbda99..fdbd056  master -> master

The two lines of importance are:

remote: Will add new hot deploy marker
remote: App will not be stopped due to presence of hot_deploy marker

Adding a hot_deploy marker will significantly increase the speed of application deployments while developing an application.

5. The Web Console

Servers used
  • localhost

Tools used
  • OpenShift Origin web console

  • git

OpenShift Origin provides users with multiple ways to create and manage applications. The platform provides command line tools, IDE integration, REST APIs, and a web console. In this chapter we will explore the creation and management of application using the web console.

Having DNS resolution setup on your local machine, as discussed in the Comprehensive Deployment Guide, is crucial in order to connect to the web console.

5.1. Authenticate to the Web Console

Open your favorite web browser and go to the following URL:

http://<your Broker hostname or IP>/

Once you enter the above URL, you will be asked to authenticate. The exact auth method will vary according to the authentication plugin that your Broker is using. The OpenShift Origin virtual machine has a default user account of demo / changeme

image

After entering in valid credentials, you will see the OpenShift Origin web console dashboard:

image

5.2. Create a New Application

In order to create a new application using the web console, click on the ADD APPLICATION button. You will then be presented with a list of available runtimes that you can choose from. To follow along with our PHP examples above, let’s create a new PHP application and name it phptwo.

image

image

Once you have created the application, you will see a confirmation screen with some information on making code changes in your new app:

image

Click through to the application overview page for more details:

  • URL for your application

  • GIT repository URL

  • Instructions for making code changes

  • Link to add a cartridge

image

5.3. Clone an Application Repository

Open up a command prompt and clone your application repository with the instructions provided on the web console. When executing the git clone command, a new directory will be created in your current working directory. Once you have a local copy of your application, make a small code change to the index.php and push your changes to your OpenShift Origin gear.

Once you have made a code change, view your application in a web browser to ensure that the code was deployed correctly to your server.

5.4. Add a Cartridge

Click on the My Applications tab at the top of the screen and then select the Phptwo application by clicking on it.

image

After clicking on the Phptwo application link, you will be presented with the management dashboard for that application. On this page, you can view the GIT repository URL, add a cartridge, or delete the application. We want to add the MongoDB database to our application. To do this, click on the Add MongoDB button.

image

On the next screen, press the Add Cartridge button.

image

Once the MongoDB database cartridge has been added to your application, the web console will display a confirmation screen which contains the connection information for your database.

image

As noted in the section on environment variables, the connection information is always available via environment variables on your OpenShift Origin gear.

5.5. Verify Database Connection

Using information from the chapter on building applications, add a file that tests the connection to the database. If you are following the examples, you will need to modify the previously used PHP code block to only display if the connection was successful as we have not created a schema for this new database instance.

6. Application Scaling

Servers used
  • localhost

  • node host

Tools used
  • rhc

  • ssh

  • git

  • touch

  • pwd

Application scaling enables your application to react to changes in HTTP traffic and automatically allocate the necessary resources to handle the current demand. The OpenShift Origin infrastructure monitors incoming web traffic and automatically adds additional gear of your web cartridge online to handle requests.

6.1. How Scaling Works

If you create a non-scaled application, the web cartridge occupies only a single gear and all traffic is sent to that gear. When you create a scaled application, it consumes two gears; one for the high-availability proxy (HAProxy) itself, and one for your actual application. If you add other cartridges like PostgreSQL or MySQL to your application, they are installed on their own dedicated gears.

The HAProxy cartridge sits between your application and the network and routes web traffic to your web cartridges. When traffic increases, HAProxy notifies the OpenShift Origin servers that it needs additional capacity. OpenShift checks that you have a free gear (out of your max number of gears) and then creates another copy of your web cartridge on that new gear. The code in the git repository is copied to each new gear, but the data directory begins empty. When the new cartridge copy starts it will invoke your build hooks and then HAProxy will begin routing web requests to it. If you push a code change to your web application all of the running gears will get that update.

The algorithm for scaling up and scaling down is based on the number of concurrent requests to your application. OpenShift Origin allocates 10 connections per gear - if HAProxy sees that you’re sustaining 90% of your peak capacity, it adds another gear. If your demand falls to 50% of your peak capacity for several minutes, HAProxy removes that gear.

Because each cartridge is "share-nothing", if you want to share data between web cartridges you can use a database cartridge. Each of the gears created during scaling has access to the database and can read and write consistent data. As OpenShift Origin grows we anticipate adding more capabilities like shared storage, scaled databases, and shared caching.

The OpenShift Origin web console shows you how many gears are currently being consumed by your application. We have lots of great things coming for web application scaling, so stay tuned.

6.2. Create a Scaled Application

In order to create a scaled application using the rhc command line tools, you need to specify the -s switch to the command. Let’s create a scaled PHP application with the following command:

$ rhc app create scaledapp -t php -s

After executing the above command, you should see output that specifies that you are using both the PHP and HAProxy cartridges:

Password: ****

Creating application 'scaledapp'
================================

  Scaling:   yes
  Namespace: <yourdomain>
  Cartridge: php
  Gear Size: default

Your application's domain name is being propagated worldwide (this might take a minute)...
The authenticity of host 'scaledapp-<yourdomain>.example.com (10.4.59.221)' can't be established.
RSA key fingerprint is 6c:a5:e5:fa:75:db:5a:7f:dc:a2:44:ed:e4:97:af:3c.
Are you sure you want to continue connecting (yes/no)? yes
Cloning into 'scaledapp'...
done

scaledapp @ http://scaledapp-<yourdomain>.example.com/
=============================================
  Application Info
  ================
    UUID      = 1a6d471841d84e8aaf25222c4cdac278
    Gear Size = small
    Git URL   =
ssh://1a6d471841d84e8aaf25222c4cdac278@scaledapp-<yourdomain>.example.com/~/git/scaledapp.git/
    SSH URL   = ssh://1a6d471841d84e8aaf25222c4cdac278@scaledapp-<yourdomain>.example.com
    Created   = 4:20 PM
  Cartridges
  ==========
    php-5.3
    haproxy-1.4
  Scaling Info
  ============
    Scaled x2 (minimum: 2, maximum: available gears) with haproxy-1.4 on small gears

RESULT:
Application scaledapp was created.

Log in to the web console with your browser and click on the scaledapp application. You will notice while looking at the gear details that it lists the number of gears that your application is currently using. Additionally, note the scaling indicator ("Scales") and the Web Load balancer cartridge:

image

6.3. Set the Scaling Strategy

OpenShift Origin allows users the ability to set the minimum and maximum numbers of gears that an application can use to handle increased HTTP traffic. This scaling strategy is exposed via the web console. While on the application details screen, click on the gear range below the Scales header on your PHP cartridge:

image

This will present you with an interface where you can set minimum and maximum gears counts for the application’s dynamic scaling:

image

6.4. Manual Scaling

There are often times when a developer will want to disable automatic scaling in order to manually control when a new gear is added to an application. Some examples of when manual scaling may be preferred over automatic scaling could include:

  • If you are anticipating a certain load on your application and wish to scale it accordingly.

  • You have a fixed set of resources for your application.

OpenShift Origin supports this workflow by allowing users to manually add and remove gears for an application. The instructions below describe how to disable the automatic scaling feature. It is assumed you have already created your scaled application as detailed in this chapter and are at the root level directory for the application.

From your locally cloned Git repository, create a disable autoscaling marker, as shown in the example below:

$ touch .openshift/markers/disable_auto_scaling
$ git add .
$ git commit -am "remove automatic scaling"
$ git push

After pushing the changes to the remote repository, you will need to restart the HAProxy cartridge, or the whole application. This applies only for the time you add the marker, so the HAProxy can pick up the changes. To restart the HAProxy cartridge you will need to SSH into the gear, run the gear restart script and select the HAProxy cartridge. To restart the whole application run:

$ rhc app-restart [AppName]

To add a new gear to your application, SSH to your application gear with the following command replacing the contents with the correct information for your application.

$ ssh [AppUUID]@[AppName]-[DomainName].example.com

Once you have have been authenticated to your application gear, you can add a new gear with the following command:

 $ add-gear -a [AppName] -u [AppUUID] -n [DomainName]

In this example, the application name is scaledapp, the application UUID is the username that you used to SSH to the node host, and the domain name is <yourdomain>. Given that information, your command should looking similar to the following:

[scaledapp-<yourdomain>.example.com ~]\> add-gear -a scaledapp -u 1a6d471841d84e8aaf25222c4cdac278 -n <yourdomain>

Verify that your new gear was added to the application by running the rhc app show command or by looking at the application details on the web console:

$ rhc app show scaledapp

After executing this command, you should see the application is now using three gears.

scaledapp @ http://scaledapp-<yourdomain>.example.com/
=============================================
  Application Info
  ================
    SSH URL   = ssh://1a6d471841d84e8aaf25222c4cdac278@scaledapp-<yourdomain>.example.com
    Gear Size = small
    Git URL   = ssh://1a6d471841d84e8aaf25222c4cdac278@scaledapp-<yourdomain>.example.com/~/git/scaledapp.git/
    Created   = 4:20 PM
    UUID      = 1a6d471841d84e8aaf25222c4cdac278
  Cartridges
  ==========
    php-5.3
    haproxy-1.4
  Scaling Info
  ============
    Scaled x3 (minimum: 2, maximum: available gears) with haproxy-1.4 on small gears

Just as we scaled up with the add-gear command, we can manually scale down with the remove-gear command. Remove the third gear from your application with the following command making sure to substitute the correct application UUID:

[scaledapp-<yourdomain>.example.com ~]\> remove-gear -a scaledapp -u 1a6d471841d84e8aaf25222c4cdac278 -n <yourdomain>

After removing the gear with the remove-gear command, verify that the application only contains two gears, HAProxy and a single runtime gear:

$  rhc app show scaledapp

scaledapp @ http://scaledapp-<yourdomain>.example.com/
=============================================
  Application Info
  ================
    Created   = 4:20 PM
    Gear Size = small
    SSH URL   = ssh://1a6d471841d84e8aaf25222c4cdac278@scaledapp-<yourdomain>.example.com
    Git URL   = ssh://1a6d471841d84e8aaf25222c4cdac278@scaledapp-<yourdomain>.example.com/~/git/scaledapp.git/
    UUID      = 1a6d471841d84e8aaf25222c4cdac278
  Cartridges
  ==========
    php-5.3
    haproxy-1.4
  Scaling Info
  ============
    Scaled x2 (minimum: 2, maximum: available gears) with haproxy-1.4 on small gears

6.5. Viewing HAProxy Information

OpenShift Origin provides a dashboard that will give users relevant information about the status of the HAProxy gear that is balancing and managing load between the application gears. This dashboard provides visibility into metrics such as process id, uptime, system limits, current connections, and running tasks. To view the HAProxy dashboard, open your web browser and enter the following URL:

http://scaledapp-<yourdomain>.example.com/haproxy-status/

image

7. DIY Applications

Servers used
  • localhost

Tools used
  • rhc

  • git

In addition to supporting Ruby, PHP, Perl, Python, and Java EE6, the OpenShift Origin environment supports the "Do it Yourself" or "DIY" application type. Using this application type, users can run just about any program that speaks HTTP.

How this works is remarkably straightforward. The OpenShift Origin execution environment is a carefully secured Fedora Linux operating system on x64 systems. Thus, OpenShift Origin can run any binary that will run on Fedora 19 x64.

The way that OpenShift Origin DIY runtimes interfaces your application to the outside world is by creating an HTTP proxy specified by the environment variables OPENSHIFT_INTERNAL_IP and OPENSHIFT_INTERNAL_PORT. All your application has to do is bind and listen on that address and port. HTTP requests will come into the OpenShift Origin environment, which will proxy those requests to your application. Your application will reply with HTTP responses, and the OpenShift Origin environment will relay those responses back to your users.

Your application will be executed by the .openshift/action_hooks/start script, and will be stopped by the .openshift/action_hooks/stop script.

Note
DIY applications are unsupported but is a great way for developers to try out unsupported languages, frameworks, or middleware that doesn’t ship as an official OpenShift Origin cartridge.

7.1. Creating a DIY Application

To create an application gear that will use the DIY application type, use the rhc app create command:

$ rhc app create -a myjavademo -t diy
$ cd myjavademo

7.2. Deploying a Sample DIY Application

In order to work with some example code instead of writing a DIY application from scratch, you can refer to an example application available on the OpenShift github page. This application code is written in Java and consists of a single MyHttpServer main class. Since this source code lives on the github OpenShift project page, we need to add the remote github repository and then pull the remote source code while at the same time overwriting the existing source code we have in our DIY application directory.

$ git remote add upstream git://github.com/openshift/openshift-diy-java-demo.git
$ git pull -s recursive -X theirs upstream master
$ git push

7.3. Verifying the Sample DIY Application

Once the java example has been pushed to your OpenShift Origin gear, open up a web browser and point to the following URL:

http://myjavademo-<yourdomain>.example.com/index.html
Note
Make sure to include the index.html file at the end of the URL.

If the application was deployed correctly, you should see a Hello DIY World! message. This little http java server will serve any files found in your application’s html directory, so you can add files or make changes to them, push the contents and see those reflected in your browser.

7.4. How This Works

The DIY cartridge provides a number of hooks that are called during the lifecycle actions of the application. The hooks available to you for customization are found in the .openshift/action_hooks directory of your application repository.

For this application, all that has been customized are the start and stop scripts. They simply launch the MyHttpServer class using Java, and perform a wget call to have the MyHttpServer stop itself:

cat .openshift/action_hooks/start
#!/bin/bash
# The logic to start up your application should be put in this
# script. The application will work only if it binds to
# $OPENSHIFT_INTERNAL_IP:8080

cd $OPENSHIFT_REPO_DIR
nohup java -cp bin test.MyHttpServer >${OPENSHIFT_DIY_LOG_DIR}/MyHttpServer.log 2>&1 &

[24](ironmaiden:diy) > cat .openshift/action_hooks/stop
#!/bin/bash
# The logic to stop your application should be put in this script.
wget http://${OPENSHIFT_INTERNAL_IP}:${OPENSHIFT_INTERNAL_PORT}?action=stop

See the src/test/MyHttpServer.java source to understand how the Java application is making use of the OpenShift Origin environment variables to interact with the server environment.

8. Developing Java EE applications using JBoss EAP

Servers used
  • localhost

Tools used
  • rhc

  • git

  • curl

OpenShift Origin provides the JBoss EAP runtime to facilitate the development and deployment of Java EE 6 applications.

JBoss Enterprise Application Platform 6 (JBoss EAP 6) is a fully compliant Java EE 6 platform which includes a subscription model with long-term support, platform certification, service packs and SLA(s). In this chapter we will build a simple todo application using Java EE 6 deployed on the JBoss EAP platform. The application will have a single entity called Todo and will persist todos to PostgreSQL using JPA. The application will also use EJB 3.1 Stateless session beans, Context and Dependency Injection (or CDI), and JAX RS for exposing RESTful web services.

8.1. Create a JBoss EAP Application

Note
Before starting this chapter, be aware that JBoss EAP is CPU and RAM intensive. If your Origin system is a low-spec’ed test system, you may run into performance issues with this example application. In this situation, we suggest that you delete other applications that you have deployed to your OpenShift Origin installation prior to proceeding.

To build the example application, run the following:

$ rhc app create -a todo -t jbosseap

This command deploys a template application at the following URL:

http://todo-<yourdomain>.example.com

Verify that the application has been deployed and the template is displaying correctly in your web browser.

8.2. Additional Marker Files for JBoss EAP

In previous chapters, we’ve discussed the way that OpenShift Origin allows the developer to control and manage some of the runtime features using marker files. For Java based deployments, there are additional marker files that a developer needs to be aware of:

  • enable_jpda - Will enable the JPDA socket based transport on the JVM running the JBoss EAP application server. This enables you to remotely debug code running inside of the JBoss application server.

  • skip_maven_build - Maven build step will be skipped

  • force_clean_build - Will start the build process by removing all non essential Maven dependencies. Any current dependencies specified in your pom.xml file will then be re-downloaded.

  • hot_deploy - Will prevent a JBoss EAP container restart during build/deployment. Newly built archives will be re-deployed automatically by the JBoss HDScanner component.

  • java7 - Will run JBoss EAP with Java7 if present. If no marker is present then the baseline Java version will be used (currently Java6)

8.3. Deployment Directory

If you list the contents of the application repository that was cloned to your local machine, you will notice a deployments directory. This directory is a location where a developer can place binary archive files, .ear files for example, for deployment. If you want to deploy a .war file rather than pushing source code, copy the .war file to deployments directory, add the .war file to your git repository, commit the change, and then push the content to your OpenShift Origin server.

8.4. Maven

OpenShift Origin uses the Maven build system for all Java projects. Once you add new source code following the standard Maven directory structure, OpenShift Origin will recognize the existing pom.xml in your applications root directory in order to build the code remotely.

The most important thing specified in the pom.xml file is a Maven profile named openshift. This is the profile which is invoked when you do deploy the code to OpenShift Origin.

8.5. Adding a PostgreSQL Cartridge

The todo sample application that is documented in this chapter will make use of the PostgreSQL database. Following the example section on adding a MySQL cartridge to an application, add the PostgreSQL cartridge to the todo application.

8.6. Building the todo Application

At this point, we should have an application named todo created as well as having PostgreSQL embedded in the application to use as our datastore. Now we can begin working on the application.

8.6.1. Creating Domain Model

Note

The source code for this example application is available on github at https://github.com/gshipley/todo-javaee6 If you want to copy the sample code directly into you example app, refer to the example git commands from the chapter on DIY applications to pull in the source code while overwriting the existing template.

The first thing that we have to do is to create the domain model for the todo application. The application will have a single entity named Todo as shown below. The entity shown below is a simple JPA entity with JPA and bean validation annotations. Create a source file named Todo.java in the todo/src/main/java/com/todo/domain directory with the following contents:

package com.todo.domain;

import java.util.Date;
import java.util.List;

import javax.persistence.CollectionTable;
import javax.persistence.Column;
import javax.persistence.ElementCollection;
import javax.persistence.Entity;
import javax.persistence.FetchType;
import javax.persistence.GeneratedValue;
import javax.persistence.GenerationType;
import javax.persistence.Id;
import javax.persistence.JoinColumn;
import javax.validation.constraints.NotNull;
import javax.validation.constraints.Size;

@Entity
public class Todo {

    @Id
    @GeneratedValue(strategy = GenerationType.AUTO)
    private Long id;

    @NotNull
    @Size(min = 10, max = 40)
    private String todo;

    @ElementCollection(fetch=FetchType.EAGER)
    @CollectionTable(name = "Tags", joinColumns = @JoinColumn(name = "todo_id"))
    @Column(name = "tag")
    @NotNull
    private List<String> tags;

    @NotNull
    private Date createdOn = new Date();

    public Todo(String todo) {
        this.todo = todo;
    }

    public Todo() {
    }

    public Long getId() {
        return id;
    }

    public void setId(Long id) {
        this.id = id;
    }

    public String getTodo() {
        return todo;
    }

    public void setTodo(String todo) {
        this.todo = todo;
    }

    public Date getCreatedOn() {
        return createdOn;
    }

    public void setCreatedOn(Date createdOn) {
        this.createdOn = createdOn;
    }


    public void setTags(List<String> tags) {
        this.tags = tags;
    }

    public List<String> getTags() {
        return tags;
    }

    @Override
    public String toString() {
        return "Todo [id=" + id + ", todo=" + todo + ", tags=" + tags
                + ", createdOn=" + createdOn + "]";
    }

}

8.6.2. Create the persistence.xml File

The persistence.xml file is a standard configuration file in JPA that defines your data source. It has to be included in the META-INF directory inside of the JAR file that contains the entity beans. The persistence.xml file must define a persistence-unit with a unique name. Create a META-INF directory under src/main/resources and then create the persistence.xml file with the contents below:

<?xml version="1.0" encoding="UTF-8" ?>
<persistence xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
        xsi:schemaLocation="http://java.sun.com/xml/ns/persistence http://java.sun.com/xml/ns/persistence/persistence_2_0.xsd"
        version="2.0" xmlns="http://java.sun.com/xml/ns/persistence">

        <persistence-unit name="todos" transaction-type="JTA">
                <provider>org.hibernate.ejb.HibernatePersistence</provider>
                <jta-data-source>java:jboss/datasources/PostgreSQLDS</jta-data-source>
                <class>com.todo.domain.Todo</class>
                <properties>
                        <property name="hibernate.show_sql" value="true" />
                        <property name="hibernate.hbm2ddl.auto" value="create" />
                </properties>

        </persistence-unit>
</persistence>

The jta-data-source refers to JNDI name preconfigured by OpenShift Origin in the standalone.xml file located in the .openshift/config directory.

8.6.3. Create the TodoService EJB Bean

Next we will create a stateless EJB bean named TodoService in the com.todo.service package. This bean will perform basic CRUD operations using javax.persistence.EntityManager. Create a file named TodoService in the src/main/java/com/todo/service directory and add the following contents:

package com.todo.service;

import java.util.List;
import javax.ejb.Stateless;
import javax.persistence.EntityManager;
import javax.persistence.PersistenceContext;
import com.todo.domain.Todo;

@Stateless
public class TodoService {

        @PersistenceContext
        private EntityManager entityManager;


        public Todo create(Todo todo) {
                entityManager.persist(todo);
                return todo;
        }

        public Todo find(Long id) {
                Todo todo = entityManager.find(Todo.class, id);
                List<String> tags = todo.getTags();
                System.out.println("Tags : " + tags);
                return todo;
        }
}

8.6.4. Enable CDI

CDI or Context and Dependency Injection is a Java EE 6 specification which enables dependency injection in a Java EE 6 project. To enable CDI in the todo project, create a beans.xml file in src/main/webapp/WEB-INF directory with the following contents:

<?xml version="1.0"?>
<beans xmlns="http://java.sun.com/xml/ns/javaee"
 xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://java.sun.com/xml/ns/javaee http://jboss.org/schema/cdi/beans_1_0.xsd"/>

In order to use the @Inject annotation instead of the @Ejb annotation to inject an EJB, you will have to write a producer which will expose the EntityManager. Create a source file in the src/main/java/com/todo/utils directory named Resources and add the following source code:

package com.todo.utils;

import javax.enterprise.inject.Produces;
import javax.persistence.EntityManager;
import javax.persistence.PersistenceContext;

public class Resources {

    @Produces
    @PersistenceContext
    private EntityManager em;

}

8.6.5. Creating a RESTful Web Service

Before exposing a RESTful web service for the Todo entity, we need to enable JAX-RS in our application. To enable JAX-RS, create a class which extends javax.ws.rs.core.Application and specify the application path using a javax.ws.rs.ApplicationPath annotation. Create a source file named JaxRsActivator in the src/main/java/com/todo/rest directory and add the following source code:

package com.todo.rest;

import javax.ws.rs.ApplicationPath;
import javax.ws.rs.core.Application;

@ApplicationPath("/rest")
public class JaxRsActivator extends Application {
   /* class body intentionally left blank */
}

Next we will create a TodoRestService class which will expose two methods that will create and read a Todo object. The service will consume and produce JSON. Create a source file named TodoRestService in the src/main/java/com/todo/rest directory and add the following source code:

package com.todo.rest;

import javax.inject.Inject;
import javax.ws.rs.Consumes;
import javax.ws.rs.GET;
import javax.ws.rs.POST;
import javax.ws.rs.Path;
import javax.ws.rs.PathParam;
import javax.ws.rs.Produces;
import javax.ws.rs.WebApplicationException;
import javax.ws.rs.core.MediaType;
import javax.ws.rs.core.Response;
import javax.ws.rs.core.UriBuilder;
import com.todo.domain.Todo;
import com.todo.service.TodoService;

@Path("/todos")
public class TodoRestService {

    @Inject
    private TodoService todoService;

    @POST
    @Consumes("application/json")
    public Response create(Todo entity) {
        todoService.create(entity);
        return Response.created(
                UriBuilder.fromResource(TodoRestService.class)
                        .path(String.valueOf(entity.getId())).build()).build();
    }

    @GET
    @Path("/{id:[0-9][0-9]*}")
    @Produces(MediaType.APPLICATION_JSON)
    public Todo lookupTodoById(@PathParam("id") long id) {
        Todo todo = todoService.find(id);
        if (todo == null) {
            throw new WebApplicationException(Response.Status.NOT_FOUND);
        }
        return todo;
    }
}

8.7. Deploy the todo Application to OpenShift Origin

Now that we have our application created, we need to push our changes to the OpenShift Origin gear that we created in an earlier section. From the application root directory, issue the following commands:

$ git add .
$ git commit -am "Adding source code"
$ git push

Once you execute the git push command, the application will begin building on the OpenShift Origin node host. Unless your Origin system is running in a production grade environment, the build process will take some time to complete.

8.8. Testing the todo Application

In order to test out the RESTful web service that we’ve created in this sample application, we can add and retrieve todo items using the curl command line utility. To add a new item, enter the following command:

$ curl -k -i -X POST -H "Content-Type: application/json" -d '{"todo":"Sell a lot of OpenShift Origin","tags":["javascript","ui"]}' https://todo-<yourdomain>.example.com/rest/todos

To list all available todo items, run the following command:

$ curl -k -i -H "Accept: application/json" https://todo-<yourdomain>.example.com/rest/todos/1

You should see the following output:

HTTP/1.1 200 OK
Date: Fri, 25 Jan 2013 04:05:51 GMT
Server: Apache-Coyote/1.1
Content-Type: application/json
Connection: close
Transfer-Encoding: chunked

{"id":1,"todo":"Sell a lot of OpenShift Origin","tags":["javascript","ui"],"createdOn":1359086546955}

If you downloaded and deployed the source code from the git repository, the project contains a JSF UI component which will allow you to test the application using your web browser. Simply point your browser to

http://todo-<yourdomain>.example.com

to verify that the application was deployed correctly.

8.9. Extra Credit

SSH into the application gear and verify the todo item was added to the PostgreSQL database.

9. Jenkins Continuous Integration

Servers used
  • localhost

  • node host

Tools used
  • rhc

  • git

  • yum

Jenkins (https://wiki.jenkins-ci.org) is a full featured continuous integration (CI) server that can run builds, tests, and other scheduled tasks. OpenShift Origin allows you to integrate Jenkins with your OpenShift Origin applications.

With Jenkins, you have access to a full library of plugins (https://wiki.jenkins-ci.org/display/JENKINS/Plugins) and a vibrant, thriving community of users who have discovered a new way to do development.

There are many reasons why you would want to leverage Jenkins as a continuous integration server. In the context of OpenShift Origin, some of the benefits are:

  • Archived build information

  • No application downtime during the build process

  • Failed builds do not get deployed (leaving the previous working version in place)

  • More resources to build your application as each Jenkins build spins up a new gear for short lived period of time

Jenkins includes a feature-rich web user interface that provides the ability to trigger builds, customize builds, manage resources, manage plugins, and many other features.

9.1. Verify Jenkins Cartridges

SSH to your node host and verify that you have the Jenkins cartridges installed:

# rpm -qa |grep jenkins

You should see the following four packages installed:

  • openshift-origin-cartridge-jenkins-1.0.1-1.el6op.noarch

  • jenkins-1.488-2.el6op.noarch

  • openshift-origin-cartridge-jenkins-client-1.0.1-1.el6op.noarch

  • jenkins-plugin-openshift-0.6.5-0.el6op.x86_64

If you do not have the above RPM packages installed on your node host, follow the directions in the Comprehensive Deployment Guide to install the Jenkins packages. Make sure to clear the cache on the broker host after installing the new packages.

9.2. Create a Jenkins Gear

In order to use Jenkins on OpenShift Origin, you will need to create an application gear that contains the Jenkins application. This is done using the rhc app create command line tool, or you can use the web console to create the application. The syntax for using the command line tool is as follows:

$ rhc app create -a jenkins -t jenkins

You should see the following output from this command:

Creating application 'jenkins'
==============================

  Gear Size: default
  Scaling:   no
  Cartridge: jenkins
  Namespace: <yourdomain>

Your application's domain name is being propagated worldwide (this might take a minute)...

Cloning into 'jenkins'...
done

jenkins @ http://jenkins-<yourdomain>.example.com/
=========================================
  Application Info
  ================
    SSH URL   = ssh://4437d81168c94baf9268f0592bbe31a9@jenkins-<yourdomain>.example.com
    Git URL   =
ssh://4437d81168c94baf9268f0592bbe31a9@jenkins-<yourdomain>.example.com/~/git/jenkins.git/
    UUID      = 4437d81168c94baf9268f0592bbe31a9
    Gear Size = small
    Created   = 2:05 PM
  Cartridges
  ==========
    jenkins-1

RESULT:
Application jenkins was created.

Jenkins created successfully.  Please make note of these credentials:

   User: admin
   Password: QKVn_1ZlQ7T_

Note:  You can change your password at: https://jenkins-<yourdomain>.example.com/me/configure

Make a note of the user username and password that was created for you by OpenShift Origin.

9.3. Add Jenkins Support to an Application

Now that we have a Jenkins server setup and running, we can add support to our todo application which will allow all futures builds to compile on the Jenkins server. To embed the Jenkins support cartridge in your application, use the following command:

$ rhc cartridge add -a todo -c jenkins-client

The output should be the following:

Adding 'jenkins-client-1' to application 'todo'
Success
jenkins-client-1
==================
  Properties
  ==========
    Job URL = https://jenkins-<yourdomain>.example.com/job/todo-build/

Verify that the Jenkins client was added to your application by running the following command:

$ rhc app show todo

At the bottom of the output, you should see the following information:

  Cartridges
  ==========
    jenkins-client-1 = https://jenkins-<yourdomain>.example.com/job/todo-build/
    postgresql-8.4     = postgresql://127.1.248.129:5432/
    jbosseap-6

9.4. Configure Jenkins

Open up a web browser and point to the following URL:

https://jenkins-<yourdomain>.example.com/job/todo-build/

Authenticate to the Jenkins environment by providing the username and password that was displayed after adding the Jenkins application.

image

Once you are authenticated to the Jenkins dashboard, click on the configure link:

image

A few interesting configuration items exist that may come in handy in the future:

Builder Configuration

The first interesting configuration is concerned with the builder. The configuration below states that Jenkins should create a builder with a small size using the JBoss EAP cartridge and that the Jenkins master will wait for 5 minutes for the slave to come online.

image

Git Configuration

The next configuration item of interest is the git SCM URL. It specifies the URL of the git repository to use, the branch to use, etc. This section is important if you want to use Jenkins to build a project which exists outside of OpenShift Origin. This would be useful for developers who have an internal repo for their source code that they would prefer to build from.

Build Configuration

The last configuration item which is interesting is under the build section. Here you can specify a shell script for building the project. For our current builder it does the following:

  • Specify if the project should be built using Java 6 or Java 7

  • Specify XMX memory configuration for maven and build the maven project. The memory it configures is 396M.

  • Deploying the application which includes stopping the application, pushing the content back from Jenkins to the application gear(s), and finally deploying the artifacts.

The source code for the default build script is as follows:

source /usr/libexec/openshift/cartridges/abstract/info/lib/jenkins_util

jenkins_rsync 4d1b096e414243e9833dad55d774de73@todo-<yourdomain>.example.com:~/.m2/ ~/.m2/

# Build setup and run user pre_build and build
. ci_build.sh

if [ -e ${OPENSHIFT_REPO_DIR}.openshift/markers/java7 ];
then
  export JAVA_HOME=/etc/alternatives/java_sdk_1.7.0
else
    export JAVA_HOME=/etc/alternatives/java_sdk_1.6.0
fi

export MAVEN_OPTS="$OPENSHIFT_MAVEN_XMX"
mvn --global-settings $OPENSHIFT_MAVEN_MIRROR --version
mvn --global-settings $OPENSHIFT_MAVEN_MIRROR clean package -Popenshift -DskipTests

# Deploy new build

# Stop app
jenkins_stop_app 4d1b096e414243e9833dad55d774de73@todo-<yourdomain>.example.com

# Push content back to application
jenkins_sync_jboss 4d1b096e414243e9833dad55d774de73@todo-<yourdomain>.example.com

# Configure / start app
$GIT_SSH 4d1b096e414243e9833dad55d774de73@todo-<yourdomain>.example.com deploy.sh

jenkins_start_app 4d1b096e414243e9833dad55d774de73@todo-<yourdomain>.example.com

$GIT_SSH 4d1b096e414243e9833dad55d774de73@todo-<yourdomain>.example.com post_deploy.sh

9.5. Deploy Code to Jenkins

Now that you have the Jenkins client embedded into your todo application gear, any future git push commands will send the code to the Jenkins server for building. To test this out, edit the src/main/webapp/todo.xhtml source file and change the title of the page. If you do not have this file, just create a new file instead. Look for the following code block:

<h2>Todo List Creation</h2>

Change the above code to the following:

<h2>Todo List Creation using Jenkins</h2>

Commit and push your change:

$ git commit -am "changed h2"
$ git push

After you push your changes to the Jenkins server, you should see the following output:

Counting objects: 5, done.
Delta compression using up to 8 threads.
Compressing objects: 100% (3/3), done.
Writing objects: 100% (3/3), 282 bytes, done.
Total 3 (delta 2), reused 0 (delta 0)
remote: restart_on_add=false
remote: Executing Jenkins build.
remote:
remote: You can track your build at https://jenkins-<yourdomain>.example.com/job/todo-build
remote:
remote: Waiting for build to schedule....Done
remote: Waiting for job to complete.....................................................................Done
remote: SUCCESS
remote: New build has been deployed.
To ssh://4d1b096e414243e9833dad55d774de73@todo-<yourdomain>.example.com/~/git/todo.git/
   eb5f9dc..8cee826  master -> master

While the build is happening, open up a new terminal window and run the following command:

$ rhc domain show

You will see a new gear that was created by the Jenkins application. This new gear is a temporary gear that OpenShift Origin creates in order to build your application code.

  todobldr @ http://todobldr-<yourdomain>.example.com/
  ===========================================
    Application Info
    ================
      UUID      = ffee273344bd404e99e59ba070512d0b
      Git URL   =
ssh://ffee273344bd404e99e59ba070512d0b@todobldr-<yourdomain>.example.com/~/git/todobldr.git/
      SSH URL   = ssh://ffee273344bd404e99e59ba070512d0b@todobldr-<yourdomain>.example.com
      Gear Size = small
      Created   = 2:48 PM
    Cartridges
    ==========
      jbosseap-6

If the build fails, or if you just want to see the output of the Maven build process, you can log in to your Jenkins application, click on the build, and then click the link to view the console output. Log in to your Jenkins application and view the contents of the last build.

image

9.6. Start a New Build

One of the great things about integrating your application with the Jenkins CI environment is the ability to start a new build without having to modify and push your source code. To initiate a new build, log in to the Jenkins dashboard and select the todo builder. Point your browser to:

https://jenkins-<yourdomain>.example.com/

Once you have been authenticated, click the todo-build link:

image

This will place you on the todo application builder dashboard. Click the Build Now link on the left hand side of the screen to initiate a new build:

image

After you click the Build Now link, a new build will show up under the links on the left hand side of the screen.

image

For more information about the current build, you can click on the build to manage and view details, including the console output, for the build.

10. JBoss Tools IDE

Servers used
  • localhost

Tools used
  • eclipse

JBoss Tools is an umbrella project for a set of Eclipse plugins that supports JBoss and related technologies; there is support for OpenShift, Hibernate, JBoss AS, Drools, jBPM, JSF, (X)HTML, Seam, Maven, JBoss ESB, JBoss Portal and more…​

10.1. Download and Install Eclipse - Juno

In this chapter, we are going to use the latest version of JBoss Tools. In order to make use of this version, we will need to use the Juno version of the popular Eclipse IDE. Head on over to the eclipse.org website and download the latest version of Eclipse for Java EE developers.

Once you have Eclipse installed, go to the JBoss Tools page located at

http://www.jboss.org/tools

and follow the instructions to install JBoss Tools 4.0 (Juno).

10.2. Use JBoss Tools with OpenShift Origin

By default, JBoss Tools OpenShift integration will default to use the OpenShift Online service that is hosted by Red Hat. In order for us to use JBoss Tools to communicate with our OpenShift Origin installation, we need to configure Eclipse with our LIBRA_SERVER setting. This is a straight forward process but one that may catch people off guard. To make the change, edit the eclipse.ini file located in the root directory of your Eclipse deployment and add -Dlibra_server=<your broker host name or IP address> directly after the the following line:

-vmargs

When finished, it should look like this:

-vmargs
-Dlibra_server=<your broker host name or IP address>
Note
If you are using the Mac OS X operating system, the process is a little more complicated. In order to pass arguments to Eclipse, you’ll have to edit the eclipse.ini file inside the Eclipse application bundle:
  • Select the Eclipse application bundle icon while holding down the Control Key

  • This will present you with a popup menu. Select "Show Package Contents" in the popup menu.

  • Locate eclipse.ini file in the Contents/MacOS sub-folder and open it with your favorite text editor to edit the command line options.

On OS X, after editing the eclipse.ini file it looks like following:

-startup
../../../plugins/org.eclipse.equinox.launcher_1.3.0.v20120522-1813.jar
--launcher.library
../../../plugins/org.eclipse.equinox.launcher.cocoa.macosx.x86_64_1.1.200.v20120522-1813
-product
org.eclipse.epp.package.jee.product
--launcher.defaultAction
openFile
-showsplash
org.eclipse.platform
--launcher.XXMaxPermSize
256m
--launcher.defaultAction
openFile
-vmargs
-Dlibra_server=<your broker host name or IP address>
-Dosgi.requiredJavaVersion=1.5
-Dhelp.lucene.tokenizer=standard
-XstartOnFirstThread
-Dorg.eclipse.swt.internal.carbon.smallFonts
-XX:MaxPermSize=256m
-Xms40m
-Xmx512m
-Xdock:icon=../Resources/Eclipse.icns
-XstartOnFirstThread
-Dorg.eclipse.swt.internal.carbon.smallFonts

After adding the correct arguments to the eclipse.ini file, restart the Eclipse IDE.

10.3. Create an OpenShift Origin Application

Now that we have Eclipse Juno and JBoss Tools 4.0 installed, we can create an OpenShift Origin application without having the leave the comfort of our favorite IDE. Click on the OpenShift Application link that is provided on the JBoss Central screen.

image

Once you click on the link to create a new OpenShift Origin application, you will be presented with a dialog to authenticate to OpenShift Origin. Now is also a good time to validate the Server setting is correctly set to your broker’s host name or IP address. If your server does not reflect this, you have not configured your eclipse.ini file correctly.

image

After clicking next, the JBoss Tools plugin will authenticate you to the broker host and present another dialog box to you. On this dialog box, you have the option of creating a new application, or to use an existing one. Since we already have a JBoss EAP application deployed, let’s select to Use existing application and click the Browse button. After clicking the Browse button, a REST API call be made to the broker host to retrieve the existing applications that you already have deployed.

image

Highlight the todo application and click on the Details…​ button. This will display all of the necessary information about the application, including any cartridges that may be embedded.

image

After clicking Next, Eclipse will ask you to create a new project or to use an existing one. Let’s create a new one and set the correct location where we want to store the project files.

image

Once you click the Finish button, the existing application will be cloned to your local project.

10.4. Manage OpenShift Origin Applications with JBoss Tools

JBoss Tools provide many features to allow a developer to manage their application from directly inside of the Eclipse IDE. This includes features such as viewing log files, publishing the application, and port-forwarding. Click on the servers tab at the bottom on the Eclipse IDE to see your OpenShift Origin server.

image

10.4.1. Tailing Log files

After clicking on the servers tab, right click on your OpenShift Origin server and then select OpenShift and finally select tail files.

image

You will now be able to view the log files in the console tab that has been opened for you inside of Eclipse.

10.4.2. Viewing Environment Variables

After clicking on the servers tab, right click on your OpenShift Origin server and then select OpenShift and finally select Environment Variables. Once you select this option, all of the system environment variables, including database connections, will be displayed in the console window of Eclipse.

10.4.3. Using Port-Forwarding

After clicking on the servers tab, right click on your OpenShift Origin server and then select OpenShift and finally select Port Forwarding. This will open up a new dialog that displays which services and what IP address will be used for the forwarded services.

image

For the next section of this chapter, ensure that you click on Start Forwarding so that we will be able to connect to PostgreSQL from our local machine.

10.4.4. Adding PostgreSQL as an Eclipse Data Source

Download the latest PostgreSQL driver from the following location

http://jdbc.postgresql.org/download.html

and save it to your local computer. Once you have the file downloaded, click on the Data Source Explorer tab, right click on Database Connection and select New. This will open the following dialog where you will want to select PostgreSQL:

image

Initially, the Drivers pull down box will be empty. In order to add our PostgreSQL driver, click the plug sign next to the drop down, highlight PostgreSQL JDBC Driver and then click on JAR List. Click on Add JAR/Zip and browse to the location of the JDBC4 driver that you downloaded.

Now that you have added the driver, the dialog box will display the available driver and allow you to specify your connection details. Enter the following information:

  • Database: todo

  • URL: jdbc:postgresql://127.0.0.1:5432/todo

  • User name: admin

  • Password: The password supplied by OpenShift. If you forgot this, use the Environment Variables utility provided by JBoss Tools.

In order to verify that your port-forwarding and database connection is setup correctly, press the test connection button. If your connection is failing, make sure that you have the correct authorization credentials and that port-forwarding is started via JBoss Tools.

Once you have correctly added the database connection, you should now see the remote database from the OpenShift Origin node host available for use in your Eclipse IDE.

image

At this point, you should be able to use any of the database tools provided by Eclipse to communicate with and manage your OpenShift Origin PostgreSQL database.

10.5. Code Changes and Application Deployment

In the project view, expand the source files for the src/main/webapp directory and edit the todo.xhtml source file. Change the following line

<h2>Todo List Creation using Jenkins</h2>

to the include JBoss Tools

<h2>Todo List Creation using Jenkins and JBoss Tools</h2>

Once you have made the source code change, save the contents of the file and then use the Team functionality by right clicking on your project. Commit and push the changes to your OpenShift Origin server. This push will follow the same workflow used previously by initiating a build on your Jenkins server.

image

After you push your changes, open up your Jenkins dashboard and open the Console Output screen to see the build progress. Once your build has completed, Eclipse will display a dialog box with a summary of the deployment:

image

Verify that your changes were deployed correctly by opening up a web browser and going to the following URL:

http://todo-<yourdomain>.example.com/

image

11. Quickstarts

Servers used
  • localhost

Tools used
  • rhc

  • git

A key tenet when Red Hat was designing OpenShift Origin was the ability for developers to be able to run their source code and application as is, without having to use proprietary API(s). To illustrate how easy it is for developers to get their existing application deployed on OpenShift Origin, the team has created a github space where they provide numerous quick start projects that make deploying common open source applications to the platform a painless task. Some of the popular open source projects the team provides a quick start for are:

  • Drupal

  • Review Board

  • Wordpress

  • Frog CMS

  • Sugar CRM

  • Redmine

  • MediaWiki

11.1. Quickstart Installation

Point your browser to the following URL:

http://www.github.com/openshift

Given the number of available quick starts, you may have to use the search functionality of your browser to locate the quick start that you would like to install. For this example walkthrough, choose either the Wordpress or Drupal quick start and follow the instructions provided to install the application.

image

12. Quickstart Creation

Servers used
  • localhost

  • node host

Tools used
  • rhc

  • git

  • github

A common task that you will be asked to do is make a software developer’s development environment easily deployable on OpenShift Origin. Development teams desire a quick and repeatable way to spin up an environment with their application code already deployed and integrated with various data stores. In the previous chapter, we described how to install applications via our quick start process. In this chapter, we will focus on the ability for users to create their own quick starts using the popular open source project Piwik as an example.

12.1. Download the Piwik Source Code

At the time of this writing, you can obtain the code directly from the Piwik website at: http://piwik.org/latest.zip. Once downloaded, save the file to ~/code/piwikstage.

After you have downloaded the source code, extract the contents of the zip archive with the following command:

$ cd ~
$ mkdir code
$ mkdir piwikstage
$ unzip latest.zip

This will create a piwik directory under the ~/code/piwikstage directory.

12.2. Create an OpenShift Origin Application

We need to create an OpenShift Origin application to hold the source code as well as embed the MySQL database:

 $ cd ~/code
$ rhc app create-a piwik -t php
$ rhc cartridge add -a piwik -c mysql-5.5

OpenShift Origin, as you know, creates a default index file for your application. Because we are going to be using the source code from our Piwik application, we need to remove the existing template.

$ rm -rf ~/code/piwik/php/*

At this point, we need to copy over the source code that we extracted from the zip archive to our piwik OpenShift Origin application:

$ cp -av ~/code/piwikstage/piwik/* ~/code/piwik/php

Now we need to add and commit our changes to our piwik application:

$ cd ~/code/piwik/php
$ git add .
$ git commit -am "Initial commit for Piwik"
$ git push

Assuming everything went as expected, you should be able to verify Piwik is running by opening up your web browser and pointing to the following URL:

http://piwik-<yourdomain>.example.com

image

12.3. Creating a github Repository

Note
This step assumes that you already have a github account. If you don’t, head on over to www.github.com and sign up (it’s free).

Log in to the github website and create a new repository for our quick start. The direct link, after you are logged in, to create a new repository is:

https://github.com/repositories/new

Enter a project name and a description for your quick start. I suggest a name that identifies the project as a OpenShift Origin quick start. For example, a good name would be Piwik-openshift-quickstart.

image

On your newly created project space, grab the HTTP Git URL and add the github repository as a remote to your existing piwik OpenShift Origin application.

image

$ cd ~/code/piwik
$ git remote add github ${github http URL from github}

12.4. Create Deployment Instructions

In order for developers to be able to use the quick start that you have created, you need to provide instructions on how to install the application. These instructions need to be in the README and README.md files. By default, github will display the contents of this file, using the markdown version if it exits, on the repository page. For example, a proper README file would contain the following contents:

Piwik on OpenShift
=========================
Piwik is a downloadable, open source (GPL licensed) real time web analytics software program. It provides you with detailed reports on your website visitors: the search engines and keywords they used, the language they speak, your popular pages, and so much more.

Piwik aims to be an open source alternative to Google Analytics, and is already used on more than 150,000 websites.

More information can be found on the official Piwik website at http://piwik.org

    Running on OpenShift
    --------------------

    Create an account at http://openshift.redhat.com/

    Create a PHP application

        rhc app create -a piwik -t php-5.3 -l $USERNAME

    Add mysql support to your application

        rhc cartridge add -a piwik -c mysql-5.5 -l $USERNAME
    Make a note of the username, password, and host name as you will need to use these to complete the Piwik installation on OpenShift

    Add this upstream Piwik quickstart repo

        cd piwik/php
        rm -rf *
        git remote add upstream -m master git://github.com/gshipley/piwik-openshift-quickstart.git
        git pull -s recursive -X theirs upstream master

    Then push the repo upstream to OpenShift

        git push

    That's it, you can now checkout your application at:

        http://piwik-$yourlogin.rhcloud.com

Create the README and README.md in the ~/code/piwik directory and add the contents provided above. Once you have created these files, add and commit them to your repository:

$ cd ~/code/piwik
$ git add .
$ git commit -am "Add installation instructions"

Now we need to push these changes to the github repository we created:

$ git push -u github master

12.5. Verify the Quickstart

Delete the piwik OpenShift Origin application and follow the instruction you created for your Piwik quick start to verify that everything works as expected.

Tip
If your application requires an existing populated database, the way to accomplish this is by using the .openshift/action_hooks/build script located in your application directory. Once you have your database created locally, do a mysqldump on the table and store the .sql file in the action_hooks directory. You can then modify an existing build file to import the schema on application deployment. For an example, take a look at the action_hooks directory of the Wordpress quick start.

1. This hook is assumed to be a shell script which is sourced in the same execution as the action it relates to; this facilitates the modification of the control action’s environment (e.g. via export statements).