AdminTraining.html

<!DOCTYPE html>  
<html lang="en">
<head>
  <meta charset="utf-8">
  <meta http-equiv="X-UA-Compatible" content="IE=edge,chrome=1">
  <title>AdminTraining</title>
  <meta name="viewport" content="width=device-width, initial-scale=1.0">
  <style>
/* 
   This document has been created with Marked.app <http://markedapp.com>, Copyright 2011 Brett Terpstra
   Please leave this notice in place, along with any additional credits below.
   ---------------------------------------------------------------
   Title: GitHub
   Author: Brett Terpstra
   Description: Github README style. Includes theme for Pygmentized code blocks.
*/
html, body {
    color: black;
}

* {
    margin: 0;
    padding: 0;
}

body {
    font: 13.34px helvetica,arial,freesans,clean,sans-serif;
    -webkit-font-smoothing: antialiased;
    line-height: 1.4;
    padding: 3px;
    background: #fff;
    -moz-border-radius: 3px;
    -webkit-border-radius: 3px;
}

p {
    margin: 1em 0;
}

a {
    color: #4183c4;
    text-decoration: none;
}

#wrapper {
    background-color: #fff;
    padding: 0 30px;
    margin: 15px;
}

#wrapper {
    font-size: 14px;
    line-height: 1.6;
}

#wrapper>*:first-child {
    margin-top: 0!important;
}

#wrapper>*:last-child {
    margin-bottom: 0!important;
}

h1,h2,h3,h4,h5,h6 {
    margin: 0;
    padding: 0;
}

h1 {
    margin: 15px 0;
    padding-bottom: 2px;
    font-size: 24px;
    border-bottom: 1px solid #eee;
}

h2 {
    margin: 20px 0 10px 0;
    font-size: 18px;
}

h3 {
    margin: 20px 0 10px 0;
    padding-bottom: 2px;
    font-size: 14px;
    border-bottom: 1px solid #ddd;
}

h4 {
    font-size: 14px;
    line-height: 26px;
    padding: 18px 0 4px;
    font-weight: bold;
    text-transform: uppercase;
}

h5 {
    font-size: 13px;
    line-height: 26px;
    padding: 14px 0 0;
    font-weight: bold;
    text-transform: uppercase;
}

h6 {
    color: #666;
    font-size: 14px;
    line-height: 26px;
    padding: 18px 0 0;
    font-weight: normal;
    font-variant: italic;
}

hr {
    background: transparent url(data:image/png;
    base64,iVBORw0KGgoAAAANSUhEUgAAAAYAAAAECAYAAACtBE5DAAAAGXRFWHRTb2Z0d2FyZQBBZG9iZSBJbWFnZVJlYWR5ccllPAAAAyJpVFh0WE1MOmNvbS5hZG9iZS54bXAAAAAAADw/eHBhY2tldCBiZWdpbj0i77u/IiBpZD0iVzVNME1wQ2VoaUh6cmVTek5UY3prYzlkIj8+IDx4OnhtcG1ldGEgeG1sbnM6eD0iYWRvYmU6bnM6bWV0YS8iIHg6eG1wdGs9IkFkb2JlIFhNUCBDb3JlIDUuMC1jMDYwIDYxLjEzNDc3NywgMjAxMC8wMi8xMi0xNzozMjowMCAgICAgICAgIj4gPHJkZjpSREYgeG1sbnM6cmRmPSJodHRwOi8vd3d3LnczLm9yZy8xOTk5LzAyLzIyLXJkZi1zeW50YXgtbnMjIj4gPHJkZjpEZXNjcmlwdGlvbiByZGY6YWJvdXQ9IiIgeG1sbnM6eG1wPSJodHRwOi8vbnMuYWRvYmUuY29tL3hhcC8xLjAvIiB4bWxuczp4bXBNTT0iaHR0cDovL25zLmFkb2JlLmNvbS94YXAvMS4wL21tLyIgeG1sbnM6c3RSZWY9Imh0dHA6Ly9ucy5hZG9iZS5jb20veGFwLzEuMC9zVHlwZS9SZXNvdXJjZVJlZiMiIHhtcDpDcmVhdG9yVG9vbD0iQWRvYmUgUGhvdG9zaG9wIENTNSBNYWNpbnRvc2giIHhtcE1NOkluc3RhbmNlSUQ9InhtcC5paWQ6OENDRjNBN0E2NTZBMTFFMEI3QjRBODM4NzJDMjlGNDgiIHhtcE1NOkRvY3VtZW50SUQ9InhtcC5kaWQ6OENDRjNBN0I2NTZBMTFFMEI3QjRBODM4NzJDMjlGNDgiPiA8eG1wTU06RGVyaXZlZEZyb20gc3RSZWY6aW5zdGFuY2VJRD0ieG1wLmlpZDo4Q0NGM0E3ODY1NkExMUUwQjdCNEE4Mzg3MkMyOUY0OCIgc3RSZWY6ZG9jdW1lbnRJRD0ieG1wLmRpZDo4Q0NGM0E3OTY1NkExMUUwQjdCNEE4Mzg3MkMyOUY0OCIvPiA8L3JkZjpEZXNjcmlwdGlvbj4gPC9yZGY6UkRGPiA8L3g6eG1wbWV0YT4gPD94cGFja2V0IGVuZD0iciI/PqqezsUAAAAfSURBVHjaYmRABcYwBiM2QSA4y4hNEKYDQxAEAAIMAHNGAzhkPOlYAAAAAElFTkSuQmCC) repeat-x 0 0;border: 0 none;
    color: #ccc;
    height: 4px;
    margin: 20px 0;
    padding: 0;
}

#wrapper>h2:first-child,#wrapper>h1:first-child,#wrapper>h1:first-child+h2 {
    border: 0;
    margin: 0;
    padding: 0;
}

#wrapper>h3:first-child,#wrapper>h4:first-child,#wrapper>h5:first-child,#wrapper>h6:first-child {
    margin: 0;
    padding: 0;
}

h4+p,h5+p,h6+p {
    margin-top: 0;
}

li p.first {
    display: inline-block;
}

ul,ol {
    margin: 15px 0 15px 25px;
}

ul li,ol li {
    margin-top: 7px;
    margin-bottom: 7px;
}

ul li>*:last-child,ol li>*:last-child {
    margin-bottom: 0;
}

ul li>*:first-child,ol li>*:first-child {
    margin-top: 0;
}

#wrapper>ul,#wrapper>ol {
    margin-top: 21px;
    margin-left: 36px;
}

dl {
    margin: 0;
    padding: 20px 0 0;
}

dl dt {
    font-size: 14px;
    font-weight: bold;
    line-height: normal;
    margin: 0;
    padding: 20px 0 0;
}

dl dt:first-child {
    padding: 0;
}

dl dd {
    font-size: 13px;
    margin: 0;
    padding: 3px 0 0;
}

blockquote {
    margin: 14px 0;
    border-left: 4px solid #ddd;
    padding-left: 11px;
    color: #555;
}

table {
    border-collapse: collapse;
    margin: 20px 0 0;
    padding: 0;
}

table tr {
    border-top: 1px solid #ccc;
    background-color: #fff;
    margin: 0;
    padding: 0;
}

table tr:nth-child(2n) {
    background-color: #f8f8f8;
}

table tr th,table tr td {
    border: 1px solid #ccc;
    text-align: left;
    margin: 0;
    padding: 6px 13px;
}

img {
    max-width: 100%;
    height: auto
}

code,tt {
    margin: 0 2px;
    padding: 2px 5px;
    white-space: nowrap;
    border: 1px solid #ccc;
    background-color: #f8f8f8;
    border-radius: 3px;
    -moz-border-radius: 3px;
    -webkit-border-radius: 3px;
    font-size: 12px
}

pre>code {
    margin: 0;
    padding: 0;
    white-space: pre;
    border: none;
    background: transparent;
    font-size: 13px
}

.highlight pre,pre {
    background-color: #f8f8f8;
    border: 1px solid #ccc;
    font-size: 13px;
    line-height: 19px;
    overflow: auto;
    padding: 6px 10px;
    border-radius: 3px;
    -moz-border-radius: 3px;
    -webkit-border-radius: 3px;
}

#wrapper>pre,#wrapper>div.highlight {
    margin: 10px 0 0;
}

pre code,pre tt {
    background-color: transparent;
    border: none;
}

#wrapper {
    background-color: #fff;
    border: 1px solid #CACACA;
    padding: 30px;
}

.poetry pre {
    font-family: Georgia, Garamond, serif !important;
    font-style: italic;
    font-size: 110% !important;
    line-height: 1.6em;
    display: block;
    margin-left: 1em;
}

.poetry pre code {
    font-family: Georgia, Garamond, serif !important;
    word-break: break-all;
	word-break: break-word; /* Non standard for webkit */
	-webkit-hyphens: auto;
	-moz-hyphens: auto;
	hyphens: auto;
    white-space: pre-wrap;
}

sup,sub,a.footnote {
    font-size: 1.4ex;
    height: 0;
    line-height: 1;
    vertical-align: super;
    position: relative;
}

sub {
    vertical-align: sub;
    top: -1px;
}

@media print {
    body {
        background: #fff;
    }

    img, pre, blockquote, table, figure {
        page-break-inside: avoid
    }

    #wrapper {
        background: #fff;
        border: none;
    }

    code {
        background-color: #fff;
        color: #444!important;
        padding: 0 .2em;
        border: 1px solid #DEDEDE;
    }

    pre code {
        background-color: #fff!important;
        overflow: visible;
    }

    pre {
        background: #fff;
    }
}

@media screen {
    body.inverted, .inverted #wrapper, .inverted hr
.inverted p,.inverted td,.inverted li,.inverted h1,.inverted h2,.inverted h3,.inverted h4,.inverted h5,.inverted h6,.inverted th,.inverted .math,.inverted caption,.inverted dd,.inverted dt, .inverted blockquote {
        color: #eee !important;
        border-color: #555
    }

    .inverted td, .inverted th {
        background: #333;
    }

    .inverted pre,.inverted code, .inverted tt {
        background: #444!important;
    }

    .inverted h2 {
        border-color: #555
    }

    .inverted hr {
        border-color: #777;
        border-width: 1px !important;
    }

    ::selection {
        background: rgba(157, 193, 200,.5)
    }

    h1::selection {
        background-color: rgba(45, 156, 208, .3)
    }

    h2::selection {
        background-color: rgba(90, 182, 224, .3)
    }

    h3::selection,
    h4::selection,
    h5::selection,
    h6::selection,li::selection,ol::selection {
        background-color: rgba(133, 201, 232, .3)
    }

    code::selection {
        background-color: rgba(0,0,0,.7);
        color: #eee
    }

    code span::selection {
        background-color: rgba(0,0,0,.7) !important;
        color: #eee !important
    }

    a::selection {
        background-color: rgba(255, 230, 102,.2)
    }

    .inverted a::selection {
        background-color: rgba(255, 230, 102,.6)
    }

    td::selection,th::selection,caption::selection {
        background-color: rgba(180, 237, 95, .5);
    }

    .inverted {
        background: #0b2531;
    }

    .inverted #wrapper,.inverted {
        background: rgba(37, 42, 42, 1)
    }

    .inverted a {
        color: rgba(172, 209, 213, 1);
    }
}

.highlight .c {
    color: #998;
    font-style: italic;
}

.highlight .err {
    color: #a61717;
    background-color: #e3d2d2;
}

.highlight .k {
    font-weight: bold;
}

.highlight .o {
    font-weight: bold;
}

.highlight .cm {
    color: #998;
    font-style: italic;
}

.highlight .cp {
    color: #999;
    font-weight: bold;
}

.highlight .c1 {
    color: #998;
    font-style: italic;
}

.highlight .cs {
    color: #999;
    font-weight: bold;
    font-style: italic;
}

.highlight .gd {
    color: #000;
    background-color: #fdd;
}

.highlight .gd .x {
    color: #000;
    background-color: #faa;
}

.highlight .ge {
    font-style: italic;
}

.highlight .gr {
    color: #a00;
}

.highlight .gh {
    color: #999;
}

.highlight .gi {
    color: #000;
    background-color: #dfd;
}

.highlight .gi .x {
    color: #000;
    background-color: #afa;
}

.highlight .go {
    color: #888;
}

.highlight .gp {
    color: #555;
}

.highlight .gs {
    font-weight: bold;
}

.highlight .gu {
    color: #800080;
    font-weight: bold;
}

.highlight .gt {
    color: #a00;
}

.highlight .kc {
    font-weight: bold;
}

.highlight .kd {
    font-weight: bold;
}

.highlight .kn {
    font-weight: bold;
}

.highlight .kp {
    font-weight: bold;
}

.highlight .kr {
    font-weight: bold;
}

.highlight .kt {
    color: #458;
    font-weight: bold;
}

.highlight .m {
    color: #099;
}

.highlight .s {
    color: #d14;
}

.highlight .na {
    color: #008080;
}

.highlight .nb {
    color: #0086B3;
}

.highlight .nc {
    color: #458;
    font-weight: bold;
}

.highlight .no {
    color: #008080;
}

.highlight .ni {
    color: #800080;
}

.highlight .ne {
    color: #900;
    font-weight: bold;
}

.highlight .nf {
    color: #900;
    font-weight: bold;
}

.highlight .nn {
    color: #555;
}

.highlight .nt {
    color: #000080;
}

.highlight .nv {
    color: #008080;
}

.highlight .ow {
    font-weight: bold;
}

.highlight .w {
    color: #bbb;
}

.highlight .mf {
    color: #099;
}

.highlight .mh {
    color: #099;
}

.highlight .mi {
    color: #099;
}

.highlight .mo {
    color: #099;
}

.highlight .sb {
    color: #d14;
}

.highlight .sc {
    color: #d14;
}

.highlight .sd {
    color: #d14;
}

.highlight .s2 {
    color: #d14;
}

.highlight .se {
    color: #d14;
}

.highlight .sh {
    color: #d14;
}

.highlight .si {
    color: #d14;
}

.highlight .sx {
    color: #d14;
}

.highlight .sr {
    color: #009926;
}

.highlight .s1 {
    color: #d14;
}

.highlight .ss {
    color: #990073;
}

.highlight .bp {
    color: #999;
}

.highlight .vc {
    color: #008080;
}

.highlight .vg {
    color: #008080;
}

.highlight .vi {
    color: #008080;
}

.highlight .il {
    color: #099;
}

.highlight .gc {
    color: #999;
    background-color: #EAF2F5;
}

.type-csharp .highlight .k {
    color: #00F;
}

.type-csharp .highlight .kt {
    color: #00F;
}

.type-csharp .highlight .nf {
    color: #000;
    font-weight: normal;
}

.type-csharp .highlight .nc {
    color: #2B91AF;
}

.type-csharp .highlight .nn {
    color: #000;
}

.type-csharp .highlight .s {
    color: #A31515;
}

.type-csharp .highlight .sc {
    color: #A31515;
}

</style>
<style>#wrapper { max-width:900px; margin:0 auto }</style>
</head>
<body class="normal poetry">
  <div id="wrapper">
      <h1 id="contents"><strong>Contents</strong></h1>

<ol>
<li><p><strong>Overview of OpenShift Enterprise</strong> </p></li>
<li><p><strong>Registering and updating the operating system</strong> </p></li>
<li><p><strong>Installing and configuring DNS</strong> </p></li>
<li><p><strong>Configuring the DHCP client and hostname</strong> </p></li>
<li><p><strong>Installing and configuring MongoDB</strong> </p></li>
<li><p><strong>Installing and configuring ActiveMQ</strong> </p></li>
<li><p><strong>Installing and configuring the MCollective client</strong> </p></li>
<li><p><strong>Installing and configuring the broker application</strong> </p></li>
<li><p><strong>Configuring the broker plugins and MongoDB user accounts</strong> </p></li>
<li><p><strong>Installing the OpenShift Enterprise Web Console</strong> </p></li>
<li><p><strong>Configuring DNS resolution for the node host</strong> </p></li>
<li><p><strong>Setting up MCollective on the node host</strong> </p></li>
<li><p><strong>Installing and configuring the OpenShift Enterprise node packages</strong> </p></li>
<li><p><strong>Configuring PAM namespace module, Linux control groups (cgroups), and user quotas</strong> </p></li>
<li><p><strong>Configuring SELinux and System Control Settings</strong> </p></li>
<li><p><strong>Configuring SSH, OpenShift Port Proxy, and node configuration</strong> </p></li>
<li><p><strong>Configuring local machine for DNS resolution</strong> </p></li>
<li><p><strong>Adding cartridges</strong> </p></li>
<li><p><strong>Managing resources</strong> </p></li>
<li><p><strong>Managing districts</strong> </p></li>
<li><p><strong>Installing the RHC client tools</strong> </p></li>
<li><p><strong>Using <em>rhc setup</em></strong> </p></li>
<li><p><strong>Creating a PHP application</strong> </p></li>
<li><p><strong>Managing an application</strong> </p></li>
<li><p><strong>Using cartridges</strong> </p></li>
<li><p><strong>Using the web console to create applications</strong> </p></li>
<li><p><strong>Scaling an application</strong> </p></li>
<li><p><strong>The DIY application type</strong> </p></li>
<li><p><strong>Java EE applications using JBoss EAP</strong> </p></li>
<li><p><strong>Using Jenkins continuous integration</strong> </p></li>
<li><p><strong>Using JBoss Tools</strong> </p></li>
<li><p><strong>Using quickstarts</strong> </p></li>
<li><p><strong>Creating a quick start</strong> </p></li>
<li><p><strong>Appendix</strong> </p></li>
</ol>

<!--BREAK-->

<h1 id="overviewofopenshiftenterprise"><strong>1.0 Overview of OpenShift Enterprise</strong></h1>

<h2 id="assumptions"><strong>1.1 Assumptions</strong></h2>

<p>This lab manual assumes that you are attending an instructor led training class and that you will be using this lab manual in conjunction with the lecture. </p>

<p>I also assume that you have been granted access to two Red Hat Enterprise Linux servers with which to perform the exercises in this lab manual. If you do not have access to your servers, please notify the instructor.</p>

<p>A working knowledge of SSH, git, and yum, and familiarity with a Linux-based text editor are assumed. If you do not have an understanding of any of these technologies, please let the instructor know. </p>

<h2 id="whatyoucanexpecttolearnfromthistrainingclass"><strong>1.2 What you can expect to learn from this training class</strong></h2>

<p>At the conclusion of this training class, you should have a solid understanding of how to install and configure OpenShift Enterprise. You should also feel comfortable in the usage of creating and deploying applications using the OpenShift Enterprise web console, command line tools, and JBoss Developer Studio. </p>

<h2 id="overviewofopenshiftenterprisepaas"><strong>1.3 Overview of OpenShift Enterprise PaaS</strong></h2>

<p>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. Developers typically start JBoss 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. </p>

<p>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. </p>

<p>OpenShift Enterprise provides developers and IT organizations an 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. </p>

<p>This manual will walk you through the process of installing and configuring an OpenShift Enterprise environment as part of this two day training class that you are attending. </p>

<h2 id="overviewofiaas"><strong>1.4 Overview of IaaS</strong></h2>

<p>The great thing about OpenShift Enterprise is that we are infrastructure agnostic. You can run OpenShift on bare metal, virtualized instances, or on public/private cloud instances. The only thing that is required is Red Hat Enterprise Linux as the underlying operating system. We require this in order to take advantage of SELinux and other enterprise features so that you can ensure your installation is rock solid and secure. </p>

<p>What does this mean? This means that in order to take advantage of OpenShift Enterprise, you can use any existing resources that you have in your hardware pool today. It doesn’t matter if your infrastructure is based on EC2, VMware, RHEV, Rackspace, OpenStack, CloudStack, or even bare metal as we run on top of any Red Hat Enterprise Linux operating system as long as the architecture is x86_64. </p>

<p>For this training class will be using OpenStack as our infrastructure as a service layer. </p>

<h2 id="usingthekickstartscript"><strong>1.5 Using the <em>kickstart</em> script</strong></h2>

<p>In this training class, we are going to go into the details of installing and configuring all of the components required for OpenShift Enterprise. We will be installing and configuring BIND, MongoDB, DHCP, ActiveMQ, MCollective, and other vital pieces to OpenShift. Doing this manually will give you a better understanding of how all of the components of OpenShift Enterprise work together to create a complete solution. </p>

<p>That being said, once you have a solid understanding of all of the moving pieces, you will probably want to take advantage of our kickstart script that performs all the functions in the administration portion of this training on your behalf. This script will allow you to create complete OpenShift Enterprise environments in a matter of minutes. It is not intended for you to use the kickstart as part of this training class. </p>

<p>The kickstart script is located at:<br/>
https://mirror.openshift.com/pub/enterprise-server/scripts/1.0/ </p>

<p>When using the kickstart script, be sure to edit it to use the correct Red Hat subscriptions. Take a look at the script header for full instructions. </p>

<h2 id="electronicversionofthisdocument"><strong>1.6 Electronic version of this document</strong></h2>

<p>This lab manual contains many configuration items that will need to be performed on your broker and node hosts. Manually typing in all of these values would be a tedious and error prone effort. To alleviate the risk of errors, and to let you concentrate on learning the material instead of typing tedious configuration items, an electronic version of the document is available at the following URL: </p>

<pre><code>http://training.runcloudrun.com  
</code></pre>

<p>In order to download all of the sample configuration files for the lab, enter the following command on your host:</p>

<pre><code># wget -rnp --reject index.\* http://training.runcloudrun.com/labs/  
</code></pre>

<!--BREAK-->

<h1 id="lab1:registeringandupdatingtheoperatingsystemestimatedtime:10minutes"><strong>Lab 1: Registering and updating the operating system (Estimated time: 10 minutes)</strong></h1>

<p><strong>Server used:</strong></p>

<ul>
<li>broker host</li>
</ul>

<p><strong>Tools used:</strong></p>

<ul>
<li>SSH</li>
<li>subscription-manager</li>
<li>ntpdate</li>
<li>yum</li>
</ul>

<h2 id="registeringthesystemandaddingsubscriptions"><strong>Registering the system and adding subscriptions</strong></h2>

<p>In order to be able to update to newer packages, and to download the OpenShift Enterprise software, your system will need to be registered with Red Hat to allow your system access to appropriate software channels. You will need the following subscriptions at a minimum for this class.</p>

<ul>
<li>Red Hat Enterprise Linux Employee Subscription</li>
<li>OpenShift Enterprise Employee Subscription</li>
</ul>

<p>The machines provided to you in this lab have already been registered with the production Red Hat Network. However, they have not been enabled for the above subscriptions. List all of the available subscriptions for the account that has been registered for you:</p>

<pre><code># subscription-manager list --available   
</code></pre>

<p>From the list provided, subscribe to Red Hat Enterprise Linux.</p>

<pre><code># subscription-manager subscribe --pool [POOL IID from previous command]  
</code></pre>

<p>Once you have subscribed to Red Hat Enterprise Linux, the next step is subscribe to the OpenShift Enterprise Employee subscription. Complete that step and then verify that you are subscribed to both RHEL and OpenShift Enterprise.</p>

<pre><code># subscription-manager list --consumed  
</code></pre>

<p>Also, take note of the yum repositories that you are now able to install packages from.</p>

<pre><code># yum repolist  
</code></pre>

<h2 id="updatingtheoperatingsystemtothelatestpackages"><strong>Updating the operating system to the latest packages</strong></h2>

<p>We need to update the operating system to have all of the latest packages that may be in the yum repository for RHEL Server. This is important to ensure that you have a recent update to the SELinux packages that OpenShift Enterprise relies on. In order to update your system, issue the following command:</p>

<pre><code># yum update  
</code></pre>

<p><strong>Note:</strong> Depending on your connection and speed of your broker host, this installation make take several minutes. </p>

<h2 id="configuringtheclocktoavoidclockskew"><strong>Configuring the clock to avoid clock skew</strong></h2>

<p>OpenShift Enterprise requires NTP to synchronize the system and hardware clocks. This synchronization is necessary for communication between the broker and node hosts; if the clocks are too far out of synchronization, MCollective will drop messages. Every MCollective request (discussed in a later lab) includes a time stamp, provided by the sending host&#8217;s clock. If a sender&#8217;s clock is substantially behind a recipient&#8217;s clock, the recipient drops the message. This is often referred to as clock skew and is a common problem that users encounter when they fail to sync all of the system clocks.</p>

<pre><code># ntpdate clock.redhat.com
# chkconfig ntpd on
# service ntpd start  
</code></pre>

<p><strong>Lab 1 Complete!</strong> </p>

<!--BREAK-->

<h1 id="lab2:installingandconfiguringdnsestimatedtime:20minutes"><strong>Lab 2: Installing and configuring DNS (Estimated time: 20 minutes)</strong></h1>

<p><strong>Server used:</strong></p>

<ul>
<li>broker host</li>
</ul>

<p><strong>Tools used:</strong></p>

<ul>
<li>SSH</li>
<li>BIND</li>
<li>text editor (vi, emacs, nano, etc.)</li>
<li>environment variables</li>
<li>SELinux</li>
<li>Commands: cat, echo, chown, dnssec-keygen, rndc-confgen, restorecon, chmod, lokkit, chkconfig, service, nsupdate, ping, dig</li>
</ul>

<p><strong>Note: For this lab, use the 192.x.x.x IP address when setting up your nameserver</strong> </p>

<h2 id="installingthebinddnsserver"><strong>Installing the BIND DNS Server</strong></h2>

<p>In order for OpenShift Enterprise to work correctly, you will need to configure BIND so that you have a DNS server setup. At a typical customer site, they will have an existing DNS infrastructure in place. However, for the purpose of this training class, we need to install and configure our own server so that name resolution works properly. Primarily, we will be using name resolution for communication between our broker and node hosts as well as dynamically updating our DNS server to resolve gear application names when we start creating application gears. </p>

<p>This lab starts off by requiring the installation of both <em>bind</em> and <em>bind-utils</em> packages.</p>

<pre><code># yum install bind bind-utils  
</code></pre>

<h2 id="creatingenvironmentvariablesandadnsseckeyfile"><strong>Creating environment variables and a DNSSEC key file</strong></h2>

<p>The official OpenShift documentation suggests that you set an environment variable for the domain name that you will be using to facilitate faster configuration of BIND. Let’s follow the suggested route for this training class by issuing the following command:</p>

<pre><code># domain=example.com  
</code></pre>

<p>DNSSEC, which stands for DNS Security Extensions, is a method by which DNS servers can verify that DNS data is coming from the correct place. You create a private/public key pair to determine to authenticity of the source domain name server. In order to implement DNSSEC on our new PaaS, we need to create a key file, which we will store in /var/named. For convenience, set the $keyfile variable now to the location of the this key file:</p>

<pre><code># keyfile=/var/named/${domain}.key  
</code></pre>

<p>Create a DNSSEC key pair and store the private key in a variable named $key by using the following commands:</p>

<pre><code># cd /var/named
# dnssec-keygen -a HMAC-MD5 -b 512 -n USER -r /dev/urandom ${domain}
# KEY=&quot;$(grep Key: K${domain}*.private | cut -d ' ' -f 2)&quot;
# cd -
# rndc-confgen -a -r /dev/urandom  
</code></pre>

<p>Verify that the key was created properly by viewing the contents of the key variable:</p>

<pre><code># echo $KEY  
</code></pre>

<p>Configure the ownership, permissions, and SELinux context for the key we created:</p>

<pre><code># restorecon -v /etc/rndc.* /etc/named.*
# chown -v root:named /etc/rndc.key
# chmod -v 640 /etc/rndc.key  
</code></pre>

<h2 id="creatingthefowarders.confconfigurationfileforhostnameresolution"><strong>Creating the <em>fowarders.conf</em> configuration file for host name resolution</strong></h2>

<p>The DNS forwarding facility of BIND can be used to create a large site-wide cache on a few servers, reducing traffic over links to external nameservers. It can also be used to allow queries by servers that do not have direct access to the Internet, but wish to look up exterior names anyway. Forwarding occurs only on those queries for which the server is not authoritative and does not have the answer in its cache. </p>

<p>Create a forwards.conf file with the following commands: </p>

<p><strong>The forwarders.conf file is available on the lab support website</strong></p>

<pre><code># echo &quot;forwarders { 8.8.8.8; 8.8.4.4; } ;&quot; &gt;&gt; /var/named/forwarders.conf
# restorecon -v /var/named/forwarders.conf
# chmod -v 755 /var/named/forwarders.conf  
</code></pre>

<h2 id="configuringsubdomainresolutionandcreatinganinitialdnsdatabase"><strong>Configuring subdomain resolution and creating an initial DNS database</strong></h2>

<p>To ensure that we are starting with a clean <em>/var/named/dynamic</em> directory, let’s remove this directory if it exists:</p>

<pre><code># rm -rvf /var/named/dynamic
# mkdir -vp /var/named/dynamic  
</code></pre>

<p>Issue the following command to create the <em>${domain}.db</em> file (before running this command, verify that the domain variable you set earlier in this lab is available to your current session): </p>

<p><strong>The example.com.db file is available on the lab support website</strong> </p>

<pre><code>cat &lt;&lt;EOF &gt; /var/named/dynamic/${domain}.db  
\$ORIGIN .  
\$TTL 1 ; 1 seconds (for testing only)  
${domain}       IN SOA  ns1.${domain}. hostmaster.${domain}. (
            2011112904 ; serial
            60         ; refresh (1 minute)
            15         ; retry (15 seconds)
            1800       ; expire (30 minutes)
            10         ; minimum (10 seconds)
            )  
        NS  ns1.${domain}.  
        MX  10 mail.${domain}.  
\$ORIGIN ${domain}.  
ns1         A   127.0.0.1  
EOF  
</code></pre>

<p>Once you have entered the above echo command, cat the contents of the file to ensure that the command was successful:</p>

<pre><code># cat /var/named/dynamic/${domain}.db  
</code></pre>

<p>You should see the following output: </p>

<pre><code>$ORIGIN .  
$TTL 1  ; 1 second  
example.com             IN SOA  ns1.example.com. hostmaster.example.com. (
                                2011112916 ; serial
                                60         ; refresh (1 minute)
                                15         ; retry (15 seconds)
                                1800       ; expire (30 minutes)
                                10         ; minimum (10 seconds)
                                )
                        NS      ns1.example.com.
                        MX      10 mail.example.com.  
$ORIGIN example.com.  
ns1                     A       127.0.0.1  
</code></pre>

<p>Now we need to install the DNSSEC key for our domain: </p>

<pre><code>cat &lt;&lt;EOF &gt; /var/named/${domain}.key  
key ${domain} {  
  algorithm HMAC-MD5;  
  secret &quot;${KEY}&quot;;  
};
EOF  
</code></pre>

<p>Set the correct permissions and context:</p>

<pre><code># chown -Rv named:named /var/named
# restorecon -rv /var/named  
</code></pre>

<h2 id="creatingthenamedconfigurationfile"><strong>Creating the <em>named</em> configuration file</strong></h2>

<p>We also need to create our <em>named.conf</em> file, Before running the following command, verify that the domain variable you set earlier in this lab is available to your current session. </p>

<p><strong>The <em>/etc/named.conf</em> file is available on the lab support website</strong> </p>

<pre><code>cat &lt;&lt;EOF &gt; /etc/named.conf  
// named.conf  
//
// Provided by Red Hat bind package to configure the ISC BIND named(8) DNS  
// server as a caching only nameserver (as a localhost DNS resolver only).  
//
// See /usr/share/doc/bind*/sample/ for example named configuration files.  
//

options {  
    listen-on port 53 { any; };  
    directory   &quot;/var/named&quot;;  
    dump-file   &quot;/var/named/data/cache_dump.db&quot;;
        statistics-file &quot;/var/named/data/named_stats.txt&quot;;
        memstatistics-file &quot;/var/named/data/named_mem_stats.txt&quot;;  
    allow-query     { any; };  
    recursion yes;

    /* Path to ISC DLV key */  
    bindkeys-file &quot;/etc/named.iscdlv.key&quot;;

    // set forwarding to the next nearest server (from DHCP response  
    forward only;
        include &quot;forwarders.conf&quot;;  
};

logging {
        channel default_debug {
                file &quot;data/named.run&quot;;
                severity dynamic;
        };  
};

// use the default rndc key  
include &quot;/etc/rndc.key&quot;;  

controls {  
    inet 127.0.0.1 port 953  
    allow { 127.0.0.1; } keys { &quot;rndc-key&quot;; };  
};

include &quot;/etc/named.rfc1912.zones&quot;;  

include &quot;${domain}.key&quot;;  

zone &quot;${domain}&quot; IN {  
    type master;  
    file &quot;dynamic/${domain}.db&quot;;  
    allow-update { key ${domain} ; } ;  
};
EOF  
</code></pre>

<p>And finally, set the permissions for the new configuration file that we just created:</p>

<pre><code># chown -v root:named /etc/named.conf
# restorecon /etc/named.conf  
</code></pre>

<h2 id="configuringhostnameresolutiontousenewthebindserver"><strong>Configuring host name resolution to use new the <em>BIND</em> server</strong></h2>

<p>We need to update our resolv.conf file to use our local <em>named</em> service that we just installed and configured. Open up your <em>/etc/resolv.conf</em> file and add the following entry <strong>as the first nameserver entry in the file</strong>: </p>

<pre><code>nameserver 127.0.0.1  
</code></pre>

<p>We also need to make sure that <em>named</em> starts on boot and that the firewall is configured to pass through DNS traffic:</p>

<pre><code># lokkit --service=dns
# chkconfig named on  
</code></pre>

<h2 id="startingthenamedservice"><strong>Starting the <em>named</em> service</strong></h2>

<p>We are finally ready to start up our new DNS server and add some updates.</p>

<pre><code># service named start  
</code></pre>

<p>You should see a confirmation message that the service was started correctly. If you do not see an OK message, I would suggest running through the above steps again and ensuring that the output of each command matches the contents of this exercise. If you are still having trouble after trying the steps again, ask the instructor for help. </p>

<h2 id="addingentriesusingnsupdate"><strong>Adding entries using <em>nsupdate</em></strong></h2>

<p>Now that our BIND server is configured and started, we need to add a record for our broker node to BIND’s database. To accomplish this task, we will use the nsupdate command, which opens an interactive shell where we can perform commands, <strong>using the 10.x.x.x address provided to you</strong>:</p>

<pre><code># nsupdate -k ${keyfile}
&gt; server 127.0.0.1
&gt; update delete broker.example.com A
&gt; update add broker.example.com 180 A ${your system ip address}
&gt; send  
</code></pre>

<p>Press control-D to exit from the interactive session. </p>

<p>In order to verify that you have successfully added broker.example.com to your DNS server, you can perform</p>

<pre><code># ping broker.example.com  
</code></pre>

<p>and it should resolve to the local machine that you are working on. You can also perform a dig request using the following command:</p>

<pre><code># dig @127.0.0.1 broker.example.com  
</code></pre>

<p><strong>Lab 2 Complete!</strong> </p>

<!--BREAK-->

<h1 id="lab3:configuringthedhcpclientandhostnameestimatedtime:5minutes"><strong>Lab 3: Configuring the DHCP client and hostname (Estimated time: 5 minutes)</strong></h1>

<p><strong>Server used:</strong></p>

<ul>
<li>broker host</li>
</ul>

<p><strong>Tools used:</strong></p>

<ul>
<li>text editor</li>
<li>Commands: hostname</li>
</ul>

<h2 id="creatingdhclient-eth0.conf"><strong>Creating <em>dhclient-eth0.conf</em></strong></h2>

<p>In order to configure your broker host to use a DNS server that we installed in a previous lab, you will need to edit the <em>/etc/dhcp/dhclient-{$network device}.conf file</em> or create the file if it does not exist. Without this step, the DNS server information in <em>/etc/resolv.conf</em> would default back the server returned from your DHCP server on the next boot of the server. For example, if you are using eth0 as your default ethernet device, you would need to edit the following file: </p>

<pre><code>/etc/dhcp/dhclient-eth0.conf  
</code></pre>

<p>If you are unsure of which network device that your system is using, you can issue the <em>ifconfig</em> command to list all available network devices for your machine. Note, the <em>lo</em> device is the loopback device and is not the one you are looking for. </p>

<p>Once you have the correct file opened, add the following information making sure to substitute the correct IP Address in place of 10.10.10.10 </p>

<pre><code>prepend domain-name-servers 10.10.10.10;  
supersede host-name &quot;broker&quot;;  
supersede domain-name &quot;example.com&quot;;  
</code></pre>

<h2 id="setthehostnameforyourserver"><strong>Set the host name for your server</strong></h2>

<p>You need to set the hostname of your broker host. In order to accomplish this task, edit the <em>/etc/sysconfig/network</em> file and locate the section labeled <em>HOSTNAME</em>. The line that you want to replace should look like this: </p>

<pre><code>HOSTNAME=localhost.localdomain  
</code></pre>

<p>We need to change this to reflect the new hostname that we are going to apply for this server. For this lab, we will be using broker.example.com. Change the <em>/etc/sysconfig/network</em> file to reflect the following change: </p>

<pre><code>HOSTNAME=broker.example.com  
</code></pre>

<p>Now that we have configured our hostname, we also need to set it for our current session by using the following command:</p>

<pre><code># hostname broker.example.com  
</code></pre>

<p><strong>Lab 3 Complete!</strong> </p>

<!--BREAK-->

<h1 id="lab4:installingandconfiguringmongodbestimatedtime:10minutes"><strong>Lab 4: Installing and configuring MongoDB (Estimated time: 10 minutes)</strong></h1>

<p><strong>Server used:</strong></p>

<ul>
<li>broker host</li>
</ul>

<p><strong>Tools used:</strong></p>

<ul>
<li>text editor</li>
<li>yum</li>
<li>mongo</li>
<li>chkconfig</li>
<li>service</li>
</ul>

<p>OpenShift Enterprise makes heavy use of MongoDB for storing internal information about users, gears, and other necessary items. If you are not familiar with MongoDB, I suggest that you head over the official MongoDB site (http://www.mongodb.org) to read up on this great NoSQL database. For the purpose of this lab, you need to know that MongoDB is a document data storage system and uses JavaScript for the command syntax and stores all documents in a JSON format. </p>

<h2 id="installmongodserver"><strong>Install <em>mongod</em> server</strong></h2>

<p>In order to use MongoDB, we will need to install the mongod server. To accomplish these tasks on Red Hat Enterprise Linux with an OpenShift Enterprise subscription, simply issue the following command:</p>

<pre><code># yum install mongodb-server  
</code></pre>

<p>At the time of this writing, you should see the following packages being installed:</p>

<table>
<caption id="section-mmd-tables-table1">Packages installed from mongodb-server</caption>
<colgroup>
<col style="text-align:left;"/>
<col style="text-align:left;"/>
</colgroup>

<thead>
<tr>
	<th style="text-align:left;">Package Name</th>
	<th style="text-align:left;">Arch</th>
	<th style="text-align:left;">Package Version</th>
	<th style="text-align:left;">Repo</th>
	<th style="text-align:left;">Size</th>
</tr>
</thead>

<tbody>
<tr>
	<td style="text-align:left;">mongodb-server</td>
	<td style="text-align:left;">x86_64</td>
	<td style="text-align:left;">2.0.2&#8211;2.el6op</td>
	<td style="text-align:left;">rhel-server-ose-infra&#8211;6-rpms</td>
	<td style="text-align:left;">3.8 M</td>
</tr>
<tr>
	<td style="text-align:left;">boost-program-options</td>
	<td style="text-align:left;">x86_64</td>
	<td style="text-align:left;">1.41.0&#8211;11.el6_1.2</td>
	<td style="text-align:left;">rhel&#8211;6-server-rpms</td>
	<td style="text-align:left;">105 k</td>
</tr>
<tr>
	<td style="text-align:left;">boost-thread</td>
	<td style="text-align:left;">x86_64</td>
	<td style="text-align:left;">1.41.0&#8211;11.el6_1.2</td>
	<td style="text-align:left;">rhel&#8211;6-server-rpms</td>
	<td style="text-align:left;">105 k</td>
</tr>
<tr>
	<td style="text-align:left;">libmongodb</td>
	<td style="text-align:left;">x86_64</td>
	<td style="text-align:left;">1.41.0&#8211;11.el6_1.2</td>
	<td style="text-align:left;">rhel&#8211;6-server-rpms</td>
	<td style="text-align:left;">41 k</td>
</tr>
<tr>
	<td style="text-align:left;">boost-program-options</td>
	<td style="text-align:left;">x86_64</td>
	<td style="text-align:left;">2.0.2&#8211;2.el6op</td>
	<td style="text-align:left;">rhel-server-ose-infra&#8211;6-rpms</td>
	<td style="text-align:left;">531 k</td>
</tr>
<tr>
	<td style="text-align:left;">mongodb</td>
	<td style="text-align:left;">x86_64</td>
	<td style="text-align:left;">2.0.2&#8211;2.el6op</td>
	<td style="text-align:left;">rhel-server-ose-infra&#8211;6-rpms</td>
	<td style="text-align:left;">21 M</td>
</tr>
</tbody>
</table>
<h2 id="configuringmongod"><strong>Configuring <em>mongod</em></strong></h2>

<p>MongoDB uses a configuration file for its settings. This file can be found at <em>/etc/mongodb.conf</em>. We need to make a few changes to this file to ensure that we handle authentication correctly and that we enable the ability to use small files. Go ahead and edit the configuration file and ensure the two following conditions are set correctly: </p>

<p><strong>The <em>/etc/mongodb.conf</em> file is available on the lab support website</strong></p>

<pre><code>auth=true  
</code></pre>

<p>By default, this line is commented out so just remove the hash mark <em>(#)</em>at the beginning of the line to enable the setting. We also need to enable smallfiles, so add the following line:</p>

<pre><code>smallfiles=true  
</code></pre>

<p>Setting <em>smallfiles=true</em> configures MongoDB not to pre-allocate a huge database, which wastes a surprising amount of time and disk space and is unnecessary for the comparatively small amount of data that the broker will store in it. It wouldn&#8217;t hurt anything not to set <em>smallfiles=true</em>, except that it would take a minute or two to initialize a larger database and waste about half a gigabyte of disk space. </p>

<h2 id="configuringmongodtostartonboot"><strong>Configuring <em>mongod</em> to start on boot</strong></h2>

<p>MongoDB is an essential part of the OpenShift Enterprise platform. Because of this, we need to ensure that mongod is configured to start on system boot:</p>

<pre><code># chkconfig mongod on  
</code></pre>

<p>By default, when you install <em>mongod</em> via the yum command, the service is not started. You can verify this with the following:</p>

<pre><code># service mongod status  
</code></pre>

<p>This should return - <em>mongod is stopped</em>. In order to start the service, simply issue</p>

<pre><code># service mongod start  
</code></pre>

<p>We need to verify that mongod was installed and configured correctly. In order to do this, we are going to make use of the mongo shell client tool. If you are more familiar with MySQL or Postgres, this is similar to the mysql client where you are dropped into an interactive SQL shell. Remember, MongoDB is a NoSQL database, so the notion of entering SQL commands is nonexistent. In order to start the mongo shell, enter the following command:</p>

<pre><code># mongo  
</code></pre>

<p>You should see a confirmation message that you are using MongoDB shell version: 2.0.2 and that you are connecting to the test database. To verify even further, let’s list all of the available databases that we currently have.</p>

<pre><code>&gt; show dbs  
</code></pre>

<p>You will then be presented with a list of valid databases that are currently available to the mongod service. </p>

<pre><code>admin   (empty)  
local   (empty)  
</code></pre>

<p><strong>Lab 4 Complete!</strong> </p>

<!--BREAK-->

<h1 id="lab5:installingandconfiguringactivemqestimatedtime:10minutes"><strong>Lab 5: Installing and configuring ActiveMQ (Estimated time: 10 minutes)</strong></h1>

<p><strong>Server used:</strong></p>

<ul>
<li>broker host</li>
</ul>

<p><strong>Tools used:</strong></p>

<ul>
<li>text editor</li>
<li>yum</li>
<li>wget</li>
<li>lokkit</li>
<li>chkconfig</li>
<li>service</li>
</ul>

<p>ActiveMQ is a fully open source messenger service that is available for use across many different programming languages and environments. OpenShift Enterprise makes use of this technology to handle communications between the broker host and the node host in our deployment. In order to make use of this messaging service, we need to install and configure ActiveMQ for use on our broker node. </p>

<h2 id="installingactivemq"><strong>Installing ActiveMQ</strong></h2>

<p>Installing ActiveMQ on Red Hat Enterprise Linux 6 is a fairly easy and straightforward process as the packages are included in the rpm repositories that are already configured on your broker node. We want to install both the server and client packages by using the following command:</p>

<pre><code># yum install activemq activemq-client  
</code></pre>

<p>You will notice that this will also install any of the dependencies required for the packages if you don’t already have them. Notably, Java 1.6 and the libraries for use with the Ruby programming language. </p>

<h2 id="configuringactivemq"><strong>Configuring ActiveMQ</strong></h2>

<p>ActiveMQ uses an XML configuration file that is located at <em>/etc/activemq/activemq.xml</em>. </p>

<pre><code># cd /etc/activemq
# mv activemq.xml activemq.orig  
</code></pre>

<p>The above command will backup the default configuration file that ships with ActiveMQ and replace it with one configured for use with OpenShift Enterprise. Now that we have the configuration template, we need to make a few minor changes to the configuration. </p>

<p>The first change we need to make is to replace the hostname provided (activemq.example.com) to the FQDN of your broker host. For example, the following line: </p>

<p><strong>The activemq.xml file is available on the lab support website</strong> </p>

<pre><code>&lt;broker xmlns=&quot;http://activemq.apache.org/schema/core&quot; brokerName=&quot;activemq.example.com&quot; dataDirectory=&quot;${activemq.data}&quot;&gt;  
</code></pre>

<p>Should become: </p>

<pre><code>&lt;broker xmlns=&quot;http://activemq.apache.org/schema/core&quot; brokerName=&quot;broker.example.com&quot; dataDirectory=&quot;${activemq.data}&quot;&gt;  
</code></pre>

<p><strong>Note: The <em>${activemq.data}</em> text should be entered as stated as it does not refer to a shell variable</strong> </p>

<p>The second change is to provide your own credentials for authentication. The authentication information is stored inside of the <em><simpleAuthenticationPlugin></em> block of code. Make the changes that you desire to the following code block: </p>

<pre><code>&lt;simpleAuthenticationPlugin&gt;
   &lt;users&gt;
     &lt;authenticationUser username=&quot;mcollective&quot; password=&quot;marionette&quot; groups=&quot;mcollective,everyone&quot;/&gt;
     &lt;authenticationUser username=&quot;admin&quot; password=&quot;secret&quot; groups=&quot;mcollective,admin,everyone&quot;/&gt;
   &lt;/users&gt;
 &lt;/simpleAuthenticationPlugin&gt;  
</code></pre>

<h2 id="updatingthefirewallrulesandconfiguringactivemqtostartonboot"><strong>Updating the firewall rules and configuring ActiveMQ to start on boot</strong></h2>

<p>We need to modify the firewall rules to allow MCollective to communicate on port 61613. </p>

<pre><code># lokkit --port=61613:tcp  
</code></pre>

<p>Finally, we need to enable the ActiveMQ service to start on boot as well as start the service for the first time.</p>

<pre><code># chkconfig activemq on
# service activemq start  
</code></pre>

<h2 id="verifyingactivemqisworking"><strong>Verifying ActiveMQ is working</strong></h2>

<p>Now that ActiveMQ has been installed, configured, and started, let’s verify that the web console is working as expected. ActiveMQ web console should be running and listening on port 8161. In order to verify that everything worked correctly, load the following URL in a web browser: </p>

<pre><code>http://localhost:8161  
</code></pre>

<p><strong>Note:</strong> Given the current configuration, ActiveMQ is only available on the localhost. If you want to be able to connect to it via HTTP remotely, you will need to either enable a SSH port forwarding tunnel or you will need to add a rule to your firewall configuration:</p>

<pre><code># lokkit --port=8161:tcp
# ssh -f -N -L 8161:broker.example.com:8161 root@10.10.10.10  
</code></pre>

<figure>
<img src="http://training.runcloudrun.com/images/activemqconsole.png" alt="" /></figure>


<p><strong>Note:</strong> While we changed the authentication credentials for the ActiveMQ service itself, the above configuration requires no authentication for accessing the activemq console, which can still be accessed via a Web interface with default the credentials. For a production deployment, you would want to restrict access to localhost (127.0.0.1) and require authentication. The authentication information is stored in the <em>/etc/activemq/jetty.xml</em> configuration file as well as the <em>/etc/activemq/jetty-realm.properties</em> file. </p>

<p><strong>Lab 5 Complete!</strong> </p>

<!--BREAK-->

<h1 id="lab6:installingandconfiguringthemcollectiveclientestimatedtime:10minutes"><strong>Lab 6: Installing and configuring the MCollective client (Estimated time: 10 minutes)</strong></h1>

<p><strong>Server used:</strong></p>

<ul>
<li>broker host</li>
</ul>

<p><strong>Tools used:</strong></p>

<ul>
<li>text editor</li>
<li>yum</li>
</ul>

<p>For communication between the broker host and the gear nodes, OpenShift Enterprise uses MCollective. You may be wondering how MCollective is different from ActiveMQ, that we installed in a previous lab. ActiveMQ is the messenger server that provides a queue of transport messages. You can think of MCollective as the client that actually sends and receives those messages. For example, if we want to create a new gear on an OpenShift Enterprise node, MCollective would receive the create gear message from ActiveMQ and perform the operation. </p>

<h2 id="installingthemcollectiveclient"><strong>Installing the MCollective client</strong></h2>

<p>In order to use MCollective, we need to install and configure it.</p>

<pre><code># yum install mcollective-client  
</code></pre>

<h2 id="configuringthemcollectiveclient"><strong>Configuring the MCollective client</strong></h2>

<p>Replace the contents of the <em>/etc/mcollective/client.cfg</em> with the following information: </p>

<p><strong>The <em>/etc/mcollective/client.cfg</em> file is available on the lab support website</strong> </p>

<pre><code>topicprefix = /topic/  
main_collective = mcollective  
collectives = mcollective  
libdir = /usr/libexec/mcollective  
logfile = /var/log/mcollective-client.log  
loglevel = debug

# Plugins  
securityprovider = psk  
plugin.psk = unset  

connector = stomp  
plugin.stomp.host = localhost  
plugin.stomp.port = 61613  
plugin.stomp.user = mcollective  
plugin.stomp.password = marionette  
</code></pre>

<p>Here, we have configured the MCollective client to connect to ActiveMQ running on the local host. In a typical deployment, you will configure MCollective to connect to ActiveMQ running on a remote server by putting the appropriate hostname for the plugin.stomp.host setting. </p>

<p><strong>Lab 6 Complete!</strong> </p>

<!--BREAK-->

<h1 id="lab7:installingandconfiguringthebrokerapplicationestimatedtime:15minutes"><strong>Lab 7: Installing and configuring the broker application (Estimated time: 15 minutes)</strong></h1>

<p><strong>Server used:</strong></p>

<ul>
<li>broker host</li>
</ul>

<p><strong>Tools used:</strong></p>

<ul>
<li>text editor</li>
<li>yum</li>
<li>sed</li>
<li>chkconfig</li>
<li>lokkit</li>
<li>openssl</li>
<li>ssh-keygen</li>
<li>fixfiles</li>
<li>restorecon</li>
</ul>

<h2 id="installingnecessarypackagesforthebrokerapplication"><strong>Installing necessary packages for the broker application</strong></h2>

<p>In order for users to interact with the OpenShift Enterprise platform, they will typically use client tools or the web console. These tools communicate with the broker via a REST API that is also accessible for writing third party applications and tools. In order to use the broker application, we need to install several packages from the OpenShift Enterprise repository.</p>

<pre><code># yum install openshift-origin-broker openshift-origin-broker-util rubygem-openshift-origin-auth-remote-user rubygem-openshift-origin-msg-broker-mcollective rubygem-openshift-origin-dns-bind  
</code></pre>

<p><strong>Note:</strong> Depending on your connection and speed of your broker host, this installation make take several minutes. </p>

<h2 id="modifyingthebrokerproxyservername"><strong>Modifying the broker proxy server name</strong></h2>

<p>The default value of the ServerName property is localhost, and you need to change this to accurately reflect your broker&#8217;s host name. Run the following command to update your broker&#8217;s host name using sed: </p>

<pre><code># sed -i -e &quot;s/ServerName .*$/ServerName `hostname`/&quot; /etc/httpd/conf.d/000000_openshift_origin_broker_proxy.conf  
</code></pre>

<p><strong>Note:</strong> You can also manually update the <em>/etc/httpd/conf.d/000000_openshift_origin_broker_proxy.conf</em> and modify the ServerName attribute to reflect the correct hostname. </p>

<h2 id="configuringthefirewallandsettingservicetostartonboot"><strong>Configuring the firewall and setting service to start on boot</strong></h2>

<p>The broker application requires a number of services to be running in order to function properly. Instead of having to start these services each time the server boots, we can add them to startup at boot time.</p>

<pre><code># chkconfig httpd on
# chkconfig network on
# chkconfig ntpd on
# chkconfig sshd on  
</code></pre>

<p>We also need to modify the firewall rules to ensure that the traffic for these services is accepted:</p>

<pre><code># lokkit --service=ssh
# lokkit --service=https
# lokkit --service=http  
</code></pre>

<h2 id="generatingaccesskeys"><strong>Generating access keys</strong></h2>

<p>We now need to generate access keys that will allow some of the services, Jenkins for example, to communicate to the broker. </p>

<pre><code># openssl genrsa -out /etc/openshift/server_priv.pem 2048
# openssl rsa -in /etc/openshift/server_priv.pem -pubout &gt; /etc/openshift/server_pub.pem  
</code></pre>

<p>We also need to generate a ssh key pair that will allow communication between the broker host and any nodes that you have configured. Remember, the broker host is the director of communications and the node hosts actually contain all of the application gears that your users create. In order to generate this SSH keypair, perform the following commands:</p>

<pre><code># ssh-keygen -t rsa -b 2048 -f ~/.ssh/rsync_id_rsa  
</code></pre>

<p>Just press enter for the password.</p>

<pre><code># cp ~/.ssh/rsync_id_rsa* /etc/openshift/  
</code></pre>

<p>In a later lab that covers configuration of the node hosts, we will copy this newly created key to each node host. </p>

<h2 id="configuringselinuxbooleanvariablesandsettingfilecontexts"><strong>Configuring SELinux Boolean variables and setting file contexts</strong></h2>

<p>SELinux has several variables that we want to ensure are set correctly. These variables include the following:</p>

<table>
<caption id="section-mmd-tables-table1">SELinux Boolean Values</caption>
<colgroup>
<col style="text-align:left;"/>
<col style="text-align:left;"/>
</colgroup>

<thead>
<tr>
	<th style="text-align:left;">Variable Name</th>
	<th style="text-align:left;">Description</th>
</tr>
</thead>

<tbody>
<tr>
	<td style="text-align:left;">httpd_unified</td>
	<td style="text-align:left;">Allow the broker to write files in the &#8220;http&#8221; file context</td>
</tr>
<tr>
	<td style="text-align:left;">httpd_can_network_connect</td>
	<td style="text-align:left;">Allow the broker application to access the network</td>
</tr>
<tr>
	<td style="text-align:left;">httpd_can_network_relay</td>
	<td style="text-align:left;">Allow the SSL termination Apache instance to access the backend Broker application</td>
</tr>
<tr>
	<td style="text-align:left;">httpd_run_stickshift</td>
	<td style="text-align:left;">Enable passenger-related permissions</td>
</tr>
<tr>
	<td style="text-align:left;">named_write_master_zones</td>
	<td style="text-align:left;">Allow the broker application to configure DNS</td>
</tr>
<tr>
	<td style="text-align:left;">allow_ypbind</td>
	<td style="text-align:left;">Allow the broker application to use ypbind to communicate directly with the name server</td>
</tr>
</tbody>
</table>
<p>In order to set all of these variables correctly, enter the following:</p>

<pre><code># setsebool -P httpd_unified=on httpd_can_network_connect=on httpd_can_network_relay=on httpd_run_stickshift=on named_write_master_zones=on allow_ypbind=on  
</code></pre>

<p>We also need to set several files and directories with the proper SELinux contexts. Issue the following commands:</p>

<pre><code># fixfiles -R rubygem-passenger restore
# fixfiles -R mod_passenger restore
# restorecon -rv /var/run
# restorecon -rv /usr/share/rubygems/gems/passenger-*  
</code></pre>

<h2 id="understandingandchangingthebrokerconfiguration"><strong>Understanding and changing the broker configuration</strong></h2>

<p>The OpenShift Enterprise broker uses a configuration file to define several of the attributes for controlling how the platform as a service works. This configuration file is located at <em>/etc/openshift/broker.conf</em>. For instance, the valid gear types that a user can create are defined using the <em>VALID_GEAR_SIZES</em> variable.</p>

<pre><code># Comma separated list of valid gear sizes  
VALID_GEAR_SIZES=&quot;small,medium&quot;  
</code></pre>

<p>Edit this file and ensure that the <em>CLOUD_DOMAIN</em> variable is set to correctly reflect the domain that you are using to configure this deployment of OpenShift Enterprise.</p>

<pre><code># Domain suffix to use for applications (Must match node config)  
CLOUD_DOMAIN=&quot;example.com&quot;  
</code></pre>

<p>While you are in this file, you can change any other settings that need to be configured for your specific installation. </p>

<p><strong>Lab 7 Complete!</strong> </p>

<!--BREAK-->

<h1 id="lab8:configuringthebrokerpluginsandmongodbuseraccountsestimatedtime:15minutes"><strong>Lab 8: Configuring the broker plugins and MongoDB user accounts (Estimated time: 15 minutes)</strong></h1>

<p><strong>Server used:</strong></p>

<ul>
<li>broker host</li>
</ul>

<p><strong>Tools used:</strong></p>

<ul>
<li>text editor</li>
<li>cat</li>
<li>echo</li>
<li>environment variables</li>
<li>pushd</li>
<li>semodule</li>
<li>htpasswd</li>
<li>mongo</li>
<li>bundler</li>
<li>chkconfig</li>
<li>service</li>
</ul>

<p>OpenShift Enterprise uses a plugin system for core system components such as DNS, authentication, and messaging. In order to make use of these plugins, we need to configure them and provide the correct configuration items to ensure that they work correctly. The plugin configuration files are located in the <em>/etc/openshift/plugins.d</em> directory. We will be working with several of these files so it is suggested that you change to that directory to complete the steps in this lab.</p>

<pre><code># cd /etc/openshift/plugins.d  
</code></pre>

<p>Once you are in this directory, you will see that OpenShift Enterprise provides several example configuration files for you to use to speed up the process of configuring these plugins. You should see three example files.</p>

<ul>
<li>openshift-origin-auth-remote-user.conf.example</li>
<li>openshift-origin-dns-bind.conf.example</li>
<li>openshift-origin-msg-broker-mcollective.conf.example</li>
</ul>

<h2 id="creatingconfigurationfilesfromexamples"><strong>Creating configuration files from examples</strong></h2>

<p>Let’s begin by copying the .example files to actual configuration files that will be used by OpenShift Enterprise.</p>

<pre><code># cp openshift-origin-auth-remote-user.conf.example openshift-origin-auth-remote-user.conf
# cp openshift-origin-msg-broker-mcollective.conf.example openshift-origin-msg-broker-mcollective.conf  
</code></pre>

<p>The broker application will check the plugins.d directory for files ending in .conf. The presence of .conf file enables the corresponding plug-in. Thus, for example, copying the openshift-origin-auth-remote-user.conf.example file to openshift-origin-auth-remote-user.conf enables the auth-remote-user plug-in. </p>

<h2 id="configuringthednsplugin"><strong>Configuring the DNS plugin</strong></h2>

<p>Instead of copying the example DNS configuration file, we are going to create a new one by issuing an echo command. We are doing this to take advantage of the $domain and $keyfile environment variables that we created in a previous lab. If you are no longer have these variables set, you can recreate them with the following commands:</p>

<pre><code># domain=example.com
# keyfile=/var/named/${domain}.key
# cd /var/named
# KEY=&quot;$(grep Key: K${domain}*.private | cut -d ' ' -f 2)&quot;  
</code></pre>

<p>To verify that your variables were recreated correctly, echo the contents of your keyfile and verify your $KEY variable is set correctly:</p>

<pre><code># cat $keyfile
# echo $KEY  
</code></pre>

<p>If you performed the above steps correctly, you should see output similar to this: </p>

<pre><code>key example.com {
    algorithm HMAC-MD5;
    secret &quot;3RH8tLp6fvX4RVV9ny2lm0tZpTjXhB62ieC6CN1Fh/2468Z1+6lX4wpCJ6sfYH6u2+//gbDDStDX+aPMtSiNFw==&quot;;  
};
</code></pre>

<p>and </p>

<pre><code>3RH8tLp6fvX4RVV9ny2lm0tZpTjXhB62ieC6CN1Fh/2468Z1+6lX4wpCJ6sfYH6u2+//gbDDStDX+aPMtSiNFw==  
</code></pre>

<p>Now that we have our variables setup correctly, we can create our <em>openshift-origin-dns-bind.conf</em> file. <strong>Ensure that you are still in the <em>/etc/openshift/plugins.d</em> directory</strong> and issue the following command:</p>

<pre><code># cd /etc/openshift/plugins.d
# cat &lt;&lt; EOF &gt; openshift-origin-dns-bind.conf  
BIND_SERVER=&quot;127.0.0.1&quot;  
BIND_PORT=53  
BIND_KEYNAME=&quot;${domain}&quot;  
BIND_KEYVALUE=&quot;${KEY}&quot;  
BIND_ZONE=&quot;${domain}&quot;  
EOF  
</code></pre>

<p>After running this command, cat the contents of the file and ensure they look similar to the following: </p>

<pre><code>BIND_SERVER=&quot;127.0.0.1&quot;  
BIND_PORT=53  
BIND_KEYNAME=&quot;example.com&quot;  
BIND_KEYVALUE=&quot;3RH8tLp6fvX4RVV9ny2lm0tZpTjXhB62ieC6CN1Fh/2468Z1+6lX4wpCJ6sfYH6u2+//gbDDStDX+aPMtSiNFw==&quot;  
BIND_ZONE=&quot;example.com&quot;  
</code></pre>

<p>The last step to configure DNS is to compile and install the SELinux policy for the plugin.</p>

<pre><code># pushd /usr/share/selinux/packages/rubygem-openshift-origin-dns-bind/ &amp;&amp; make -f /usr/share/selinux/devel/Makefile ; popd
# semodule -i /usr/share/selinux/packages/rubygem-openshift-origin-dns-bind/dhcpnamedforward.pp  
</code></pre>

<h2 id="configuringanauthenticationplugin"><strong>Configuring an authentication plugin</strong></h2>

<p>OpenShift Enterprise supports various different authentication systems for authorizing a user. In a production environment, you will probably want to use LDAP, kerberos, or some other enterprise class authorization and authentication system. However, for this lab we will use a system called Basic Auth which relies on a <em>htpasswd</em> file to configure authentication. OpenShift Enterprise provides three example authentication configuration files in the <em>/var/www/openshift/broker/httpd/conf.d/</em> directory. </p>

<table>
<caption id="section-mmd-tables-table1">Authentication Sample Files</caption>
<colgroup>
<col style="text-align:left;"/>
<col style="text-align:left;"/>
</colgroup>

<thead>
<tr>
	<th style="text-align:left;">Authentication Type</th>
	<th style="text-align:left;">Description</th>
</tr>
</thead>

<tbody>
<tr>
	<td style="text-align:left;">Basic Auth</td>
	<td style="text-align:left;">openshift-origin-auth-remote-user-basic.conf.sample</td>
</tr>
<tr>
	<td style="text-align:left;">Kerberos</td>
	<td style="text-align:left;">openshift-origin-auth-remote-user-kerberos.conf.sample</td>
</tr>
<tr>
	<td style="text-align:left;">LDAP</td>
	<td style="text-align:left;">openshift-origin-auth-remote-user-ldap.conf.sample</td>
</tr>
</tbody>
</table>
<p>Since we will be using Basic Auth, we need to copy the sample configuration file to the actual configuration file:</p>

<pre><code># cp /var/www/openshift/broker/httpd/conf.d/openshift-origin-auth-remote-user-basic.conf.sample /var/www/openshift/broker/httpd/conf.d/openshift-origin-auth-remote-user.conf   
</code></pre>

<p>This configuration file specifies that the <em>AuthUserFile</em> is located at <em>/etc/openshift/htpasswd</em>. At this point, that file doesn’t exist, so we need to create it and add a user named <em>demo</em>.</p>

<pre><code># htpasswd -c /etc/openshift/htpasswd demo  
</code></pre>

<p><strong>Note: The -c option to htpasswd creates a new file, overwriting any existing htpasswd file. If your intention is to add a new user to an existing htpasswd file, simply drop the -c option.</strong> </p>

<p>After entering the above command, you will be prompted for a password for the user <em>demo</em>. Once you have provided that password, view the contents of the htpasswd file to ensure that the user was added correctly. Make a note of the password as we will using it during later labs.</p>

<pre><code># cat /etc/openshift/htpasswd  
</code></pre>

<p>If the operation was a success, you should see output similar to the following: </p>

<pre><code>demo:$apr1$Q7yO3MF7$rmSZ7SI.vITfEiLtkKSMZ/  
</code></pre>

<h2 id="addingamongodbaccount"><strong>Adding a MongoDB account</strong></h2>

<p>As previously discussed in this training class, OpenShift Enterprise makes heavy use of the MongoDB NOSQL database. In a previous lab, we installed and configured MongoDB but now we need to add a user for the broker application. If you take a look at the broker configuration file</p>

<pre><code># cat /etc/openshift/broker.conf |grep MONGO  
</code></pre>

<p>you will see that by default, the broker application is expecting a MongoDB user to be created called <em>openshift</em> with a password of <em>mooo</em>. At this point, you can either create a user with those credentials or create a separate user. If you create a separate user, ensure that you modify the broker.conf file to reflect the correct credentials.</p>

<pre><code># mongo openshift_broker_dev --eval 'db.addUser(&quot;openshift&quot;, &quot;mooo&quot;)'  
</code></pre>

<p>Once you have entered the above command, you should see the following output: </p>

<pre><code>MongoDB shell version: 2.0.2  
connecting to: openshift_broker_dev
{ &quot;n&quot; : 0, &quot;connectionId&quot; : 2, &quot;err&quot; : null, &quot;ok&quot; : 1 }
{  
    &quot;user&quot; : &quot;openshift&quot;,  
    &quot;readOnly&quot; : false,  
    &quot;pwd&quot; : &quot;8f5b96dbda3a3cd0120d6de44d8811a7&quot;,  
    &quot;_id&quot; : ObjectId(&quot;50e4665e60ce1894d530e1f1&quot;)
}  
</code></pre>

<h2 id="configuringbundler"><strong>Configuring Bundler</strong></h2>

<p>The broker rails application depends on several gem files in order to operate correctly. We need to ensure that bundler can find the appropriate gem files.</p>

<pre><code># cd /var/www/openshift/broker
# bundle --local  
</code></pre>

<p>You should see a lot of information scroll by letting you know what gem files the system is actually using. The last line of output should be: </p>

<pre><code>Your bundle is complete! Use `bundle show [gemname]` to see where a bundled gem is installed.  
</code></pre>

<h2 id="settingservicestostartonboot"><strong>Setting services to start on boot</strong></h2>

<p>The last step in configuring our broker application is to ensure that all of our services are started and that they are configured to start upon system boot.</p>

<pre><code># chkconfig openshift-broker on  
</code></pre>

<p>This will ensure that the broker starts upon next system boot. However, we also need to start the broker application to run now.</p>

<pre><code># service httpd start
# service openshift-broker start  
</code></pre>

<p><strong>Lab 8 Complete!</strong><br/>
<!--BREAK--> </p>

<h1 id="lab9:installingtheopenshiftenterprisewebconsoleestimatedtime:10minutes"><strong>Lab 9: Installing the OpenShift Enterprise Web Console (Estimated time: 10 minutes)</strong></h1>

<p><strong>Server used:</strong></p>

<ul>
<li>broker host</li>
</ul>

<p><strong>Tools used:</strong></p>

<ul>
<li>text editor</li>
<li>yum</li>
<li>service</li>
<li>chkconfig</li>
</ul>

<p>In this lab we want to install the OpenShift Enterprise Web Console. The console is written in ruby and will provide a great way for users of the system to create and manage application gears that are deployed on the gear hosts. </p>

<h2 id="installingthewebconsolerpms"><strong>Installing the Web Console RPMs</strong></h2>

<p>The installation of the web console can be performed with a simple <em>yum install</em> command but will pull in many dependencies from the ruby programming language. At the time of this writing, executing the following command installed 77 additional packages.</p>

<pre><code># yum install openshift-console  
</code></pre>

<p><strong>Note:</strong> Depending on your connection and speed of your broker host, this installation make take several minutes. </p>

<h2 id="configuringauthenticationfortheconsole"><strong>Configuring authentication for the console</strong></h2>

<p>In a previous lab, we configured the broker application for Basic Auth. When performing that lab, you actually configured authentication for the REST based API that the broker application provides. One of the great things about OpenShift Enterprise is that the console application uses a separate authenticate scheme for authenticating users to the web console. This will allow you to restrict which users you want to have access to the REST API and keep that authentication separate from the web based user console. </p>

<p>The openshift-console package that we installed previously in this lab created some sample authentication files for us. These files are located in the <em>/var/www/openshift/console/httpd/conf.d</em> directory. For this lab, we are going to use the same htpasswd file that we created when setting up the Broker Application authentication. In order to do this, simply issue the following commands:</p>

<pre><code># cd /var/www/openshift/console/httpd/conf.d
# cp openshift-origin-auth-remote-user-basic.conf.sample openshift-origin-auth-remote-user-basic.conf  
</code></pre>

<p>Now that we have the openshift-console packages installed, we need to start the service and ensure it starts on boot.</p>

<pre><code># service openshift-console start
# chkconfig openshift-console on  
</code></pre>

<p>Once completed, the console will now prompt the user to provide their login credentials as specified in the <em>/etc/openshift/htpasswd</em> file. </p>

<p><strong>Note: Seeing an error page after authenticating to the console is expected at this point. The web console will not be fully active until we add a node host in a later lab.</strong> </p>

<p><strong>Lab 9 Complete!</strong><br/>
<!--BREAK--> </p>

<h1 id="lab10:configuringdnsresolutionforthenodehostestimatedtime:20minutes"><strong>Lab 10: Configuring DNS resolution for the node host (Estimated time: 20 minutes)</strong></h1>

<p><strong>Servers used:</strong></p>

<ul>
<li>Node host</li>
<li>Broker host</li>
</ul>

<p><strong>Tools used:</strong></p>

<ul>
<li>text editor</li>
<li>yum</li>
<li>ntpdate</li>
<li>dig</li>
<li>oo-register-dns</li>
<li>cat</li>
<li>scp</li>
<li>ssh</li>
</ul>

<p><strong>Before proceeding with this lab, ensure that you are connected, via SSH, to your node host and subscribe to RHEL and OpenShift Enterprise repositories using <em>subscription-manager</em>.</strong> </p>

<h2 id="updatingtheoperatingsystemtothelatestpackages"><strong>Updating the operating system to the latest packages</strong></h2>

<p>During the training class, you were provided with credentials for two servers, a broker host and a node host. This lab begins with the configuration of your node / gear host. </p>

<p>Once you have successfully subscribed to the correct products, ensure that your operating system is updated to the latest packages.</p>

<pre><code># yum update  
</code></pre>

<h2 id="configuringtheclocktoavoidclockskew"><strong>Configuring the clock to avoid clock skew</strong></h2>

<p>OpenShift Enterprise requires NTP to synchronize the system and hardware clocks. This synchronization is necessary for communication between the broker and node hosts; if the clocks are too far out of synchronization, MCollective will drop messages. Every MCollective request includes a time stamp, provided by the sending host&#8217;s clock. If a sender&#8217;s clock is substantially behind a recipient&#8217;s clock, the recipient drops the message. This is often referred to as clock skew as is a common problem that users encounter when they fail to sync all of the system clocks.</p>

<pre><code># ntpdate clock.redhat.com
# chkconfig ntpd on
# service ntpd start  
</code></pre>

<h2 id="registeringadnsentryforthenodehost"><strong>Registering a DNS entry for the node host</strong></h2>

<p><strong>SSH to your broker application host</strong> that we configured in the previous labs and set a variable that points to your keyfile. If you have been using example.com, as stated in this lab manual, the following command should work.</p>

<pre><code># keyfile=/var/named/example.com.key  
</code></pre>

<p>If you did not use example.com, replace the above command with the correct location of your keyfile. </p>

<p>In order to configure your DNS to resolve your node host, we need to tell our BIND server about the host. Run the following command and <strong>replace the IP address with the correct IP address of your node</strong>.</p>

<pre><code># oo-register-dns -h node -d example.com -n 10.10.10.11 -k ${keyfile}  
</code></pre>

<p>Now that we have added node.example.com to our DNS server, the broker application host should be able to resolve the node host by referring to it by name. Let’s test this:</p>

<pre><code># dig @127.0.0.1 node.example.com  
</code></pre>

<p>This should resolve to 10.10.10.11, or the IP address that you specified when you ran the command. </p>

<h2 id="configuringsshkeyauthenticationbetweenbrokerandnode"><strong>Configuring SSH key authentication between broker and node</strong></h2>

<p>While on the broker application host, we need to copy the SSH key that we previously created to the node. This will allow operations to work from inside of OpenShift Enterprise without requiring a password. Once you connect to the broker host, copy the key with the following command: </p>

<p><strong>Note: Execute the following on the broker host.</strong></p>

<pre><code># scp /etc/openshift/rsync_id_rsa.pub root@node.example.com:/root/.ssh  
</code></pre>

<p>Once you enter that command, you will be prompted to authenticate to the node host. </p>

<p>At this point, we need to login to our node host to add the newly copied key to our authorized_keys. SSH into your node host and run the following: </p>

<p><strong>Note: Execute the following on the node host.</strong></p>

<pre><code># cat /root/.ssh/rsync_id_rsa.pub &gt;&gt; /root/.ssh/authorized_keys
# rm -f /root/.ssh/rsync_id_rsa.pub  
</code></pre>

<p>Now that our key has been copied from our broker application host to our node host, let’s verify that is copied correctly and was added to the authorized_keys file. Once you issue the following command, you should be authenticated to the node host without having to specify the root user password. </p>

<p><strong>Note: Execute the following on the broker host.</strong></p>

<pre><code># ssh -i /root/.ssh/rsync_id_rsa root@node.example.com  
</code></pre>

<h2 id="configuringdnsresolutiononthenode"><strong>Configuring DNS resolution on the node</strong></h2>

<p>We need to configure the node host to use the BIND server that we have installed and configured on the broker application host. This is a fairly straight forward process by adding the IP address of the broker application host to our <em>/etc/resolv.conf</em> on the node host. Edit this file and the following line making sure to use the correct IP address of your broker application server. </p>

<p><strong>Note: Execute the following on the node host.</strong> </p>

<pre><code>nameserver 10.10.10.10  
</code></pre>

<h2 id="configuringthedhcpclientandhostname"><strong>Configuring the DHCP client and hostname</strong></h2>

<p>On the node host, we need to configure our settings to prepend the DNS server we created in a previous lab to our resolv.conf file on system boot. This will allow the node host to resolve references to broker.example.com to ensure that all pieces of OpenShift Enterprise can communicate with one another. This process is similar to setting up the <em>dhclient-eht0.conf</em> configuration file for the broker application. </p>

<p><strong>Note:</strong> This step assumes that your node host is using the eth0 device for network connectivity. If that is not the case, replace eth0 with the correct Ethernet device for you host. </p>

<p>Edit the <em>/etc/dhcp/dhclient-eth0.conf</em> file, or add it if it doesn’t exist, and add the following information ensuring that you replace the IP address with the correct IP of your broker application host. </p>

<pre><code>prepend domain-name-servers 10.10.10.10;  
supersede host-name &quot;node&quot;;  
supersede domain-name &quot;example.com&quot;;  
</code></pre>

<p>We now need to set the hostname for node host to correctly reflect node.example.com. Edit the <em>/etc/sysconfig/network</em> file and change the <em>HOSTNAME</em> entry to the following: </p>

<pre><code>HOSTNAME=node.example.com  
</code></pre>

<p>We also need to set the hostname for our current session but issuing the hostname command at the command prompt.</p>

<pre><code># hostname node.example.com  
</code></pre>

<p>Verify that the hostname was set correctly by running the hostname command. If the hostname was set correctly, you should <em>node.example.com</em> as the output of the hostname command.</p>

<pre><code># hostname  
</code></pre>

<p><strong>Lab 10 Complete!</strong><br/>
<!--BREAK--> </p>

<h1 id="lab11:settingupmcollectiveonthenodehostestimatedtime:10minutes"><strong>Lab 11: Setting up MCollective on the node host (Estimated time: 10 minutes)</strong></h1>

<p><strong>Server used:</strong></p>

<ul>
<li>node host</li>
</ul>

<p><strong>Tools used:</strong></p>

<ul>
<li>text editor</li>
<li>yum</li>
<li>chkconfig</li>
<li>service</li>
<li>mco ping</li>
</ul>

<p>If you recall, MCollective is the tool that OpenShift Enterprise uses to send and receive messages via the ActiveMQ messaging server. In order for the node host, the client, to send and receive messages with the broker application, we need to install and configure MCollective on the node host to communicate with the broker application. </p>

<h2 id="installingmcollectiveonthenodehost"><strong>Installing MCollective on the node host</strong></h2>

<p>In order to install MCollective on the node host, we will need to install the <em>openshift-origin-msg-node-mcollective</em> package that is provided with your OpenShift Enterprise subscription.</p>

<pre><code># yum install openshift-origin-msg-node-mcollective  
</code></pre>

<p><strong>Note:</strong> Depending on your connection and speed of your broker host, this installation make take several minutes. </p>

<h2 id="configuringmcollectiveonthenodehost"><strong>Configuring MCollective on the node host</strong></h2>

<p>Now that we have MCollective installed on the node host, we need to configure the package to be able to communicate with the broker application service. In order to accomplish this, we want to replace the contents of the MCollective server.cfg configuration file to point to our correct stomp host. Edit the <em>/etc/mcollective/server.cfg</em> file and add the following information. If you used a different hostname for your broker application host, ensure that you provide the correct stomp host. You also need to ensure that you use the same username and password that you specified in the ActiveMQ configuration on the broker host. </p>

<p><strong>The <em>/etc/mcollective/server.cfg</em> file is available on the lab support website</strong> </p>

<pre><code>topicprefix = /topic/  
main_collective = mcollective  
collectives = mcollective  
libdir = /usr/libexec/mcollective  
logfile = /var/log/mcollective.log  
loglevel = debug  
daemonize = 1  
direct_addressing = n  
registerinterval = 30

# Plugins  
securityprovider = psk  
plugin.psk = unset  

connector = stomp  
plugin.stomp.host = broker.example.com  
plugin.stomp.port = 61613  
plugin.stomp.user = mcollective  
plugin.stomp.password = marionette

# Facts  
factsource = yaml  
plugin.yaml = /etc/mcollective/facts.yaml  
</code></pre>

<p><strong>Note: STOMP, or the Simple (or Streaming) Text Orientated Messaging Protocol, is the protocol used to encode MCollective messages for transport over ActiveMQ.</strong> </p>

<p>We need to ensure that MCollective is set to start on boot and also start the service for our current session.</p>

<pre><code># chkconfig mcollective on
# service mcollective start  
</code></pre>

<p>At this point, MCollective on the node host should be able to communicate with the broker application host. We can verify this by running the <em>mco ping</em> command on the broker.example.com host. </p>

<pre><code># mco ping  
</code></pre>

<p>If MCollective was installed and configured correctly, you should see node.example.com in the output from the previous command. </p>

<p><strong>Lab 11 Complete!</strong><br/>
<!--BREAK--> </p>

<h1 id="lab12:installingandconfiguringtheopenshiftenterprisenodepackagesestimatedtime:10minutes"><strong>Lab 12: Installing and configuring the OpenShift Enterprise node packages (Estimated time: 10 minutes)</strong></h1>

<p><strong>Server used:</strong></p>

<ul>
<li>node host</li>
</ul>

<p><strong>Tools used:</strong></p>

<ul>
<li>text editor</li>
<li>yum</li>
<li>lokkit</li>
<li>chkconfig</li>
</ul>

<p>Just as we installed specific packages that provide the source code and functionality for the broker application to work correctly, the node host also has a set of packages that need to be installed to properly identify the host as a node that will contain application gears. </p>

<h2 id="installingthecorepackages"><strong>Installing the core packages</strong></h2>

<p>The following packages are required for your node host to work correctly:</p>

<ul>
<li>rubygem-openshift-origin-node</li>
<li>rubygem-passenger-native</li>
<li>openshift-origin-port-proxy</li>
<li>openshift-origin-node-util</li>
</ul>

<p>Installing these packages can be performed in one yum install command.</p>

<pre><code># yum install rubygem-openshift-origin-node rubygem-passenger-native openshift-origin-port-proxy openshift-origin-node-util  
</code></pre>

<p><strong>Note:</strong> Depending on your connection and speed of your broker host, this installation make take several minutes. </p>

<h2 id="installingcartridgesthatthenodehostwillsupport"><strong>Installing cartridges that the node host will support</strong></h2>

<p>OpenShift Enterprise gears can be created based upon a cartridge that exists in the system. The cartridge provides the functionality that a consumer of the PaaS can use to create specific application types, databases, or other functionality. OpenShift Enterprise also provides an extensive cartridge API that will allow you to create your own custom cartridge types for your specific deployment needs. At the time of this writing, the following optional application cartridges are available for consumption on the node host.</p>

<ul>
<li>openshift-origin-cartridge-diy&#8211;0.1 diy (&#8220;do it yourself&#8221;) application type</li>
<li>openshift-origin-cartridge-haproxy&#8211;1.4 haproxy&#8211;1.4 support</li>
<li>openshift-origin-cartridge-jbossews&#8211;1.0 JBoss EWS Support</li>
<li>openshift-origin-cartridge-jbosseap&#8211;6.0 JBossEAP 6.0 support</li>
<li>openshift-origin-cartridge-jenkins&#8211;1.4 Jenkins server for continuous integration</li>
<li>openshift-origin-cartridge-ruby&#8211;1.9-scl Ruby 1.9 support</li>
<li>openshift-origin-cartridge-perl&#8211;5.10 mod_perl support</li>
<li>openshift-origin-cartridge-php&#8211;5.3 PHP 5.3 support</li>
<li>openshift-origin-cartridge-python&#8211;2.6 Python 2.6 support</li>
<li>openshift-origin-cartridge-ruby&#8211;1.8 Ruby Rack support running on Phusion Passenger (Ruby 1.8)</li>
</ul>

<p>If you want to provide scalable PHP applications for your consumers, you would want to install the openshift-origin-cartridge-haproxy&#8211;1.4 and the openshift-origin-cartridge-php&#8211;5.3 cartridges. </p>

<p>For database and other system related functionality, OpenShift Enterprise provides the following:</p>

<ul>
<li>openshift-origin-cartridge-cron&#8211;1.4 Embedded crond support</li>
<li>openshift-origin-cartridge-jenkins-client&#8211;1.4 Embedded jenkins client</li>
<li>openshift-origin-cartridge-mysql&#8211;5.1 Embedded MySQL server</li>
<li>openshift-origin-cartridge-postgresql&#8211;8.4 Embedded PostgreSQL server</li>
</ul>

<p>The only required cartridge is the openshift-origin-cartridge-cron&#8211;1.4 package. </p>

<p><strong>Note: If you are installing a multi-node configuration, it is important to remember that each node host <em>must</em> have the same cartridges installed.</strong> </p>

<p>Let’s start by installing the cron package, which is required for all OpenShift Enterprise deployments.</p>

<pre><code># yum install openshift-origin-cartridge-cron-1.4  
</code></pre>

<p>For this lab, let’s also assume that we want to only allow scalable PHP applications that can connect to MySQL on our OpenShift Enterprise deployment. Issue the following command to installed the required cartridges:</p>

<pre><code># yum install openshift-origin-cartridge-haproxy-1.4 openshift-origin-cartridge-php-5.3 openshift-origin-cartridge-mysql-5.1  
</code></pre>

<p>For a complete list of all cartridges that you are entitled to install, you can perform a search using the yum command that will output all OpenShift Enterprise cartridges.</p>

<pre><code># yum search origin-cartridge  
</code></pre>

<h2 id="startingrequiredservicesonthenodehost"><strong>Starting required services on the node host</strong></h2>

<p>The node host will need to allow HTTP, HTTPS, and SSH traffic to flow through the firewall. We also want to ensure that the httpd, network, and sshd services are set to start on boot.</p>

<pre><code># lokkit --service=ssh
# lokkit --service=https
# lokkit --service=http
# chkconfig httpd on
# chkconfig network on
# chkconfig sshd on  
</code></pre>

<p><strong>Lab 12 Complete!</strong><br/>
<!--BREAK--> </p>

<h1 id="lab13:configuringpamnamespacemodulelinuxcontrolgroupscgroupsanduserquotasestimatedtime:10minutes"><strong>Lab 13: Configuring PAM namespace module, Linux control groups (cgroups), and user quotas (Estimated time: 10 minutes)</strong></h1>

<p><strong>Server used:</strong></p>

<ul>
<li>node host</li>
</ul>

<p><strong>Tools used:</strong></p>

<ul>
<li>text editor</li>
<li>sed</li>
<li>restorecon</li>
<li>chkconfig</li>
<li>service</li>
<li>mount</li>
<li>quotacheck</li>
</ul>

<h2 id="configuringpamtousetheopenshiftenterpriseconfiguration"><strong>Configuring PAM to use the OpenShift Enterprise configuration</strong></h2>

<p>The pam_namespace PAM module sets up a private namespace for a session with polyinstantiated directories. A polyinstantiated directory provides a different instance of itself based on user name, or when using SELinux, user name, security context or both. OpenShift Enterprise ships with its own PAM configuration and we need to configure the node to use the configuration.</p>

<pre><code># sed -i -e 's|pam_selinux|pam_openshift|g' /etc/pam.d/sshd  
</code></pre>

<p>You also need to enter the following script on the command line: </p>

<p><strong>This script is available for download from the lab support website.</strong> </p>

<pre><code>for f in &quot;runuser&quot; &quot;runuser-l&quot; &quot;sshd&quot; &quot;su&quot; &quot;system-auth-ac&quot;; \  
do t=&quot;/etc/pam.d/$f&quot;; \  
if ! grep -q &quot;pam_namespace.so&quot; &quot;$t&quot;; \  
then echo -e &quot;session\t\trequired\tpam_namespace.so no_unmount_on_close&quot; &gt;&gt; &quot;$t&quot; ; \  
fi; \  
done;  
</code></pre>

<h2 id="configuringlinuxcontrolgroupscgroups"><strong>Configuring Linux Control Groups (cgroups)</strong></h2>

<p>Cgroups allows you to allocate resources—such as CPU time, system memory, network bandwidth, or combinations of these resources—among user-defined groups of tasks (processes) running on a system. You can monitor the cgroups you configure, deny cgroups access to certain resources, and even reconfigure your cgroups dynamically on a running system. </p>

<p>Run the following command to configure cgroups for OpenShift Enterprise.</p>

<pre><code># cp -f /usr/share/doc/rubygem-openshift-origin-node-*/cgconfig.conf /etc/cgconfig.conf
# restorecon -v /etc/cgconfig.conf
# mkdir /cgroup
# restorecon -v /cgroup
# chkconfig cgconfig on
# chkconfig cgred on
# chkconfig openshift-cgroups on
# service cgconfig restart
# service cgred restart
# service openshift-cgroups start  
</code></pre>

<p>In order for cgroups to work correctly, you need to ensure that services are started in the correct order.</p>

<ul>
<li>service cgconfig start</li>
<li>service cgcred start</li>
<li>service openshift-cgroups start</li>
</ul>

<p>To verify that your cgroups configuration is correct, let’s check a few security contexts:</p>

<pre><code># ls -alZ /etc/cgconfig.conf  
</code></pre>

<p>Output should be: </p>

<pre><code>-rw-r--r--. root root system_u:object_r:cgconfig_etc_t:s0 /etc/cgconfig.conf  
</code></pre>

<p>The context of the /cgroups directory: </p>

<pre><code>ls -alZ /|grep cgroup  
</code></pre>

<p>Output should be: </p>

<pre><code>drwxr-xr-x. root root system_u:object_r:cgroup_t:s0    cgroup  
</code></pre>

<h2 id="settingupdiskquotas"><strong>Setting up disk quotas</strong></h2>

<p>When a consumer of OpenShift Enterprise creates an application gear, we need to be able to control and set the amount of disk space that the gear can consume. This configuration is located in the <em>/etc/openshift/resource_limits.conf</em> file. The two settings of interest are the qouta_files and the quota_blocks. The quota_files setting specifies the total number of files that a gear / user is allowed to own. The quota_blocks is the actual amount of disk storage that the gear is allowed to consume — where 1 block is equal to 1024 bytes. </p>

<p>In order to enable <em>usrqouta</em> on the filesystem, you will need to add the <em>usrquote</em> option in the <em>/etc/fstab</em> for the mount of /var/lib/openshift. In this lab, the /var/lib/openshift directory is mounted as part of the root filesystem. The corresponding line in the /etc/fstab file looks like </p>

<pre><code>/dev/mapper/VolGroup-lv_root /                       ext4    defaults        1 1  
</code></pre>

<p>In order to add the usrquote option to this mount point, change the entry to the following: </p>

<pre><code>/dev/mapper/VolGroup-lv_root /                       ext4    defaults,usrquota        1 1  
</code></pre>

<p><strong>This file is available for download from the lab support website.</strong> </p>

<p>For the usrquota option to take effect, we need to reboot the node host or simply remount the filesystem.</p>

<pre><code># mount -o remount /  
</code></pre>

<p>And then generate user quota info for the mount point:</p>

<pre><code># quotacheck -cmug /  
</code></pre>

<p><strong>Lab 13 Complete!</strong><br/>
<!--BREAK--> </p>

<h1 id="lab14:configuringselinuxandsystemcontrolsettingsestimatedtime:5minutes"><strong>Lab 14: Configuring SELinux and System Control Settings (Estimated time: 5 minutes)</strong></h1>

<p><strong>Server used:</strong></p>

<ul>
<li>node host</li>
</ul>

<p><strong>Tools used:</strong></p>

<ul>
<li>text editor</li>
<li>setsebool</li>
<li>fixfiles</li>
<li>restorecon</li>
<li>sysctl</li>
</ul>

<h2 id="configuringselinux"><strong>Configuring SELinux</strong></h2>

<p>The OpenShift Enterprise node requires several SELinux boolean values to be set in order to operate correctly.</p>

<table>
<caption id="section-mmd-tables-table1">SELinux Boolean Values</caption>
<colgroup>
<col style="text-align:left;"/>
<col style="text-align:left;"/>
</colgroup>

<thead>
<tr>
	<th style="text-align:left;">Variable Name</th>
	<th style="text-align:left;">Description</th>
</tr>
</thead>

<tbody>
<tr>
	<td style="text-align:left;">httpd_unified</td>
	<td style="text-align:left;">Allow the broker to write files in the &#8220;http&#8221; file context</td>
</tr>
<tr>
	<td style="text-align:left;">httpd_can_network_connect</td>
	<td style="text-align:left;">Allow the broker application to access the network</td>
</tr>
<tr>
	<td style="text-align:left;">httpd_can_network_relay</td>
	<td style="text-align:left;">Allow the SSL termination Apache instance to access the backend Broker application</td>
</tr>
<tr>
	<td style="text-align:left;">httpd_run_stickshift</td>
	<td style="text-align:left;">Enable passenger-related permissions</td>
</tr>
<tr>
	<td style="text-align:left;">httpd_read_user_content</td>
	<td style="text-align:left;">Allow the node to read application data</td>
</tr>
<tr>
	<td style="text-align:left;">httpd_enable_homedirs</td>
	<td style="text-align:left;">Allow the node to read application data</td>
</tr>
<tr>
	<td style="text-align:left;">allow_polyinstantiation</td>
	<td style="text-align:left;">Allow polyinstantiation for gear containment</td>
</tr>
</tbody>
</table>
<p>To set these values and then relabel files to the correct context, issue the following commands:</p>

<pre><code># setsebool -P httpd_unified=on httpd_can_network_connect=on httpd_can_network_relay=on httpd_read_user_content=on httpd_enable_homedirs=on httpd_run_stickshift=on allow_polyinstantiation=on
# restorecon -rv /var/run
# restorecon -rv /usr/sbin/mcollectived /var/log/mcollective.log /var/run/mcollectived.pid
# restorecon -rv /var/lib/openshift /etc/openshift/node.conf /etc/httpd/conf.d/openshift  
</code></pre>

<h2 id="configuringsystemcontrolsettings"><strong>Configuring System Control Settings</strong></h2>

<p>We need to modify the <em>/etc/sysctl.conf</em> configuration file to increase the number of kernel semaphores (to allow many httpd processes), increase the number ephemeral ports, and to also increase the connection tracking table size. Edit the file in your favorite text editor and add the following lines to the bottom of the file:</p>

<pre><code># Added for OpenShift Enterprise  
kernel.sem = 250  32000 32  4096  
net.ipv4.ip_local_port_range = 15000 35530  
net.netfilter.nf_conntrack_max = 1048576      
</code></pre>

<p>Once the changes have been made, we need to reload the configuration file.</p>

<pre><code># sysctl -p /etc/sysctl.conf  
</code></pre>

<p><strong>Lab 14 Complete!</strong><br/>
<!--BREAK--> </p>

<h1 id="lab15:configuringsshopenshiftportproxyandnodeconfigurationestimatedtime:20minutes"><strong>Lab 15: Configuring SSH, OpenShift Port Proxy, and node configuration (Estimated time: 20 minutes)</strong></h1>

<p><strong>Server used:</strong></p>

<ul>
<li>node host</li>
</ul>

<p><strong>Tools used:</strong></p>

<ul>
<li>text editor</li>
<li>perl</li>
<li>lokkit</li>
<li>chkconfig</li>
<li>service</li>
<li>openshift-facts</li>
</ul>

<h2 id="configuringsshtopassthroughthegit_sshenvironmentvariable"><strong>Configuring SSH to pass through the <em>GIT_SSH</em> environment variable</strong></h2>

<p>Edit the <em>/etc/ssh/sshd_config</em> file and add the following lines</p>

<pre><code># Added to pass the GIT_SSH environment variable  
AcceptEnv GIT_SSH  
</code></pre>

<p>When a developer pushes a change up to their OpenShift Enterprise gear, an SSH connection is created. Because this may result in a high number of connections, we need to increase the limit of the number of connections allowed to the node host.</p>

<pre><code># perl -p -i -e &quot;s/^#MaxSessions .*$/MaxSessions 40/&quot; /etc/ssh/sshd_config
# perl -p -i -e &quot;s/^#MaxStartups .*$/MaxStartups 40/&quot; /etc/ssh/sshd_config  
</code></pre>

<h2 id="configuringtheportproxy"><strong>Configuring the port proxy</strong></h2>

<p>Multiple application gears can and will reside on the same node host. In order for these applications to receive HTTP requests to the node, we need to configure a proxy that will pass traffic to the gear application that is listening for connections on the loopback address. We need to open up a range of ports that the node can accept traffic on as well as ensure the port-proxy is started on boot.</p>

<pre><code># lokkit --port=35531-65535:tcp
# chkconfig openshift-port-proxy on
# service openshift-port-proxy start  
</code></pre>

<p>If a node is restarted, we want to ensure that the gear applications are also restarted. OpenShift Enterprise provides a script to accomplish this task, but we need to configure the service to start on boot.</p>

<pre><code># chkconfig openshift-gears on  
</code></pre>

<h2 id="configuringnodesettingsfordomainname"><strong>Configuring node settings for domain name</strong></h2>

<p>Edit the <em>/etc/openshift/node.conf</em> file and specify the correct settings for your <em>CLOUD_DOMAIN, PUBLIC_HOSTNAME, and BROKER_HOST</em> IP address. For example, given the information in this lab, my settings are as follows: </p>

<pre><code>PUBLIC_HOSTNAME=&quot;node.example.com&quot;       # The node host's public hostname  
PUBLIC_IP=“10.10.10.10”                                      # The node host's public IP address  
BROKER_HOST=&quot;broker.example.com&quot;              # IP or DNS name of broker host for REST API  
</code></pre>

<h2 id="updatingthefacterdatabase"><strong>Updating the <em>facter</em> database</strong></h2>

<p>Facter generates metadata files for MCollective and is normally run by cron. Run the following command to execute facter immediately to create the initial database and ensure that it runs properly: </p>

<pre><code># /etc/cron.minutely/openshift-facts  
</code></pre>

<h2 id="rebootingthenode"><strong>Rebooting the node</strong></h2>

<p>In order to verify that all services were installed and configured correctly, I suggest that you restart the node to ensure that all services start on boot as described in this post. </p>

<h2 id="testingtheconfiguration"><strong>Testing the configuration</strong></h2>

<p>If everything in the current, and all previous labs were completed successfully, we can now test our deployment of OpenShift Enterprise. During this lab, we will setup an SSH tunnel to allow us to communicate with the broker and node hosts. The will allow us to connect to localhost on our lab machine and all traffic will be forwarded to your OpenShift Enterprise installation. In the next lab, we will update our local machines to point directly to the DNS server that we installed in Lab 2, but for now, an SSH tunnel will allow us to test the installation. </p>

<p>On your local machine, issue the following command, replacing the IP address with the IP address of your broker node:</p>

<pre><code># sudo ssh -f -N -L 80:broker.example.com:80 -L 8161:broker.example.com:8161 -L 443:broker.example.com:443 root@10.4.59.x  
</code></pre>

<p>We have to use the sudo command in order to allow forwarding of low range ports. Once, you have entered the above command, and authenticated correctly, you should be able to view the web console by pointing your local browser to: </p>

<pre><code>http://127.0.0.1  
</code></pre>

<p>You will notice that you may, depending on your browser settings, have to accept the SSL certificate. In Firefox, the page will look similar to this: </p>

<figure>
<img src="http://training.runcloudrun.com/images/cert.png" alt="" /></figure>


<p>Once you have accepted and added the SSL certificate, you will prompted to authenticate to the OpenShift console. Use the credentials that we created in a previous lab, which should be:</p>

<ul>
<li>Username: demo</li>
<li>Password: demo</li>
</ul>

<p>After you have authenticated, you should be presented with the OpenShift web console as shown below: </p>

<figure>
<img src="http://training.runcloudrun.com/images/console.png" alt="" /></figure>


<p>If you do not see the expected content, consult the troubleshooting section at the end of this manual. </p>

<p><strong>Lab 15 Complete!</strong><br/>
<!--BREAK--> </p>

<h1 id="lab16:configuringlocalmachinefordnsresolutionestimatedtime:10minutes"><strong>Lab 16: Configuring local machine for DNS resolution (Estimated time: 10 minutes)</strong></h1>

<p><strong>Server used:</strong></p>

<ul>
<li>local machine</li>
</ul>

<p><strong>Tools used:</strong></p>

<ul>
<li>text editor</li>
<li>networking tools</li>
</ul>

<p>At this point, we should have a complete OpenShift Enterprise installation working correctly on the lab machines that were provided to you by the instructor. During the next portion of the training, we will be focussing on administration and usage of the OpenShift Enterprise PaaS. To make performing these tasks easier, it is suggested that you add the DNS server that we created in lab 2 to be the first nameserver that your local machine uses to resolve hostnames. The process for this varies depending on the operating system. This lab manual will cover the configuration for both the Linux and Mac operating systems. If you are using a Microsoft Windows operating system, consult the instructor for instructions on how to perform this lab. </p>

<h2 id="configuringexample.comresolutionforlinux"><strong>Configuring example.com resolution for Linux</strong></h2>

<p>If you are using Linux, the process for updating your name server is straightforward. Simply edit the <em>/etc/resolv.conf</em> configuration file and add the IP address of your broker node as the first entry. For example, add the following at the top of the file, replacing the 10.x.x.x IP address with the correct address of your broker node. </p>

<pre><code>nameserver 10.4.59.x  
</code></pre>

<p>Once you have added the above nameserver, you should be able to communicate with your OpenShift Enterprise PaaS by using the server hostname. To test this out, ping the broker and node hosts from your local machine:</p>

<pre><code>$ ping broker.example.com
$ ping node.example.com  
</code></pre>

<h2 id="configuringexample.comresolutionforosx"><strong>Configuring example.com resolution for OS X</strong></h2>

<p>If you are using OSX, you will notice that the operating has a <em>/etc/resolv.conf</em> configuration file. However, the operating system does not respect this file and requires users to edit the DNS servers via the <em>System Preferences</em> tool. </p>

<p>Open up the <em>System Preferences</em> tool and select the <em>Network</em> utility: </p>

<figure>
<img src="http://training.runcloudrun.com/images/network.png" alt="" /></figure>


<p>On the bottom left hand corner of the <em>Network</em> utility, ensure that the lock button is unlocked to enable user modifications to the DNS configuration. Once you have unlocked the system for changes, locate the ethernet device that is providing connectivity for your machine and click the advanced button: </p>

<figure>
<img src="http://training.runcloudrun.com/images/network2.png" alt="" /></figure>


<p>Select the DNS tab at the top of the window: </p>

<figure>
<img src="http://training.runcloudrun.com/images/network3.png" alt="" /></figure>


<p><strong>Note:</strong> Make a list of the current DNS servers that you have configured for your operating system. When you add a new one, OSX removes the existing servers forcing you to add them back. </p>

<p>Click the <em>+</em> button to add a new DNS server and enter the 10.4.59.x IP address of your broker host. </p>

<figure>
<img src="http://training.runcloudrun.com/images/network4.png" alt="" /></figure>


<p><strong>Note:</strong> Add your existing nameservers back that you made a note of above. </p>

<p><strong>Note:</strong> After this training class, remember to remove the DNS server for your broker host. </p>

<p>After you have applied the changes, we can now test that name resolution is working correctly. To test this out, ping the broker and node hosts from your local machine:</p>

<pre><code>$ ping broker.example.com
$ ping node.example.com  
</code></pre>

<p><strong>Lab 16 Complete!</strong><br/>
<!--BREAK--> </p>

<h1 id="lab17:addingcartridgesestimatedtime:10minutes"><strong>Lab 17: Adding cartridges (Estimated time: 10 minutes)</strong></h1>

<p><strong>Server used:</strong></p>

<ul>
<li>node host</li>
<li>broker host</li>
</ul>

<p><strong>Tools used:</strong></p>

<ul>
<li>yum</li>
<li>bundle</li>
</ul>

<p>By default, OpenShift Enterprise caches certain values for faster retrieval. Clearing this cache allows the retrieval of updated settings. </p>

<p>For example, the first time MCollective retrieves the list of cartridges available on your nodes, the list is cached so that subsequent requests for this information are processed more quickly. If you install a new cartridge, it is unavailable to users until the cache is cleared and MCollective retrieves a new list of cartridges. </p>

<p>This lab will focus on installing cartridges to allow OpenShift Enterprise to create JBoss gears. </p>

<h2 id="listingavailablecartridgesforyoursubscription"><strong>Listing available cartridges for your subscription</strong></h2>

<p>For a complete list of all cartridges that you are entitled to install, you can perform a search using the yum command that will output all OpenShift Enterprise cartridges.</p>

<pre><code># yum search origin-cartridge  
</code></pre>

<p>During this lab, you should see the following cartridges available to install:</p>

<ul>
<li>openshift-origin-cartridge-abstract.noarch : OpenShift common cartridge components</li>
<li>openshift-origin-cartridge-cron&#8211;1.4.noarch : Embedded cron support for express</li>
<li>openshift-origin-cartridge-diy&#8211;0.1.noarch : Provides diy support</li>
<li>openshift-origin-cartridge-haproxy&#8211;1.4.noarch : Provides embedded haproxy&#8211;1.4 support</li>
<li>openshift-origin-cartridge-jbosseap&#8211;6.0.noarch : Provides JBossEAP6.0 support</li>
<li>openshift-origin-cartridge-jbossews&#8211;1.0.noarch : Provides JBossEWS1.0 support</li>
<li>openshift-origin-cartridge-jenkins&#8211;1.4.noarch : Provides jenkins&#8211;1.4 support</li>
<li>openshift-origin-cartridge-jenkins-client&#8211;1.4.noarch : Embedded jenkins client support for express</li>
<li>openshift-origin-cartridge-mysql&#8211;5.1.noarch : Provides embedded mysql support</li>
<li>openshift-origin-cartridge-perl&#8211;5.10.noarch : Provides mod_perl support</li>
<li>openshift-origin-cartridge-php&#8211;5.3.noarch : Provides php&#8211;5.3 support</li>
<li>openshift-origin-cartridge-postgresql&#8211;8.4.noarch : Provides embedded PostgreSQL support</li>
<li>openshift-origin-cartridge-python&#8211;2.6.noarch : Provides python&#8211;2.6 support</li>
<li>openshift-origin-cartridge-ruby&#8211;1.8.noarch : Provides ruby rack support running on Phusion Passenger</li>
<li>openshift-origin-cartridge-ruby&#8211;1.9-scl.noarch : Provides ruby rack support running on Phusion Passenger</li>
</ul>

<h2 id="installingjbosssupport"><strong>Installing JBoss support</strong></h2>

<p>In order to enable consumers of the PaaS to create JBoss gears, we will need to install all of the necessary cartridges for the application server and supporting build systems. Perform the following command to install the required cartridges: </p>

<p><strong>Note:</strong> Execute the following on the node host.</p>

<pre><code># yum install openshift-origin-cartridge-jbosseap-6.0.noarch openshift-origin-cartridge-jbossews-1.0.noarch openshift-origin-cartridge-jenkins–1.4.noarch openshift-origin-cartridge-jenkins-client–1.4.noarch  
</code></pre>

<p>The above command will allow users to create JBoss EAP and JBoss EWS gears. We also installed support for the Jenkins continuous integration environment which we will cover in a later lab. At the time of this writing, the above command will download and install an additional 285 packages on your node host. </p>

<p><strong>Note:</strong> Depending on your connection and speed of your node host, this installation make take several minutes. </p>

<h2 id="clearingthebrokerapplicationcache"><strong>Clearing the broker application cache</strong></h2>

<p>At this point, you will notice that if you try to create a JBoss based application via the web console, that the application type is not available. This is because the broker host creates a cache of available gear types to increase performance. After adding a new cartridge, you need to clear this cache in order for the new gear type to be available to users. </p>

<p><strong>Note:</strong> Execute the following on the broker host.</p>

<pre><code># cd /var/www/openshift/broker
# bundle exec rake tmp:clear  
</code></pre>

<p>It may take several minutes before you see the new cartridges available on the web console as it takes a few minutes for the cache to completely clear. </p>

<h2 id="testingnewcartridges"><strong>Testing new cartridges</strong></h2>

<p>Given the steps in lab 16 of this training, you should be able to access the web console from a web browser using your local machine. Open up your preferred browser and enter the following URL: </p>

<pre><code>http://broker.example.com  
</code></pre>

<p>You will be prompted to authenticate and then be presented with an application creation screen. After the cache has been cleared, and assuming you have added the new cartridges correctly, you should see a screen similar to the following: </p>

<figure>
<img src="http://training.runcloudrun.com/images/console-jboss.png" alt="" /></figure>


<p>If you do not see the new cartridges available on the web console, check that the new cartridges are available by viewing the contents of the <em>/usr/libexec/openshift/cartridges</em> directory:</p>

<pre><code># cd /usr/libexec/openshift/cartridges
# ls  
</code></pre>

<h2 id="installingthepostgresqlanddiycartridges"><strong>Installing the PostgreSQL and DIY cartridges</strong></h2>

<p>Using the knowledge that you have gained during in this lab, perform the necessary commands to install both the PostgreSQL and DIY cartridges on your node host. Verify the success of the installation by ensuring that the DIY application type is available on the web console: </p>

<figure>
<img src="http://training.runcloudrun.com/images/console-diy.png" alt="" /></figure>


<p><strong>Lab 17 Complete!</strong><br/>
<!--BREAK--> </p>

<h1 id="lab18:managingresourcesestimatedtime:10minutes"><strong>Lab 18: Managing resources (Estimated time: 10 minutes)</strong></h1>

<p><strong>Server used:</strong></p>

<ul>
<li>node host</li>
<li>broker host</li>
</ul>

<p><strong>Tools used:</strong></p>

<ul>
<li>text editor</li>
<li>oo-admin-ctl-user</li>
</ul>

<h2 id="settingdefaultgearquotasandsizes"><strong>Setting default gear quotas and sizes</strong></h2>

<p>A users default gear size and quota is specified in the <em>/etc/openshift/broker.conf</em> configuration file located on the broker host. </p>

<p>The <em>VALID_GEAR_SIZES</em> setting is not applied to users but specifies the gear sizes that the current OpenShift Enterprise PaaS installation supports. </p>

<p>The <em>DEFAULT_MAX_GEARS</em> settings specifies the number of gears to assign to all users upon user creation. This is the total number of gears that a user can create by default. </p>

<p>The <em>DEFAULT_GEAR_SIZE</em> setting is the size of gear that a newly created user has access to. </p>

<p>Take a look at the <em>/etc/openshift/broker.conf</em> configuration file to determine the current settings for your installation: </p>

<p><strong>Note:</strong> Execute the following on the broker host.</p>

<pre><code># cat /etc/openshift/broker.conf  
</code></pre>

<p>By default, OpenShift Enterprise sets the default gear size to small and the number of gears a user can create to 100. </p>

<p>When changing the <em>/etc/openshift/broker.conf</em> configuration file, keep in mind that the existing settings are cached until you restart the <em>openshift-broker</em> service. </p>

<h2 id="settingthenumberofgearsaspecificusercancreate"><strong>Setting the number of gears a specific user can create</strong></h2>

<p>There are often times when you want to increase or decrease the number of gears a particular user can consume without modifying the setting for all existing users. OpenShift Enterprise provides a command that will allow the administrator to configure settings for an individual user. To see all of the available options that can be performed on a specific user, enter the following command:</p>

<pre><code># oo-admin-ctl-user  
</code></pre>

<p>To see how many gears that our <em>demo</em> user has consumed as well as how many gears the <em>demo</em> user has access to create, you can provide the following switches to the <em>oo-admin-ctl-user</em> command:</p>

<pre><code># oo-admin-ctl-user -l demo  
</code></pre>

<p>Given the current state of our configuration for this training class, you should see the following output: </p>

<pre><code>User demo:
    consumed gears: 0
    max gears: 100
    gear sizes: small
</code></pre>

<p>In order to change the number of gears that our <em>demo</em> user has permission to create, you can pass the —setmaxgears switch to the command. For instance, if we only want to allow the <em>demo</em> user to be able to create 25 gears, we would use the following command:</p>

<pre><code># oo-admin-ctl-user -l demo --setmaxgears 25  
</code></pre>

<p>After entering the above command, you should see the following output: </p>

<pre><code>Setting max_gears to 25... Done.  
User demo:
  consumed gears: 0
  max gears: 25
  gear sizes: small
</code></pre>

<h2 id="settingthetypeofgearsaspecificusercancreate"><strong>Setting the type of gears a specific user can create</strong></h2>

<p>In a production environment, a customer will typically have different gear sizes that are available for developers to consume. For this lab, we will only create small gears. However, to add the ability to create medium size gears for the <em>demo</em> user, you can pass the -addgearsize switch to the <em>oo-admin-ctl-user</em> command. </p>

<pre><code># oo-admin-ctl-user -l demo --addgearsize medium  
</code></pre>

<p>After entering the above command, you should see the following output: </p>

<pre><code>Adding gear size medium for user demo... Done.  
User demo:
  consumed gears: 0
  max gears: 25
  gear sizes: small, medium
</code></pre>

<p>In order to remove the ability for a user to create a specific gear size, you can use the &#8211;removegearsize switch:</p>

<pre><code># oo-admin-ctl-user -l demo --removegearsize medium
</code></pre>

<p><strong>Lab 18 Complete!</strong><br/>
<!--BREAK--> </p>

<h1 id="lab19:managingdistrictsestimatedtime:10minutes"><strong>Lab 19: Managing districts (Estimated time: 10 minutes)</strong></h1>

<p><strong>Server used:</strong></p>

<ul>
<li>node host</li>
<li>broker host</li>
</ul>

<p><strong>Tools used:</strong></p>

<ul>
<li>text editor</li>
<li>oo-admin-ctl-district</li>
</ul>

<p>Districts define a set of node hosts within which gears can be easily moved to load-balance the resource usage of those nodes. While not required for a basic OpenShift Enterprise installation, districts provide several administrative benefits and their use is recommended. </p>

<p>Districts allow a gear to maintain the same UUID (and related IP addresses, MCS levels and ports) across any node within the district, so that applications continue to function normally when moved between nodes on the same district. All nodes within a district have the same profile, meaning that all the gears on those nodes are the same size (for example small or medium). There is a hard limit of 6000 gears per district. </p>

<p>This means, for example, that developers who hard-code environment settings into their applications instead of using environment variables will not experience problems due to gear migrations between nodes. The application continues to function normally because exactly the same environment is reserved for the gear on every node in the district. This saves developers and administrators time and effort. </p>

<h2 id="enablingdistricts"><strong>Enabling districts</strong></h2>

<p>To use districts, the broker’s MCollective plugin must be configured to enable districts. Edit the <em>/etc/openshift/plugins.d/openshift-origin-msg-broker-mcollective.conf</em> configuration file and confirm the following parameters are set: </p>

<p><strong>Note:</strong> Execute the following on the broker host. </p>

<pre><code>DISTRICTS_ENABLED=true  
NODE_PROFILE_ENABLED=true  
</code></pre>

<h2 id="creatingandpopulatingdistricts"><strong>Creating and populating districts</strong></h2>

<p>To create a district that will support a gear type of small, we will use the <em>oo-admin-ctl-district</em> command. After defining the district, we can add our node host (node.example.com) as the only node in that district. Execute the following commands to create a district named small_district which can only hold <em>small</em> gear types: </p>

<p><strong>Note: Execute the following on the broker host.</strong></p>

<pre><code># oo-admin-ctl-district -c create -n small_district -p small  
</code></pre>

<p>If the command was successful, you should see output similar to the following: </p>

<pre><code>Successfully created district: 513b50508f9f44aeb90090f19d2fd940  

{&quot;name&quot;=&gt;&quot;small_district&quot;,  
 &quot;externally_reserved_uids_size&quot;=&gt;0,  
 &quot;active_server_identities_size&quot;=&gt;0,  
 &quot;node_profile&quot;=&gt;&quot;small&quot;,  
 &quot;max_uid&quot;=&gt;6999,  
 &quot;creation_time&quot;=&gt;&quot;2013-01-15T17:18:28-05:00&quot;,  
 &quot;max_capacity&quot;=&gt;6000,  
 &quot;server_identities&quot;=&gt;{},  
 &quot;uuid&quot;=&gt;&quot;513b50508f9f44aeb90090f19d2fd940&quot;,  
 &quot;available_uids&quot;=&gt;&quot;&lt;6000 uids hidden&gt;&quot;,  
 &quot;available_capacity&quot;=&gt;6000}  
</code></pre>

<p>If you are familiar with JSON, you will understand the format of this output. What actually happened is a new document was created in the MongoDB database that we installed in a previous lab. To view this document inside of the database, execute the following:</p>

<pre><code># mongo  
</code></pre>

<p>This will drop you into the mongo shell where you can perform commands against the database. The first thing we need to do is let MongoDB know which database we want to use:</p>

<pre><code>&gt; show dbs
&gt; use openshift_broker_dev  
</code></pre>

<p>To list all of the available collections in the <em>openshift_broker_dev</em> database, you can issue the following command:</p>

<pre><code>&gt; db.getCollectionNames()  
</code></pre>

<p>You should see the following collections returned:</p>

<pre><code>[ &quot;district&quot;, &quot;system.indexes&quot;, &quot;system.users&quot;, &quot;user&quot; ]  
</code></pre>

<p>We can now query the <em>district</em> collection to verify the creation of our small district:</p>

<pre><code>&gt; db.district.find()  
</code></pre>

<p>The output should be:</p>

<pre><code>{ &quot;_id&quot; : &quot;513b50508f9f44aeb90090f19d2fd940&quot;, &quot;name&quot; : &quot;small_district&quot;, &quot;externally_reserved_uids_size&quot; : 0,   
&quot;active_server_identities_size&quot; : 0, &quot;node_profile&quot; : &quot;small&quot;, &quot;max_uid&quot; : 6999, &quot;creation_time&quot; :   
&quot;2013-01-15T17:18:28-05:00&quot;, &quot;max_capacity&quot; : 6000, &quot;server_identities&quot; : [ ], &quot;uuid&quot; :   
&quot;513b50508f9f44aeb90090f19d2fd940&quot;, &quot;available_uids&quot; : [    1000, .........], , &quot;available_capacity&quot; : 6000 }  
</code></pre>

<p><strong>Note:</strong> The <em>server_identities</em> array does not contain any data yet. </p>

<p>Now we can add our node host, node.example.com, to the <em>small_district</em> that we created above:</p>

<pre><code># oo-admin-ctl-district -c add-node -n small_district -i node.example.com  
</code></pre>

<p>You should see the following output: </p>

<pre><code>Success!  

{&quot;available_capacity&quot;=&gt;6000,  
 &quot;creation_time&quot;=&gt;&quot;2013-01-15T17:18:28-05:00&quot;,  
 &quot;available_uids&quot;=&gt;&quot;&lt;6000 uids hidden&gt;&quot;,  
 &quot;node_profile&quot;=&gt;&quot;small&quot;,  
 &quot;uuid&quot;=&gt;&quot;513b50508f9f44aeb90090f19d2fd940&quot;,  
 &quot;externally_reserved_uids_size&quot;=&gt;0,  
 &quot;server_identities&quot;=&gt;{&quot;node.example.com&quot;=&gt;{&quot;active&quot;=&gt;true}},  
 &quot;name&quot;=&gt;&quot;small_district&quot;,  
 &quot;max_capacity&quot;=&gt;6000,  
 &quot;max_uid&quot;=&gt;6999,  
 &quot;active_server_identities_size&quot;=&gt;1}  
</code></pre>

<p><strong>Note:</strong> If you see an error message indicating that you can’t add this node to the district because the node already has applications on it, consult the troubleshooting section. </p>

<p>Repeat the steps above to query the database for information about districts. Notice that the <em>server_identities</em> array now contains the following information: </p>

<pre><code>&quot;server_identities&quot; : [ { &quot;name&quot; : &quot;node.example.com&quot;, &quot;active&quot; : true } ]  
</code></pre>

<p>If you continued to add additional nodes to this district, the <em>server_identities</em> array would show all the node hosts that are assigned to the district. </p>

<p>OpenShift Enterprise also provides a command line tool to display information about a district. Simple enter the following command to view the JSON information that is stored in the MongoDB database:</p>

<pre><code># oo-admin-ctl-district  
</code></pre>

<h2 id="managingdistrictcapacity"><strong>Managing district capacity</strong></h2>

<p>Districts and node hosts have a configured capacity for the number of gears allowed. For a node host, the default values configured in <em>/etc/openshift/resource_limits.conf</em> are: </p>

<ul>
<li>Maximum number of application per node : 100</li>
<li>Maximum number of active applications per node : 100</li>
</ul>

<p><strong>Lab 19 Complete!</strong> </p>

<!--BREAK-->

<h1 id="lab20:installingtherhcclienttoolsestimatedtime:15minutes"><strong>Lab 20: Installing the RHC client tools (Estimated time: 15 minutes)</strong></h1>

<p><strong>Server used:</strong></p>

<ul>
<li>localhost</li>
</ul>

<p><strong>Tools used:</strong></p>

<ul>
<li>ruby</li>
<li>sudo</li>
<li>git</li>
<li>yum</li>
<li>gem</li>
<li>rhc</li>
</ul>

<p>The OpenShift Client tools, known as <strong>rhc</strong>, are built and packaged using the Ruby programming language. OpenShift Enterprise integrates with the Git version control system to provide powerful, decentralized version control for your application source code. </p>

<p>OpenShift Enterprise client tools can be installed on any operating system with Ruby 1.8.7 or higher. Instructions for specific operating systems are provided below. It is assumed that you are running the commands from a command line window, such as Command Prompt, or Terminal. If you are using Ruby Version Manager (rvm) see the instructions below. </p>

<h2 id="microsoftwindows"><strong>Microsoft Windows</strong></h2>

<h3 id="installingrubyforwindows"><strong>Installing Ruby for Windows</strong></h3>

<p><a href="http://rubyinstaller.org/">RubyInstaller 1.9</a> provides the best experience for installing Ruby on Windows XP, Vista, and Windows 7. Download the newest version from the <a href="http://rubyinstaller.org/downloads/">download page</a> and launch the installer. </p>

<p><strong>Important</strong>: During the installation you should accept all of the defaults, it is mandatory that you select the &#8220;Add Ruby executables to your PATH&#8221; check box in order to run Ruby from the command line. </p>

<p>After the installation is complete, to verify that the installation is working run:</p>

<pre><code>C:\Program Files\&gt; ruby -e 'puts &quot;Welcome to Ruby&quot;'  
Welcome to Ruby  
</code></pre>

<p>If the &#8216;Welcome to Ruby&#8217; message does not display, the Ruby executable may not have been added to the path. Restart the installation process and ensure the &#8220;Add Ruby executables to your PATH&#8221; check box is selected. </p>

<h3 id="installinggitforwindows"><strong>Installing Git for Windows</strong></h3>

<p>The next step is to install <a href="http://msysgit.github.com/">Git for Windows</a> so that you can synchronize your local application source and your OpenShift application. Git for Windows offers the easiest Git experience on the Windows operating system and is the recommended default - if you use another version of Git please ensure it can be executed from the command line and continue to the next section. </p>

<p>Download and install the <a href="http://code.google.com/p/msysgit/downloads/list?q=full+installer+official+git">latest version of Git for Windows</a>. Ensure that Git is added to your PATH so that it can be run from the command line. After the installation has completed, verify that Git is correctly configured by runing:</p>

<pre><code>C:\Program Files\&gt; git --version  
git version 1.7.11.msysgit.1  
</code></pre>

<h3 id="installingrhcforwindows"><strong>Installing RHC for Windows</strong></h3>

<p>After Ruby and Git are correctly installed, use the RubyGems package manager (included in Ruby) to install the OpenShift Enterprise client tools. Run:</p>

<pre><code>C:\Program Files\&gt; gem install rhc  
</code></pre>

<p>RubyGems downloads and installs the rhc gem from www.rubygems.org/gems/rhc. The installation typically proceeds without errors. After the installation has completed, run:</p>

<pre><code>C:\Program Files\&gt; rhc  
</code></pre>

<h2 id="macosx"><strong>Mac OS X</strong></h2>

<h3 id="installingrubyforosx"><strong>Installing Ruby for OS X</strong></h3>

<p>From OS X Lion onwards, Ruby 1.8.7 is installed by default. On older Mac systems, Ruby is shipped as part of the <a href="https://developer.apple.com/xcode/">Xcode development suite</a> and can be installed from your installation CD. If you are familiar with Mac development, you can also use <a href="http://macruby.org/">MacRuby</a> or see the Ruby installation page for <a href="http://www.ruby-lang.org/en/downloads/">help installing with homebrew</a>. </p>

<p>To verify that Ruby is correctly installed run:</p>

<pre><code>$ ruby -e 'puts &quot;Welcome to Ruby&quot;'  
Welcome to Ruby  
</code></pre>

<h3 id="installinggitforosx"><strong>Installing Git for OS X</strong></h3>

<p>There are a number of options on Mac OS X for Git. We recommend the Git for OS X installer - download and run the latest version of the dmg file on your system. To verify the <a href="http://code.google.com/p/git-osx-installer/">Git for OS X installation</a>, run:</p>

<pre><code>$ git --version  
git version 1.7.11.1  
</code></pre>

<h3 id="installingrhcforosx"><strong>Installing RHC for OS X</strong></h3>

<p>With Ruby and Git installed, use the RubyGems library system to install and run the OpenShift Enterprise gem. Run:</p>

<pre><code>$ sudo gem install rhc  
</code></pre>

<p>After the installation has completed, run:</p>

<pre><code>$ rhc -v  
</code></pre>

<h2 id="fedora16and17"><strong>Fedora 16 and 17</strong></h2>

<p>To install from yum on Fedora 16 and 17, run:</p>

<pre><code>$ sudo yum install rubygem-rhc  
</code></pre>

<p>This installs Ruby, Git, and the other dependencies required to run the OpenShift Enterprise client tools. </p>

<p>After the OpenShift Enterprise client tools have been installed, run:</p>

<pre><code>$ rhc -v  
</code></pre>

<h2 id="redhatenterpriselinux6.2and6.3"><strong>Red Hat Enterprise Linux 6.2 and 6.3</strong></h2>

<p>The most recent version of the OpenShift Enterprise client tools are available as a RPM from the OpenShift Enterprise hosted YUM repository. We recommend this version to remain up to date, although a version of the OpenShift Enterprise client tools RPM is also available through EPEL. </p>

<p>To add the OpenShift Enterprise YUM repository, download the repository file openshift.repo and move it to your <strong>/etc/yum.repos.d/</strong> directory.</p>

<pre><code>$ sudo mv ~/openshift.repo /etc/yum.repos.d/  
</code></pre>

<p>In order to install the rubygems package, the <em>RHEL Optional</em> channel must be enabled. There are two ways of doing this from the command line. If you are using the Certificate-Based RHN tooling, enter the following command:</p>

<pre><code>$ sudo yum-config-manager --enable rhel-6-server-optional-rpms     
</code></pre>

<p>If you are using RHN-Classic, enter the following command:</p>

<pre><code>$ sudo rhn-channel --add -- channel=rhel-x86rhel-x86_64-server-optional-6  
</code></pre>

<p>With the repository in place, you can now install the OpenShift Enterprise client tools by running the following command:</p>

<pre><code>$ sudo yum install rhc  
</code></pre>

<h2 id="ubuntu"><strong>Ubuntu</strong></h2>

<p>Use the apt-get command line package manager to install Ruby and Git before you install the OpenShift Enterprise command line tools. Run:</p>

<pre><code>$ sudo apt-get install ruby-full rubygems git-core  
</code></pre>

<p>After you install both Ruby and Git, verify they can be accessed via the command line:</p>

<pre><code>$ ruby -e 'puts &quot;Welcome to Ruby&quot;'
$ git --version  
</code></pre>

<p>If either program is not available from the command line, please add them to your PATH environment variable. </p>

<p>With Ruby and Git correctly installed, you can now use the RubyGems package manager to install the OpenShift Enterprise client tools. From a command line, run:</p>

<pre><code>$ sudo gem install rhc  
</code></pre>

<p><strong>Lab 20 Complete!</strong> </p>

<!--BREAK-->

<h1 id="lab21:usingrhcsetupestimatedtime:10minutes"><strong>Lab 21: Using <em>rhc setup</em> (Estimated time: 10 minutes)</strong></h1>

<p><strong>Server used:</strong></p>

<ul>
<li>localhost</li>
</ul>

<p><strong>Tools used:</strong></p>

<ul>
<li>rhc</li>
</ul>

<h2 id="configuringrhcsetup"><strong>Configuring RHC setup</strong></h2>

<p>By default, the RHC command line tool will default to use the publicly hosted OpenShift environment. Since we are using our own enterprise environment, we need to tell <em>rhc</em> to use our broker.example.com server instead of openshift.com. In order to accomplish this, the first thing we need to do is set our <em>LIBRA_SERVER</em> variable to point to our broker host and then run the <em>rhc setup</em> command:</p>

<pre><code>$ LIBRA_SERVER=broker.example.com rhc setup  
</code></pre>

<p>Once you enter in that command, you will be prompted for the username that you would like to authenticate with. For this training class, use the <em>demo</em> user account that we created in a previous lab. After providing the username that you would like to connect with, you will be prompted for the password of the user account. </p>

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

<p>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 this lab, create the following namespace: </p>

<pre><code>ose  
</code></pre>

<h2 id="underthecovers"><strong>Under the covers</strong></h2>

<p>The <em>rhc setup</em> tool is a convenient command line utility to ensure that the users operating system is configured properly to create and manage applications from the command line. After this command has been executed, a <em>.openshift</em> directory was created in the users home directory with some basic configuration items specified in the <em>express.conf</em> file. The contents of that file are as follows:</p>

<pre><code># Default user login  
default_rhlogin=‘demo’

# Server API  
libra_server = 'broker.example.com'  
</code></pre>

<p>This information will be provided to the <em>rhc</em> 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 <em>-l</em> switch to the <em>rhc</em> command. </p>

<p><strong>Lab 21 Complete!</strong> </p>

<!--BREAK-->

<h1 id="lab22:creatingaphpapplicationestimatedtime:30minutes"><strong>Lab 22: Creating a PHP application (Estimated time: 30 minutes)</strong></h1>

<p><strong>Server used:</strong></p>

<ul>
<li>localhost</li>
<li>node host</li>
</ul>

<p><strong>Tools used:</strong></p>

<ul>
<li>rhc</li>
</ul>

<p>In this lab, we are ready to start using OpenShift Enterprise to create our first application. To create an application, we will be using the <em>rhc app</em> command. In order to view all of the swtich available for the <em>rhc app</em> command, enter the following command:</p>

<pre><code>$ rhc app -h  
</code></pre>

<p>This will provide you with the following output: </p>

<pre><code>List of Actions  
create             Create an application and adds it to a domain  
git-clone          Clone and configure an application's repository locally  
delete             Delete an application from the server  
start              Start the application  
stop               Stop the application  
force-stop         Stops all application processes  
restart            Restart the application  
reload             Reload the application's configuration  
tidy               Clean out the application's logs and tmp directories and tidy up the git repo on the server  
show               Show information about an application  
status             Show status of an application's gears  

Global Options  
-l, --rhlogin login       OpenShift login  
-p, --password password   OpenShift password  
-d, --debug               Turn on debugging  
--timeout seconds         Set the timeout in seconds for network commands  
--noprompt                Suppress the interactive setup wizard from running before a command  
--config FILE             Path of a different config file  
-h, --help                Display help documentation  
-v, --version             Display version information  
</code></pre>

<h2 id="createanewapplication"><strong>Create a new application</strong></h2>

<p>It is very easy to create an OpenShift Enterprise application using <em>rhc</em>. The command to create an application is <em>rhc app create</em> and it requires two mandatory arguments:</p>

<ul>
<li><p><strong>Application Name (-a or &#8211;app)</strong> : The name of the application. The application name can only contain alpha-numeric characters and at max contain only 32 characters.</p></li>
<li><p><strong>Type (-t or &#8211;type)</strong>: The type is used to specify which language runtime to use. </p></li>
</ul>

<p>Create a directory to hold your OpenShift Enterprise code projects:</p>

<pre><code>$ cd ~
$ mkdir ose
$ cd ose  
</code></pre>

<p>To create an application that uses the <em>php</em> runtime, issue the following command:</p>

<pre><code>$ rhc app create -a firstphp -t php  
</code></pre>

<p>After entering that command, you should see the following output: </p>

<pre><code>Password: ****  

Creating application 'firstphp'  
===============================

  Namespace: ose  
  Scaling:   no  
  Cartridge: php  
  Gear Size: default  

Your application's domain name is being propagated worldwide (this might take a minute)...  
The authenticity of host 'firstphp-ose.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 'firstphp'...  
done  

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

RESULT:  
Application firstphp was created.
</code></pre>

<p>If you completed all of the steps in lab 16 correctly, you should be able to verify that your application was created correctly by opening up a web browser and entering the following URL: </p>

<pre><code>http://firstphp-ose.example.com  
</code></pre>

<p>You should see the default template that OpenShift Enterprise uses for a new application. </p>

<figure>
<img src="http://training.runcloudrun.com/images/firstphp.png" alt="" /></figure>


<h2 id="whatjusthappened"><strong>What just happened?</strong></h2>

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

<ul>
<li>A request was made to the broker application host to create a new php application</li>
<li>A message was dropped using MCollective and ActiveMQ to find a node host to handle the application creation request</li>
<li>A node host responded to the request and created an application / gear for you</li>
<li>All SELinux and cgroup policies were enabled for your application gear</li>
<li>A userid was created for your application gear</li>
<li>A private git repository was created for your gear on the node host</li>
<li>The git repository was cloned on your local machine</li>
<li>BIND was updated on the broker host to include an entry for your application</li>
</ul>

<h2 id="understandingthedirectorystructureonthenodehost"><strong>Understanding the directory structure on the node host</strong></h2>

<p>It is important to understand the directory structure of each OpenShift Enterprise 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:</p>

<pre><code># cd /var/lib/openshift
# ls  
</code></pre>

<p>You will see output similar to the following: </p>

<pre><code>e9e92282a16b49e7b78d69822ac53e1d  
</code></pre>

<p>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:</p>

<pre><code># cd e9e92282a16b49e7b78d69822ac53e1d
# ls -al  
</code></pre>

<p>You should see the following directories: </p>

<pre><code>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]#   
</code></pre>

<p>During a previous lab, where we setup the <em>rhc</em> tools, 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 <em>authorized_key</em> file. To verify this, use the following command to view the contents of the file:</p>

<pre><code># cat .ssh/authorized_keys  
</code></pre>

<p>You will also notice the following three directories:</p>

<ul>
<li>app-root - Contains your core application code as well as your data directory where persistent data is stored.</li>
<li>git - Your private git repository that was created upon gear creation.</li>
<li>php&#8211;5.3 - The core PHP runtime and associated configuration files. Your application is served from this directory.</li>
</ul>

<h2 id="understandingdirectorystructureonthelocalhost"><strong>Understanding directory structure on the localhost</strong></h2>

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

<pre><code>$ cd firstphp
$ ls -al  
</code></pre>

<p>You should see the following information: </p>

<pre><code>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  
</code></pre>

<h3 id="gitdirectory"><strong>.git directory</strong></h3>

<p>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:</p>

<pre><code>$ cat .git/config  
</code></pre>

<p>You should see the following information which specifies the URL for our repository that is hosted on the OpenShift Enterprise node host: </p>

<pre><code>[core]  
    repositoryformatversion = 0  
    filemode = true  
    bare = false  
    logallrefupdates = true  
    ignorecase = true  
[remote &quot;origin&quot;]  
    fetch = +refs/heads/*:refs/remotes/origin/*  
    url = ssh://e9e92282a16b49e7b78d69822ac53e1d@firstphp-ose.example.com/~/git/firstphp.git/  
[branch &quot;master&quot;]  
    remote = origin  
    merge = refs/heads/master  
[rhc]  
    app-uuid = e9e92282a16b49e7b78d69822ac53e1d  
</code></pre>

<p><strong>Note:</strong> 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. </p>

<h3 id="openshiftdirectory"><strong>.openshift directory</strong></h3>

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

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

<table>
<caption id="section-mmd-tables-table1">Action Hooks</caption>
<colgroup>
<col style="text-align:left;"/>
<col style="text-align:left;"/>
</colgroup>

<thead>
<tr>
	<th style="text-align:left;">Action Hook</th>
	<th style="text-align:left;">Description</th>
</tr>
</thead>

<tbody>
<tr>
	<td style="text-align:left;">build</td>
	<td style="text-align:left;">Executed on your CI system if available. Otherwise, executed before the deploy step</td>
</tr>
<tr>
	<td style="text-align:left;">deploy</td>
	<td style="text-align:left;">Executed after dependencies are resolved but before application has started</td>
</tr>
<tr>
	<td style="text-align:left;">post_deploy</td>
	<td style="text-align:left;">Executed after application has been deployed and started</td>
</tr>
<tr>
	<td style="text-align:left;">pre_build</td>
	<td style="text-align:left;">Executed on your CI system if available. Otherwise, executed before the build step</td>
</tr>
</tbody>
</table>
<p>OpenShift Enterprise also supports the ability for a user to schedule jobs to executed 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:</p>

<ul>
<li>daily</li>
<li>hourly</li>
<li>minutely</li>
<li>monthly</li>
<li>weekly</li>
</ul>

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

<h3 id="libsdirectory"><strong>libs directory</strong></h3>

<p>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 Enterprise uses is providing <em>PEAR</em> modules in the deptlist.txt file. </p>

<h3 id="miscdirectory"><strong>misc directory</strong></h3>

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

<h3 id="phpdirectory"><strong>php directory</strong></h3>

<p>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:</p>

<ul>
<li>health_check.php - A simple file to determine if the application is responding to requests</li>
<li>index.php - The OpenShift template that we saw after application creation in the web browser.</li>
</ul>

<h2 id="makeachangetothephpapplicationanddeployupdatedcode"><strong>Make a change to the PHP application and deploy updated code</strong></h2>

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

<pre><code>&lt;h1&gt;
    Welcome to OpenShift  
&lt;/h1&gt;  
</code></pre>

<p>Update this code block to the following and then save your changes: </p>

<pre><code>&lt;h1&gt;
    Welcome to OpenShift Enterprise  
&lt;/h1&gt;  
</code></pre>

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

<pre><code>$ git commit -am “Changed welcome message.”  
</code></pre>

<p>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. </p>

<pre><code>$ git push  
</code></pre>

<p>You should see the following output: </p>

<pre><code>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-ose.example.com/~/git/firstphp.git/
   3edf63b..edc0805  master -&gt; master  
</code></pre>

<p>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. </p>

<h2 id="verifycodechange"><strong>Verify code change</strong></h2>

<p>If you completed all of the steps in lab 16 correctly, you should be able to verify that your application was deployed correctly by opening up a web browser and entering the following URL: </p>

<pre><code>http://firstphp-ose.example.com  
</code></pre>

<p>You should see the updated code for the application. </p>

<figure>
<img src="http://training.runcloudrun.com/images/firstphpOSE.png" alt="" /></figure>


<h2 id="addinganewphpfile"><strong>Adding a new PHP file</strong></h2>

<p>Adding a new source code file to your OpenShift Enterprise 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 <em>php</em> directory and name it <em>time.php</em>. After creating this file, add the following contents: </p>

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

<p>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 Enterprise gear:</p>

<pre><code>$ git add .
$ git commit -am “Adding time.php”
$ git push  
</code></pre>

<h2 id="verifycodechange"><strong>Verify code change</strong></h2>

<p>To verify that we have created and deployed the new PHP source file correctly, open up a web browser and enter the following URL: </p>

<pre><code>http://firstphp-ose.example.com/time.php  
</code></pre>

<p>You should see the updated code for the application. </p>

<figure>
<img src="http://training.runcloudrun.com/images/firstphpTime.png" alt="" /></figure>


<h2 id="enablehot_deploy"><strong>Enable <em>hot_deploy</em></strong></h2>

<p>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 Enterprise 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/ose/firstphp and issue the following commands:</p>

<pre><code>$ touch .openshift/markers/hot_deploy
$ git add .
$ git commit -am “Adding hot_deploy marker”
$ git push  
</code></pre>

<p>Pay attention to the output: </p>

<pre><code>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-ose.example.com/~/git/firstphp.git/
   4fbda99..fdbd056  master -&gt; master  
</code></pre>

<p>The two lines of importance are: </p>

<pre><code>remote: Will add new hot deploy marker  
remote: App will not be stopped due to presence of hot_deploy marker  
</code></pre>

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

<p><strong>Lab 22 Complete!</strong><br/>
<!--BREAK--> </p>

<h1 id="lab23:managinganapplicationestimatedtime:30minutes"><strong>Lab 23: Managing an application (Estimated time: 30 minutes)</strong></h1>

<p><strong>Server used:</strong></p>

<ul>
<li>localhost</li>
<li>node host</li>
</ul>

<p><strong>Tools used:</strong></p>

<ul>
<li>rhc</li>
</ul>

<h2 id="startstoprestartopenshiftenterpriseapplication"><strong>Start/Stop/Restart OpenShift Enterprise application</strong></h2>

<p>OpenShift Enterprise 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 <em>rhc app stop</em> command. After making necessary maintenance tasks you can start the application again using the <em>rhc app start</em> command. </p>

<p>To stop an application execute the following command:</p>

<pre><code>$ rhc app stop -a firstphp  

RESULT:  
firstphp stopped  
</code></pre>

<p>Verify that your application has been stopped with the following <em>curl</em> command:</p>

<pre><code>$ curl http://firstphp-ose.example.com/health  

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

<p>To start the application back up, execute the following command:</p>

<pre><code>$ rhc app start -a firstphp  

RESULT:  
firstphp started  
</code></pre>

<p>Verify that your application has been started with the following <em>curl</em> command:</p>

<pre><code>$ curl http://firstphp-ose.example.com/health

1  
</code></pre>

<p>You can also stop and start the application in one command as shown below.</p>

<pre><code>$ rhc app restart -a firstphp  

RESULT:  
firstphp restarted  
</code></pre>

<h2 id="viewingapplicationdetails"><strong>Viewing application details</strong></h2>

<p>All of the details about an application can be viewed by the <em>rhc app show</em> 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:</p>

<pre><code>$ rhc app show -a firstphp  
Password: ****


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

<h2 id="viewingapplicationstatus"><strong>Viewing application status</strong></h2>

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

<pre><code>rhc app show --state -a firstphp  
Password: ****


RESULT:  
Geargroup php-5.3 is started  
</code></pre>

<h2 id="cleaningupanapplication"><strong>Cleaning up an application</strong></h2>

<p>As users start developing an application and deploying changes to OpenShift Enterprise, 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 Enterprise provides a disk space cleanup tool to help users manage the application disk space. This command is also available under <em>rhc app</em> and performs the following functions:</p>

<ul>
<li>Runs the <em>git gc</em> command on the application&#8217;s remote git repository</li>
<li>Clears the application&#8217;s /tmp and log file directories. These are specified by the application&#8217;s <em>OPENSHIFT_LOG_DIR</em>* and <em>OPENSHIFT_TMP_DIR</em> environment variables.</li>
<li>Clears unused application libraries. This means that any library files previously installed by a <em>git push</em> command are removed.</li>
</ul>

<p>To clean up the disk space on your application gear, run the following command:</p>

<pre><code>$ rhc app tidy -a firstphp  
</code></pre>

<h2 id="sshtoapplicationgear"><strong>SSH to application gear</strong></h2>

<p>OpenShift allows remote access to the application gear by using the Secure Shell protocol (SSH). <a href="http://en.wikipedia.org/wiki/Secure_Shell">Secure Shell (SSH)</a> 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 Enterprise uses SSH for :</p>

<ul>
<li>Performing Git operations</li>
<li>Remote access your application gear</li>
</ul>

<p>The SSH keys were generated and uploaded to OpenShift Enterprise by rhc setup command we executed in a previous lab. You can verify that SSH keys are uploaded by logging into the OpenShift Enterprise web console and clicking on the &#8220;My Account&#8221; tab as shown below. </p>

<figure>
<img src="http://training.runcloudrun.com/images/sshkeys.png" alt="" /></figure>


<p><strong>Note:</strong> If you don&#8217;t see an entry under &#8220;Public Keys&#8221; then you can either upload the SSH keys by clicking on &#8220;Add a new key&#8221; or run the <em>rhc setup</em> command again. This will create a SSH key pair in &lt;User.Home&gt;/.ssh folder and upload the public key to the OpenShift Enterprise server. </p>

<p>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 <a href="http://www.chiark.greenend.org.uk/~sgtatham/putty/">Putty</a>. Instructions for installing Putty can be found <a href="https://openshift.redhat.com/community/page/install-and-setup-putty-ssh-client-for-windows">on the OpenShift website</a>. </p>

<pre><code>$ ssh UUID@appname-namespace.example.com  
</code></pre>

<p>You can get the SSH URL by running <em>rhc app show</em> command as shown below:</p>

<pre><code>$ rhc app show -a firstphp  
Password: ****


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

<p>Now you can ssh into the application gear using the SSH URL shown above:</p>

<pre><code>$ ssh e9e92282a16b49e7b78d69822ac53e1d@firstphp-ose.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, destroy your application with 'rhc app destroy'
    and recreate it
    !!! IMPORTANT !!! IMPORTANT !!! IMPORTANT !!!

    Type &quot;help&quot; for more info.
</code></pre>

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

<pre><code>[firstphp-ose.example.com ~]\&gt; 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  
</code></pre>

<h2 id="viewinglogfilesforanapplication"><strong>Viewing log files for an application</strong></h2>

<p>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 Enterprise provides the <em>rhc tail</em> command to display the contents of your log files. To view all the options available for the <em>rhc tail</em> command, issue the following:</p>

<pre><code>$ rhc tail -h  
Usage: rhc tail &lt;application&gt;  

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 &lt;application_name&gt;/logs/*) (optional)  
  -a, --app app             Name of application you wish to view the logs of  
</code></pre>

<p>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 <em>firstphp</em> application, use the following command:</p>

<pre><code>$ rhc tail -a firstphp  
</code></pre>

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

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

<p>The log files are also available on the gear node host in the <em>php&#8211;5.3/logs</em> directory. </p>

<h2 id="viewingdiskquotaforanapplication"><strong>Viewing disk quota for an application</strong></h2>

<p>In a previous lab, we configured the application gears to have a disk usage quota. You can view the quota of your currently running gear by connecting to the gear node host via SSH as discussed previously in this lab. Once you are connected to your application gear, enter the following command:</p>

<pre><code>$ quota -s  
</code></pre>

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

<pre><code>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   40000          
</code></pre>

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

<pre><code>$ du -u   
</code></pre>

<h2 id="addingacustomdomaintoanapplication"><strong>Adding a custom domain to an application</strong></h2>

<p>OpenShift Enterprise 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 <em>firstphp</em> we created in a previous lab. The first thing you need to do before setting up a custom domain name is to buy the domain name from domain registration provider. </p>

<p>After buying the domain name, you have to add a <a href="http://en.wikipedia.org/wiki/CNAME_record">CName record</a> for the custom domain name. Once you have created the CName record, you can let OpenShift Enterprise know about the CName by using the <em>rhc alias</em> command.</p>

<pre><code>$ rhc alias add firstphp www.mycustomdomainname.com  
</code></pre>

<p>Technically, what OpenShift Enterprise has done under the hood is set up a Vhost in Apache to handle the custom URL. </p>

<h2 id="backingupanapplication"><strong>Backing up an application</strong></h2>

<p>Use the <em>rhc snapshot save</em> command to create backups of your OpenShift Enterprise 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.</p>

<pre><code>$ 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  
</code></pre>

<p>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 &#8211;filepath option. </p>

<p><strong>NOTE</strong>: This command will stop your application for the duration of the backup process. </p>

<h2 id="deletinganapplication"><strong>Deleting an application</strong></h2>

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

<pre><code>$ 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  
</code></pre>

<p>There is another variant of this command which does not require the user to confirm the delete opeartion. To use this variant, pass the <em>&#8211;confirm</em> flag.</p>

<pre><code>$ rhc app delete --confirm -a someAppToDelete  

Deleting application 'someAppToDelete'  

RESULT:  
Application 'someAppToDelete' successfully deleted  
</code></pre>

<h2 id="restoringabackup"><strong>Restoring a backup</strong></h2>

<p>Not only you can take a backup of an application but you can also restore a previously saved snapshot. This form of the <em>rhc</em>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 Enterprise runs the deployment script on the newly restored repository. To restore an application snapshot, run the following command:</p>

<pre><code>$ rhc snapshot restore -a firstphp -f firstphp.tar.gz  
</code></pre>

<p><strong>NOTE</strong>: This command will stop your application for the duration of the restore process. </p>

<h2 id="verifyapplicationhasbeenrestored"><strong>Verify application has been restored</strong></h2>

<p>Open up a web browser and point to the following URL: </p>

<pre><code>http://firstphp-ose.example.com  
</code></pre>

<p>If the restore process worked correctly, you should see the restored application running just as it was before the delete operation that you performed earlier in this lab. </p>

<h2 id="viewingathreaddumpofanapplication"><strong>Viewing a thread dump of an application</strong></h2>

<p><strong>Note:</strong> The following sections requires a Ruby or JBoss application type. Since we have not created one yet in this class, read through the material below but don’t actually perform the commands at this time. </p>

<p>You can trigger a thread dump for Ruby and JBoss applications using the <em>rhc threaddump</em> 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:</p>

<pre><code>$ rhc threaddump -a ApplicationName  
</code></pre>

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

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

<p><strong>Lab 23 Complete!</strong><br/>
<!--BREAK--> </p>

<h1 id="lab24:usingcartridgesestimatedtime:30minutes"><strong>Lab 24: Using cartridges (Estimated time: 30 minutes)</strong></h1>

<p><strong>Server used:</strong></p>

<ul>
<li>localhost</li>
<li>node host</li>
</ul>

<p><strong>Tools used:</strong></p>

<ul>
<li>rhc</li>
<li>mysql</li>
<li>tail</li>
<li>git</li>
<li>PHP</li>
</ul>

<p>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 Enterprise. Please refer to the official OpenShift Enterprise documentation for how you can <a href="https://openshift.redhat.com/community/wiki/introduction-to-cartridge-building">write your own cartridge</a>. </p>

<h2 id="viewingavailablecartridges"><strong>Viewing available cartridges</strong></h2>

<p>To view all of the available commands for working with cartridges on OpenShift Enterprise, enter the following command:</p>

<pre><code>$ rhc cartridge -h  
</code></pre>

<h2 id="listavailablecartridges"><strong>List available cartridges</strong></h2>

<p>To see a list of all available cartridges to users of this OpenShift Enterprise deployment, issue the following command:</p>

<pre><code>$ rhc cartridge list  
</code></pre>

<p>You should see the following output: </p>

<pre><code>RESULT:  
cron-1.4, mysql-5.1, haproxy-1.4, postgresql-8.4  
</code></pre>

<h2 id="addthemysqlcartridge"><strong>Add the MySQL cartridge</strong></h2>

<p>In order to use a cartridge, we need to embed it into our existing application. OpenShift Enterprise provides support for version 5.1 of this popular open source database. To enable MySQL support for the <em>firstphp</em> application, issue the following command:</p>

<pre><code>$ rhc cartridge add mysql -a firstphp  
</code></pre>

<p>You should see the following output: </p>

<pre><code>Password: *********  

Adding 'mysql-5.1' to application 'firstphp'  
Success  
mysql-5.1  
=========  
  Properties  
  ==========
    Username       = admin
    Password       = aFh_GsHP63fV
    Connection URL = mysql://127.1.244.1:3306/
    Database Name  = firstphp  
</code></pre>

<h2 id="usingmysql"><strong>Using MySQL</strong></h2>

<p>Developers will typically interact with MySQL by using the mysql shell command on OpenShift Enterprise. In order to use the mysql shell, use the information you gained in a previous lab in order to SSH to your application gear. Once you have been authenticated, issue the following command: </p>

<pre><code>[firstphp-ose.example.com ~]\&gt; mysql  
</code></pre>

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

<p>When embedding the MySQL database, OpenShift Enterprise 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 <em>users</em> table: </p>

<pre><code>mysql&gt; use firstphp;  
Database changed  

mysql&gt; 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&gt; insert into users values (null, 'gshipley@redhat.com');  
Query OK, 1 row affected (0.00 sec)  
</code></pre>

<p>Verify that the user record has been added by selecting all rows from the <em>users</em> table: </p>

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

<p>To exit out of the MySQL session, simple enter the <em>exit</em> command: </p>

<pre><code>mysql&gt; exit  
</code></pre>

<h2 id="mysqlenvironmentvariables"><strong>MySQL environment variables</strong></h2>

<p>As mentioned earlier in this lab, OpenShift Enterprise 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: </p>

<p><strong>Note:</strong> Execute the following on the node host. </p>

<pre><code>[firstphp-ose.example.com ~]\&gt; env |grep MYSQL  
</code></pre>

<p>You should see the following information return from the command: </p>

<pre><code>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  
</code></pre>

<p>To view a list of all <em>OPENSHIFT</em> environment variables, you can use the following command: </p>

<pre><code>[firstphp-ose.example.com ~]\&gt; env | grep OPENSHIFT  
</code></pre>

<h2 id="viewingmysqllogs"><strong>Viewing MySQL logs</strong></h2>

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

<pre><code>[firstphp-ose.example.com ~]\&gt; tail -f $OPENSHIFT_MYSQL_DB_LOG_DIR/*  
</code></pre>

<h2 id="connectingtothemysqlcartridgefromphp"><strong>Connecting to the MySQL cartridge from PHP</strong></h2>

<p>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 <em>php</em> directory of your <em>firstphp</em> application named <em>dbtest.php</em>. Add the following source code to the <em>dbtest.php</em> file: </p>

<pre><code>&lt;?php  
$dbhost = getenv(&quot;OPENSHIFT_MYSQL_DB_HOST&quot;);  
$dbport = getenv(&quot;OPENSHIFT_MYSQL_DB_PORT&quot;);  
$dbuser = getenv(&quot;OPENSHIFT_MYSQL_DB_USERNAME&quot;);  
$dbpwd = getenv(&quot;OPENSHIFT_MYSQL_DB_PASSWORD&quot;);  
$dbname = getenv(&quot;OPENSHIFT_APP_NAME&quot;);  

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

if (!$connection) {
        echo &quot;Could not connect to database&quot;;
} else {
        echo &quot;Connected to database.&lt;br&gt;&quot;;
}  

$dbconnection = mysql_select_db($dbname);  

$query = &quot;SELECT * from users&quot;;  

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

mysql_close();  

?&gt;
</code></pre>

<p>Once you have created the source file, add the file to your git repository, commit the change, and push the change to your OpenShift Enterprise gear.</p>

<pre><code>$ git add .
$ git commit -am “Adding dbtest.php”
$ git push  
</code></pre>

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

<pre><code>http://firstphp-ose.example.com/dbtest.php  
</code></pre>

<p>You should see a screen with the following information: </p>

<pre><code>Connected to database.
1 gshipley@redhat.com 
</code></pre>

<h2 id="managingcartridges"><strong>Managing cartridges</strong></h2>

<p>OpenShift Enterprise provides the ability to embed multiple cartridges in an application. For instance, even though we are using MySQL for our <em>firstphp</em> 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:</p>

<pre><code>$ rhc cartridge status -a firstphp -c mysql  
</code></pre>

<p>To stop the cartridge, enter the following command:</p>

<pre><code>$ rhc cartridge stop -a firstphp -c mysql  
</code></pre>

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

<pre><code>http://firstphp-ose.example.com/dbtest.php  
</code></pre>

<p>You should see the following message returned to your browser: </p>

<pre><code>Could not connect to database  
</code></pre>

<p>Start the database back up using the <em>start</em> switch.</p>

<pre><code>$ rhc cartridge start -a firstphp -c mysql  
</code></pre>

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

<pre><code>$ rhc cartridge show mysql -a firstphp  
</code></pre>

<p>The user will then be presented with the following output: </p>

<pre><code>Password: ****  

mysql-5.1  
=========  
  Properties  
  ==========
    Username       = admin
    Password       = aFh_GsHP63fV
    Database Name  = firstphp
    Connection URL = mysql://127.1.244.1:3306/
</code></pre>

<h2 id="usingportforwarding"><strong>Using port forwarding</strong></h2>

<p>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. </p>

<p>With OpenShift Enterprise 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 Enterprise gear, you have to first forward all the ports to your local machine. This can be done using the <em>rhc port-forward</em> 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:</p>

<pre><code>$ rhc port-forward -a firstphp  

Checking available ports...  
Binding httpd -&gt; 127.11.144.1:8080...  
Binding mysqld -&gt; 127.11.144.1:3306...  
Forwarding ports, use ctl + c to stop  
</code></pre>

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

<p><strong>Note:</strong> 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. </p>

<pre><code>sudo ifconfig lo0 alias 127.11.144.1  
</code></pre>

<p>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 Enterprise gear, run the <em>mysql</em> command as shown below:</p>

<pre><code>$ mysql -uadmin -p -h 127.11.144.1  
</code></pre>

<p><strong>Note:</strong> The above command assumes that you have the MySQL client installed locally. </p>

<p><strong>Lab 24 Complete!</strong><br/>
<!--BREAK--> </p>

<h1 id="lab25:usingthewebconsoletocreateapplicationsestimatedtime:10minutes"><strong>Lab 25: Using the web console to create applications (Estimated time: 10 minutes)</strong></h1>

<p><strong>Server used:</strong></p>

<ul>
<li>localhost</li>
</ul>

<p><strong>Tools used:</strong></p>

<ul>
<li>OpenShift Enterprise web console</li>
<li>git</li>
</ul>

<p>OpenShift Enterprise provides users with multiple ways to create and manage applications. The platform provides command line tools, IDE integration, REST APIs, and a web console. During this lab, we will explore the creation and management of application using the web console. </p>

<p>Having DNS resolution setup on your local machine, as discussed in lab 16, is crucial in order to complete this lab. </p>

<h2 id="authenticatetothewebconsole"><strong>Authenticate to the web console</strong></h2>

<p>Open your favorite web browser and go to the following URL: </p>

<pre><code>http://broker.example.com  
</code></pre>

<p>Once you enter the above URL, you will be asked to authenticate using basic auth. For this training class, you can use the demo account that you created in a previous lab. </p>

<figure>
<img src="http://training.runcloudrun.com/images/consoleAuth.png" alt="" /></figure>


<p>After entering in valid credentials, you will see the OpenShift Enterprise web console dashboard: </p>

<figure>
<img src="http://training.runcloudrun.com/images/consoleDashboard.png" alt="" /></figure>


<h2 id="creatinganewapplication"><strong>Creating a new application</strong></h2>

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

<figure>
<img src="http://training.runcloudrun.com/images/php2.png" alt="" /></figure>


<figure>
<img src="http://training.runcloudrun.com/images/php2.1.png" alt="" /></figure>


<p>Once you have created the application, you will see a confirmation screen with some important information:</p>

<ul>
<li>URL for your application</li>
<li>GIT repository URL</li>
<li>Instructions for making code changes</li>
<li>Link to add a cartridge</li>
</ul>

<figure>
<img src="http://training.runcloudrun.com/images/php2.2.png" alt="" /></figure>


<h2 id="cloneyourapplicationrepository"><strong>Clone your application repository</strong></h2>

<p>Open up a command prompt and clone your application repository with the instructions provided on the web console. Once you have a local copy of your application, make a small code change to the <em>index.php</em> and push your changes to your OpenShift Enterprise gear. </p>

<p>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. </p>

<h2 id="addingacartridgewiththewebconsole"><strong>Adding a cartridge with the web console</strong></h2>

<p>Click on the <em>My Applications</em> tab at the top of the screen and then select the <em>Phptwo</em> application by clicking on it. </p>

<figure>
<img src="http://training.runcloudrun.com/images/php2.3.png" alt="" /></figure>


<p>After clicking on the <em>Phptwo</em> 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 MySQL database to our application. To do this, click on the <em>ADD CARTRIDGE</em> button. </p>

<figure>
<img src="http://training.runcloudrun.com/images/php2.4.png" alt="" /></figure>


<p>On the next screen, select the MySQL 5.1 cartridge. </p>

<figure>
<img src="http://training.runcloudrun.com/images/php2.5.png" alt="" /></figure>


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

<figure>
<img src="http://training.runcloudrun.com/images/php2.6.png" alt="" /></figure>


<p>If you recall from a previous lab, the connection information is always available via environment variables on your OpenShift Enterprise gear. </p>

<h2 id="verifydatabaseconnection"><strong>Verify database connection</strong></h2>

<p>Using information you learned in a previous lab, add a PHP file that tests the connection to the database. 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. </p>

<p><strong>Lab 25 Complete!</strong><br/>
<!--BREAK--> </p>

<h1 id="lab26:scalinganapplicationestimatedtime:15minutes"><strong>Lab 26: Scaling an application (Estimated time: 15 minutes)</strong></h1>

<p><strong>Server used:</strong></p>

<ul>
<li>localhost</li>
<li>node host</li>
</ul>

<p><strong>Tools used:</strong></p>

<ul>
<li>rhc</li>
<li>ssh</li>
<li>git</li>
<li>touch</li>
<li>pwd</li>
</ul>

<p>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 Enterprise infrastructure monitors incoming web traffic and automatically adds additional gear of your web cartridge online to handle requests. </p>

<h2 id="howscalingworks"><strong>How scaling works</strong></h2>

<p>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. </p>

<p>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 Enterprise 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. </p>

<p>The algorithm for scaling up and scaling down is based on the number of concurrent requests to your application. OpenShift Enterprise allocates 10 connections per gear - if HAProxy sees that you&#8217;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. Simple! </p>

<p>Because each cartridge is &#8220;share-nothing&#8221;, 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 Enterprise grows we anticipate adding more capabilities like shared storage, scaled databases, and shared caching. </p>

<p>The OpenShift Enterprise 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. </p>

<h2 id="createascaledapplication"><strong>Create a scaled application</strong></h2>

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

<pre><code>$ rhc app create scaledapp -t php -s  
</code></pre>

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

<pre><code>Password: ****  

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

  Scaling:   yes  
  Namespace: ose  
  Cartridge: php  
  Gear Size: default  

Your application's domain name is being propagated worldwide (this might take a minute)...  
The authenticity of host 'scaledapp-ose.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-ose.example.com/  
=============================================  
  Application Info  
  ================
    UUID      = 1a6d471841d84e8aaf25222c4cdac278
    Gear Size = small
    Git URL   =  
ssh://1a6d471841d84e8aaf25222c4cdac278@scaledapp-ose.example.com/~/git/scaledapp.git/
    SSH URL   = ssh://1a6d471841d84e8aaf25222c4cdac278@scaledapp-ose.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.  
</code></pre>

<p>Log in to the web console with your browser and click on the <em>scaledapp</em> application. You will notice while looking at the gear details that it lists the number of gears that your application is currently using. </p>

<figure>
<img src="http://training.runcloudrun.com/images/scaledApp.png" alt="" /></figure>


<h2 id="settingthescalingstrategy"><strong>Setting the scaling strategy</strong></h2>

<p>OpenShift Enterprise 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 the <em>Scaled up with HAProxy x2</em> button to change the default scaling rules. </p>

<figure>
<img src="http://training.runcloudrun.com/images/scaledApp2.png" alt="" /></figure>


<h2 id="manualscaling"><strong>Manual scaling</strong></h2>

<p>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:</p>

<ul>
<li>If you are anticipating a certain load on your application and wish to scale it accordingly.</li>
<li>You have a fixed set of resources for your application.</li>
</ul>

<p>OpenShift Enterprise 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 lab and are at the root level directory for the application. </p>

<p>From your locally cloned Git repository, create a <em>disable autoscaling</em> marker, as shown in the example below:</p>

<pre><code>$ touch .openshift/markers/disable_auto_scaling
$ git add .
$ git commit -a “remove automatic scaling”
$ git push  
</code></pre>

<p>To add a new gear to your application, SSH to your node host and enter the following command:</p>

<pre><code> $ add-gear -a [AppName] -u [AppUUID] -n [DomainName]  
</code></pre>

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

<pre><code>[scaledapp-ose.example.com ~]\&gt; add-gear -a scaledapp -u 1a6d471841d84e8aaf25222c4cdac278 -n ose  
</code></pre>

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

<pre><code>$ rhc app show scaledapp  
</code></pre>

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

<pre><code>scaledapp @ http://scaledapp-ose.example.com/  
=============================================  
  Application Info  
  ================
    SSH URL   = ssh://1a6d471841d84e8aaf25222c4cdac278@scaledapp-ose.example.com
    Gear Size = small
    Git URL   = ssh://1a6d471841d84e8aaf25222c4cdac278@scaledapp-ose.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
</code></pre>

<figure>
<img src="http://training.runcloudrun.com/images/scaledApp3.png" alt="" /></figure>


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

<pre><code>[scaledapp-ose.example.com ~]\&gt; remove-gear -a scaledapp -u 1a6d471841d84e8aaf25222c4cdac278 -n ose  
</code></pre>

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

<pre><code>$  rhc app show scaledapp  

scaledapp @ http://scaledapp-ose.example.com/  
=============================================  
  Application Info  
  ================
    Created   = 4:20 PM
    Gear Size = small
    SSH URL   = ssh://1a6d471841d84e8aaf25222c4cdac278@scaledapp-ose.example.com
    Git URL   = ssh://1a6d471841d84e8aaf25222c4cdac278@scaledapp-ose.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  
</code></pre>

<h2 id="viewinghaproxyinformation"><strong>Viewing HAProxy information</strong></h2>

<p>OpenShift Enterprise 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: </p>

<pre><code>http://scaledapp-ose.example.com/haproxy-status/  
</code></pre>

<figure>
<img src="http://training.runcloudrun.com/images/scaledApp4.png" alt="" /></figure>


<p><strong>Lab 26 Complete!</strong><br/>
<!--BREAK--> </p>

<h1 id="lab27:thediyapplicationtypeestimatedtime:10minutes"><strong>Lab 27: The DIY application type (Estimated time: 10 minutes)</strong></h1>

<p><strong>Server used:</strong></p>

<ul>
<li>localhost</li>
</ul>

<p><strong>Tools used:</strong></p>

<ul>
<li>rhc</li>
<li>git</li>
</ul>

<p>In addition to supporting Ruby, PHP, Perl, Python, and Java EE6, the OpenShift Enterprise environment supports the &#8220;Do it Yourself&#8221; or &#8220;DIY&#8221; application type. Using this application type, users can run just about any program that speaks HTTP. </p>

<p>How this works is remarkably straightforward. The OpenShift Enterprise execution environment is a carefully secured Red Hat Enterprise Linux operating system on x64 systems. Thus, OpenShift Enterprise can run any binary that will run on RHEL 6.3 x64. </p>

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

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

<p><strong>Note:</strong> 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 Enterprise cartridge. </p>

<h2 id="creatingadiyapplicationtype"><strong>Creating a DIY application type</strong></h2>

<p>To create an application gear that will use the DIY application type, use the <em>rhc app create</em> command:</p>

<pre><code>$ rhc app create -a myjavademo -t diy
$ cd diy  
</code></pre>

<h2 id="deployingapplicationcode"><strong>Deploying application code</strong></h2>

<p>Instead of spending time in this lab with writing a server runtime, we are going to use an existing one that is 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.</p>

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

<h2 id="verifythediyapplicationisworking"><strong>Verify the DIY application is working</strong></h2>

<p>Once the java example has been pushed to your OpenShift Enterprise gear, open up a web browser and point to the following URL: </p>

<pre><code>http://myjavademo-ose.example.com/index.html  
</code></pre>

<p><strong>Note:</strong> Make sure to include the index.html file at the end of the URL. </p>

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

<h2 id="underthecovers"><strong>Under the covers</strong></h2>

<p>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. </p>

<p>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 <em>wget</em> call to have the MyHttpServer stop itself: </p>

<pre><code>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 &gt;${OPENSHIFT_DIY_LOG_DIR}/MyHttpServer.log 2&gt;&amp;1 &amp;  

[24](ironmaiden:diy) &gt; 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  
</code></pre>

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

<p><strong>Lab 27 Complete!</strong><br/>
<!--BREAK--> </p>

<h1 id="lab28:developingjavaeeapplicationsusingjbosseapestimatedtime:30minutes"><strong>Lab 28: Developing Java EE applications using JBoss EAP (Estimated time: 30 minutes)</strong></h1>

<p><strong>Server used:</strong></p>

<ul>
<li>localhost</li>
</ul>

<p><strong>Tools used:</strong></p>

<ul>
<li>rhc</li>
<li>git</li>
<li>curl</li>
</ul>

<p>OpenShift Enterprise provides the JBoss EAP runtime to facilitate the development and deployment of Java EE 6 applications. </p>

<p>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 lab 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. </p>

<h2 id="createajbosseapapplication"><strong>Create a JBoss EAP application</strong></h2>

<p><strong>Note:</strong> Before starting this lab, it is suggested that you delete any existing applications that you have deployed to your OpenShift Enterprise installation. The OpenStack virtual machines that have been provided for this training class only contain 2gb of memory.</p>

<pre><code>$ rhc app create -a todo -t jbosseap  
</code></pre>

<p>Just as we saw in previous labs, a template has been deployed for you at the following URL: </p>

<pre><code>http://todo-ose.example.com  
</code></pre>

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

<h2 id="additionalmarkerfilesforjbosseap"><strong>Additional marker files for JBoss EAP</strong></h2>

<p>If you recall from a previous lab, we discussed the way that OpenShift Enterprise 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:</p>

<ul>
<li><p>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.</p></li>
<li><p>skip_maven_build - Maven build step will be skipped</p></li>
<li><p>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.</p></li>
<li><p>hot_deploy - Will prevent a JBoss container restart during build/deployment. Newly built archives will be re-deployed automatically by the JBoss HDScanner component.</p></li>
<li><p>java7 - Will run JBoss EAP with Java7 if present. If no marker is present then the baseline Java version will be used (currently Java6) </p></li>
</ul>

<h2 id="deploymentdirectory"><strong>Deployment directory</strong></h2>

<p>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 Enterprise server. </p>

<h2 id="maven"><strong>Maven</strong></h2>

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

<p>The most important thing specified in the <em>pom.xml</em> file is a Maven profile named <em>openshift</em>. This is the profile which is invoked when you do deploy the code to OpenShift Enterprise. </p>

<h2 id="embedpostgresqlcartridge"><strong>Embed PostgreSQL cartridge</strong></h2>

<p>The <em>todo</em> sample application that we are going to write as part of this lab will make use of the PostgreSQL database. Using the information that you have learned from previous labs, add the PostgreSQL cartridge to the <em>todo</em> application. </p>

<h2 id="buildingthetodoapplication"><strong>Building the <em>todo</em> application</strong></h2>

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

<h3 id="creatingdomainmodel"><strong>Creating Domain Model</strong></h3>

<p><strong>Note:</strong> The source code for this application is available on github at the following URL: </p>

<pre><code>https://github.com/gshipley/todo-javaee6  
</code></pre>

<p>If you want the easy way out, use the information you have learned from a previous lab to add the above repository as a remote repository and then pull in the source code while overwriting the existing template. </p>

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

<p>package com.todo.domain; </p>

<pre><code>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 = &quot;Tags&quot;, joinColumns = @JoinColumn(name = &quot;todo_id&quot;))  
    @Column(name = &quot;tag&quot;)  
    @NotNull  
    private List&lt;String&gt; 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&lt;String&gt; tags) {  
        this.tags = tags;
    }

    public List&lt;String&gt; getTags() {  
        return tags;
    }

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

}  
</code></pre>

<h3 id="createthepersistence.xmlfile"><strong>Create the <em>persistence.xml</em> file</strong></h3>

<p>The persistence.xml file is a standard configuration file in JPA that defines your data source. It has to be included in the <em>META-INF</em> 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 <em>META-INF</em> directory under src/main/resources and then create the <em>persistence.xml</em> file with the contents below: </p>

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

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

        &lt;/persistence-unit&gt;  
&lt;/persistence&gt;  
</code></pre>

<p>The <em>jta-data-source</em> refers to JNDI name preconfigured by OpenShift Enterprise in the standalone.xml file located in the <em>.openshift/config</em> directory. </p>

<h3 id="createthetodoserviceejbbean"><strong>Create the TodoService EJB bean</strong></h3>

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

<pre><code>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&lt;String&gt; tags = todo.getTags();
                System.out.println(&quot;Tags : &quot; + tags);
                return todo;
        }
}  
</code></pre>

<h3 id="enablecdi"><strong>Enable CDI</strong></h3>

<p>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 <em>todo</em> project, create a <em>beans.xml</em> file in <em>src/main/webapp/WEB-INF</em> directory with the following contents: </p>

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

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

<pre><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;

}  
</code></pre>

<h3 id="creatingarestfulwebservice"><strong>Creating a RESTful web service</strong></h3>

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

<pre><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 */
}  
</code></pre>

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

<pre><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(&quot;/todos&quot;)  
public class TodoRestService {

    @Inject  
    private TodoService todoService;

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

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

<h2 id="deploythetodoapplicationtoopenshiftenterprise"><strong>Deploy the <em>todo</em> application to OpenShift Enterprise</strong></h2>

<p>Now that we have our application created, we need to push our changes to the OpenShift Enterprise gear that we created earlier in this lab. From the application root directory, issue the following commands:</p>

<pre><code>$ git add .
$ git commit -am “Adding source code”
$ git push  
</code></pre>

<p>Once you execute the <em>git push</em> command, the application will begin building on the OpenShift Enterprise node host. During this training class, the OpenStack virtual machines we have created are not production grade environments. Because of this, the build process will take some time to complete. Sit back, be patient, and help your fellow classmates who may be having problems. </p>

<h2 id="testingthetodoapplication"><strong>Testing the <em>todo</em> application</strong></h2>

<p>In order to test out the RESTful web service that we created in this lab, we can add and retrieve todo items using the <em>curl</em> command line utility. To add a new item, enter the following command:</p>

<pre><code>$ curl -k -i -X POST -H &quot;Content-Type: application/json&quot; -d '{&quot;todo&quot;:&quot;Sell a lot of OpenShift Enterprise&quot;,&quot;tags&quot;:[&quot;javascript&quot;,&quot;ui&quot;]}' https://todo-ose.example.com/rest/todos  
</code></pre>

<p>To list all available todo items, run the following command:</p>

<pre><code>$ curl -k -i -H &quot;Accept: application/json&quot; https://todo-ose.example.com/rest/todos/1  
</code></pre>

<p>You should see the following output: </p>

<pre><code>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  

{&quot;id&quot;:1,&quot;todo&quot;:&quot;Sell a lot of OpenShift Enterprise&quot;,&quot;tags&quot;:[&quot;javascript&quot;,&quot;ui&quot;],&quot;createdOn&quot;:1359086546955}  
</code></pre>

<p>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 </p>

<pre><code>http://todo-ose.example.com  
</code></pre>

<p>to verify that the application was deployed correctly. </p>

<h2 id="extracredit"><strong>Extra Credit</strong></h2>

<p>SSH into the application gear and verify the todo item was added to the PostgreSQL database. </p>

<p><strong>Lab 28 Complete!</strong><br/>
<!--BREAK--> </p>

<h1 id="lab29:usingjenkinscontinuousintegrationestimatedtime:30minutes"><strong>Lab 29: Using Jenkins continuous integration (Estimated time: 30 minutes)</strong></h1>

<p><strong>Server used:</strong></p>

<ul>
<li>localhost</li>
<li>node host</li>
</ul>

<p><strong>Tools used:</strong></p>

<ul>
<li>rhc</li>
<li>git</li>
<li>yum</li>
</ul>

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

<p>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. </p>

<p>There are many reason why you would want to leverage Jenkins as a continuous integration server. In the context of OpenShift Enterprise, some of the benefits are:</p>

<ul>
<li>Archived build information</li>
<li>No application downtime during the build process</li>
<li>Failed builds do not get deployed (leaving the previous working version in place)</li>
<li>More resources to build your application as each Jenkins build spins up a new gear for short lived period of time</li>
</ul>

<p>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. </p>

<h2 id="verifyjenkinscartridgesareinstalled"><strong>Verify Jenkins cartridges are installed</strong></h2>

<p>SSH to your node host and verify that you have the Jenkins cartridges installed:</p>

<pre><code># rpm -qa |grep jenkins  
</code></pre>

<p>You should see the following four packages installed:</p>

<ul>
<li>openshift-origin-cartridge-jenkins&#8211;1.4&#8211;1.0.1&#8211;1.el6op.noarch</li>
<li>jenkins&#8211;1.488&#8211;2.el6op.noarch</li>
<li>openshift-origin-cartridge-jenkins-client&#8211;1.4&#8211;1.0.1&#8211;1.el6op.noarch</li>
<li>jenkins-plugin-openshift&#8211;0.6.5&#8211;0.el6op.x86_64</li>
</ul>

<p>If you do now have the above RPM packages installed on your node host, follow the directions in lab 17 to install the Jenkins packages. Make sure to clear the cache on the broker host after installing the new packages. </p>

<h2 id="createajenkinsgear"><strong>Create a Jenkins gear</strong></h2>

<p>In order to use Jenkins on OpenShift Enterprise, you will need to create an application gear to contains the Jenkins application. This is done using the <em>rhc app create</em> 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:</p>

<pre><code>$ rhc app create -a jenkins -t jenkins  
</code></pre>

<p>You should see the following output from this command: </p>

<pre><code>Creating application 'jenkins'  
==============================

  Gear Size: default  
  Scaling:   no  
  Cartridge: jenkins  
  Namespace: ose  

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

Cloning into 'jenkins'...  
done  

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

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-ose.example.com/me/configure  
</code></pre>

<p>Make a note of the user username and password that was created for you by OpenShift Enterprise. </p>

<h2 id="addingjenkinssupporttoyourapplication"><strong>Adding Jenkins support to your application</strong></h2>

<p>Now that we have a Jenkins server setup and running, we can add support to our <em>todo</em> 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:</p>

<pre><code>$ rhc cartridge add -a todo -c jenkins-client  
</code></pre>

<p>The output should be the following: </p>

<pre><code>Adding 'jenkins-client-1.4' to application 'todo'  
Success  
jenkins-client-1.4  
==================  
  Properties  
  ==========
    Job URL = https://jenkins-ose.example.com/job/todo-build/  
</code></pre>

<p>Verify that the Jenkins client was added to your application by running the following command:</p>

<pre><code>$ rhc app show todo  
</code></pre>

<p>At the bottom of the output, you should see the following information:</p>

<pre><code>  Cartridges  
  ==========
    jenkins-client-1.4 = https://jenkins-ose.example.com/job/todo-build/
    postgresql-8.4     = postgresql://127.1.248.129:5432/
    jbosseap-6.0
</code></pre>

<h2 id="configuringjenkins"><strong>Configuring Jenkins</strong></h2>

<p>Open up a web browser and point to the following URL: </p>

<pre><code>https://jenkins-ose.example.com/job/todo-build/  
</code></pre>

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

<figure>
<img src="http://training.runcloudrun.com/images/jenkins.png" alt="" /></figure>


<p>Once you are authenticated to the Jenkins dashboard, click on the configure link: </p>

<figure>
<img src="http://training.runcloudrun.com/images/jenkins2.png" alt="" /></figure>


<p>A few interesting configuration items exist that may come in handy in the future: </p>

<p><strong>Builder Configuration</strong>: 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. </p>

<figure>
<img src="http://training.runcloudrun.com/images/jenkins3.png" alt="" /></figure>


<p><strong>Git Configuration</strong>: 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 Enterprise. This would be useful for developers who have an internal repo for their source code that they would prefer to build from. </p>

<p><strong>Build Configuration</strong>: The last configuration item which is interesting is under the <em>build section</em>. Here you can specify a shell script for building the project. For our current builder it does the following:</p>

<ul>
<li>Specify if the project should be built using Java 6 or Java 7</li>
<li>Specify XMX memory configuration for maven and build the maven project. The memory it configures is 396M.</li>
<li>Deploying the application which includes stopping the application, pushing the content back from Jenkins to the application gear(s), and finally deploying the artifacts.</li>
</ul>

<p>The source code for the default build script is as follows: </p>

<pre><code>source /usr/libexec/openshift/cartridges/abstract/info/lib/jenkins_util  

jenkins_rsync 4d1b096e414243e9833dad55d774de73@todo-ose.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=&quot;$OPENSHIFT_MAVEN_XMX&quot;  
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-ose.example.com

# Push content back to application  
jenkins_sync_jboss 4d1b096e414243e9833dad55d774de73@todo-ose.example.com

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

jenkins_start_app 4d1b096e414243e9833dad55d774de73@todo-ose.example.com  

$GIT_SSH 4d1b096e414243e9833dad55d774de73@todo-ose.example.com post_deploy.sh
</code></pre>

<p><strong>Deploying code to Jenkins</strong> </p>

<p>Now that you have the Jenkins client embedded into your <em>todo</em> application gear, any future <em>git push</em> commands will send the code to the Jenkins server for building. To test this out, edit the <em>src/main/webapp/todo.xhtml</em> 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: </p>

<pre><code>&lt;h2&gt;Todo List Creation&lt;/h2&gt;  
</code></pre>

<p>Change the above code to the following: </p>

<pre><code>&lt;h2&gt;Todo List Creation using Jenkins&lt;/h2&gt;  
</code></pre>

<p>Commit and push your change:</p>

<pre><code>$ git commit -am “changed h2”
$ git push  
</code></pre>

<p>After you push your changes to the Jenkins server, you should see the following output: </p>

<pre><code>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-ose.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-ose.example.com/~/git/todo.git/
   eb5f9dc..8cee826  master -&gt; master  
</code></pre>

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

<pre><code>$ rhc domain show  
</code></pre>

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

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

<p>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. </p>

<figure>
<img src="http://training.runcloudrun.com/images/jenkins4.png" alt="" /></figure>


<h2 id="startinganewbuild"><strong>Starting a new build</strong></h2>

<p>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 <em>todo</em> builder. Point your browser to: </p>

<pre><code>https://jenkins-ose.example.com/  
</code></pre>

<p>Once you have been authenticated, click the <em>todo-build</em> link: </p>

<figure>
<img src="http://training.runcloudrun.com/images/jenkins5.png" alt="" /></figure>


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

<figure>
<img src="http://training.runcloudrun.com/images/jenkins6.png" alt="" /></figure>


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

<figure>
<img src="http://training.runcloudrun.com/images/jenkins7.png" alt="" /></figure>


<p>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. </p>

<p><strong>Lab 29 Complete!</strong><br/>
<!--BREAK--> </p>

<h1 id="lab30:usingjbosstoolsestimatedtime:30minutes"><strong>Lab 30: Using JBoss Tools (Estimated time: 30 minutes)</strong></h1>

<p><strong>Server used:</strong></p>

<ul>
<li>localhost</li>
</ul>

<p><strong>Tools used:</strong></p>

<ul>
<li>eclipse</li>
</ul>

<p>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&#8230; </p>

<h2 id="downloadandinstalleclipse-juno"><strong>Download and install Eclipse - Juno</strong></h2>

<p>In this lab, 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. </p>

<p>Once you have Eclipse installed, go to the JBoss Tools page located at </p>

<pre><code>http://www.jboss.org/tools  
</code></pre>

<p>and follow the instructions to install JBoss Tools 4.0 (Juno). </p>

<h2 id="usingjbosstoolsandopenshiftenterprise"><strong>Using JBoss Tools and OpenShift Enterprise</strong></h2>

<p>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 Enterprise installation, we need to configure Eclipse with our <em>LIBRA_SERVER</em> setting. This is a straight forward process but one that may catch people off guard. To make the change, edit the <em>eclipse.ini</em> file located in the root directory of your Eclipse deployment and add <em>-Dlibra_server=broker.example.com</em> directly after the the following line: </p>

<pre><code>-vmargs  
</code></pre>

<p>When finished, it should look like this: </p>

<pre><code>-vmargs  
-Dlibra_server=broker.example.com  
</code></pre>

<p><strong>Note:</strong> 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&#8217;ll have to edit the <em>eclipse.ini</em> file inside the Eclipse application bundle: </p>

<ul>
<li>Select the Eclipse application bundle icon while holding down the Control Key</li>
<li>This will present you with a popup menu. Select &#8220;Show Package Contents&#8221; in the popup menu.</li>
<li>Locate eclipse.ini file in the Contents/MacOS sub-folder and open it with your favorite text editor to edit the command line options.</li>
</ul>

<p>On my OS X operating system, after editing the <em>eclipse.ini</em> file it looks like following: </p>

<pre><code>-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=broker.example.com  
-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  
</code></pre>

<p>After adding the correct arguments to the <em>eclipse.ini</em> file, restart the Eclipse IDE. </p>

<h2 id="createanopenshiftenterpriseapplication"><strong>Create an OpenShift Enterprise application</strong></h2>

<p>Now that we have Eclipse Juno and JBoss Tools 4.0 installed, we can create an OpenShift Enterprise application without having the leave the comfort of our favorite IDE. Click on the <em>OpenShift Applicaiton</em> link that is provided on the JBoss Central screen. </p>

<figure>
<img src="http://training.runcloudrun.com/images/jbosstools1.png" alt="" /></figure>


<p>Once you click on the link to create a new OpenShift Enterprise application, you will be presented with a dialog to authenticate to OpenShift Enterprise. Now is also a good time to validate the <em>Server</em> setting is correctly set to <em>broker.example.com</em>. If your server does not reflect this, you have not configured your <em>eclipse.ini</em> file correctly. If you are unable to configure your <em>eclipse.ini</em> file as specified in this lab, inform the instructor so that he/she may help you. </p>

<figure>
<img src="http://training.runcloudrun.com/images/jbosstools2.png" alt="" /></figure>


<p>After clicking <em>next</em>, 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 <em>Use existing application</em> and click the <em>Browse</em> button. After clicking the <em>Browse</em> button, a REST API call be made to the broker host to retrieve the existing applications that you already have deployed. </p>

<figure>
<img src="http://training.runcloudrun.com/images/jbosstools3.png" alt="" /></figure>


<p>Highlight the <em>todo</em> application and click on the <em>Details&#8230;</em> button. This will display all of the necessary information about the application, including any cartridges that may be embedded. </p>

<figure>
<img src="http://training.runcloudrun.com/images/jbosstools4.png" alt="" /></figure>


<p>After clicking <em>Next</em>, 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. </p>

<figure>
<img src="http://training.runcloudrun.com/images/jbosstools5.png" alt="" /></figure>


<p>Once you click the <em>Finish</em> button, the existing application will be cloned to your local project. </p>

<h2 id="managingopenshiftenterpriseapplicationwithjbosstools"><strong>Managing OpenShift Enterprise application with JBoss Tools</strong></h2>

<p>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 Enterprise server. </p>

<figure>
<img src="http://training.runcloudrun.com/images/jbosstools6.png" alt="" /></figure>


<h3 id="tailinglogfiles"><strong>Tailing log files</strong></h3>

<p>After clicking on the <em>servers</em> tab, right click on your OpenShift Enterprise server and then select <em>OpenShift</em> and finally select <em>tail files</em>. </p>

<figure>
<img src="http://training.runcloudrun.com/images/jbosstools7.png" alt="" /></figure>


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

<h3 id="viewingenvironmentvariables"><strong>Viewing environment variables</strong></h3>

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

<h3 id="usingport-forwarding"><strong>Using port-forwarding</strong></h3>

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

<figure>
<img src="http://training.runcloudrun.com/images/jbosstools8.png" alt="" /></figure>


<p>For the next section of this lab, ensure that you click on <em>Start Forwarding</em> so that we will be able to connect to PostgreSQL from our local machine. </p>

<h3 id="addingpostgresqlasaneclipsedatasource"><strong>Adding PostgreSQL as an Eclipse data source</strong></h3>

<p>Download the latest PostgreSQL driver from the following location </p>

<pre><code>http://jdbc.postgresql.org/download.html  
</code></pre>

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

<figure>
<img src="http://training.runcloudrun.com/images/db1.png" alt="" /></figure>


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

<p>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:</p>

<ul>
<li>Database: todo</li>
<li>URL: jdbc:postgresql://127.0.0.1:5432/todo</li>
<li>User name: admin</li>
<li>Password: The password supplied by OpenShift. If you forgot this, use the <em>Environment Variables</em> utility provided by JBoss Tools.</li>
</ul>

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

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

<figure>
<img src="http://training.runcloudrun.com/images/db2.png" alt="" /></figure>


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

<h2 id="makingacodechangeanddeployingtheapplication"><strong>Making a code change and deploying the application</strong></h2>

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

<pre><code>&lt;h2&gt;Todo List Creation using Jenkins&lt;/h2&gt;  
</code></pre>

<p>to the include JBoss Tools </p>

<pre><code>&lt;h2&gt;Todo List Creation using Jenkins and JBoss Tools&lt;/h2&gt;  
</code></pre>

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

<figure>
<img src="http://training.runcloudrun.com/images/tools1.png" alt="" /></figure>


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

<figure>
<img src="http://training.runcloudrun.com/images/tools2.png" alt="" /></figure>


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

<pre><code>http://todo-ose.example.com/      
</code></pre>

<figure>
<img src="http://training.runcloudrun.com/images/tools3.png" alt="" /></figure>


<p><strong>Lab 30 Complete!</strong><br/>
<!--BREAK--> </p>

<h1 id="lab31:usingquickstartsestimatedtime:10minutes"><strong>Lab 31: Using quickstarts (Estimated time: 10 minutes)</strong></h1>

<p><strong>Server used:</strong></p>

<ul>
<li>localhost</li>
</ul>

<p><strong>Tools used:</strong></p>

<ul>
<li>rhc</li>
<li>git</li>
</ul>

<p>A key tenant when Red Hat was designing OpenShift Enterprise 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 Enterprise, 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:</p>

<ul>
<li>Drupal</li>
<li>Review Board</li>
<li>Wordpress</li>
<li>Frog CMS</li>
<li>Sugar CRM</li>
<li>Redmine</li>
<li>MediaWiki</li>
</ul>

<h2 id="installaquickstart"><strong>Install a quickstart</strong></h2>

<p>Point your browser to the following URL: </p>

<pre><code>http://www.github.com/openshift  
</code></pre>

<p>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 lab, choose either the Wordpress or Drupal quick start and follow the instructions provided to install the application. </p>

<figure>
<img src="http://training.runcloudrun.com/images/quickstart.png" alt="" /></figure>


<p><strong>Lab 31 Complete!</strong><br/>
<!--BREAK--><br/>
<strong>Lab 32: Creating a quick start (Estimated time: 30 minutes)</strong> </p>

<p><strong>Server used:</strong></p>

<ul>
<li>localhost</li>
<li>node host</li>
</ul>

<p><strong>Tools used:</strong></p>

<ul>
<li>rhc</li>
<li>git</li>
<li>github</li>
</ul>

<p>A common task that you will be asked to do is make a software developers development environment easily deployable on OpenShift Enterprise. 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 lab, we saw how easy it was to install applications via our quick start process. During this lab, we will focus on the ability for you to create your own quick starts using the popular open source project Piwik as an example. </p>

<h2 id="downloadthepiwiksourcecode"><strong>Download the Piwik source code</strong></h2>

<p>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 <em>~/code/piwikstage</em>. </p>

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

<pre><code>$ cd ~
$ mkdir code
$ mkdir piwikstage
$ unzip latest.zip
</code></pre>

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

<h2 id="createanopenshiftenterpriseapplication"><strong>Create an OpenShift Enterprise application</strong></h2>

<p>We need to create an OpenShift Enterprise application to hold the source code as well as embed the MySQL database:</p>

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

<p>OpenShift Enterprise, as you know, creates a default <em>index</em> file for your application. Because we are going to be using the source code from our Piwik applicaiton, we need to remove the existing template.</p>

<pre><code>$ rm -rf ~/code/piwik/php/*  
</code></pre>

<p>At this point, we need to copy over the source code that we extracted from the zip archive to our <em>piwik</em> OpenShift Enterprise applciation:</p>

<pre><code>$ cp –av ~/code/piwikstage/piwik/* ~/code/piwik/php  
</code></pre>

<p>Now we need to add and commit our changes to our <em>piwik</em> applicaiton:</p>

<pre><code>$ cd ~/code/piwik/php
$ git add .
$ git commit –am “Initial commit for Piwik”
$ git push
</code></pre>

<p>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: </p>

<pre><code>http://piwik-ose.example.com  
</code></pre>

<figure>
<img src="http://training.runcloudrun.com/images/piwik.png" alt="" /></figure>


<h2 id="creatingagithubrepository"><strong>Creating a github repository</strong></h2>

<p><strong>Note</strong>: 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).</p>

<p>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: </p>

<pre><code>https://github.com/repositories/new  
</code></pre>

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

<figure>
<img src="http://training.runcloudrun.com/images/piwik2.png" alt="" /></figure>


<p>On your newly created project space, grab the HTTP Git URL and add the github repository as a remote to your existing <em>piwik</em> OpenShift Enterprise application. </p>

<figure>
<img src="http://training.runcloudrun.com/images/piwik3.png" alt="" /></figure>


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

<h2 id="createdeploymentinstructions"><strong>Create deployment instructions</strong></h2>

<p>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 <em>README</em> and <em>README.md</em> 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: </p>

<pre><code>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 -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  
</code></pre>

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

<pre><code>$ cd ~/code/piwik
$ git add .
$ git commit -am “Add installation instructions”  
</code></pre>

<p>Now we need to push these changes to the github repository we created:</p>

<pre><code>$ git push -u github master  
</code></pre>

<h2 id="verifyyourquickstartworks"><strong>Verify your quick start works</strong></h2>

<p>Delete the <em>piwik</em> OpenShift Enterprise application and follow the instruction you created for your Piwik quick start to verify that everything works as expected. </p>

<p><strong>Note:</strong> 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 <em>mysqldump</em> 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.</p>

<h1 id="appendixa-troubleshooting"><strong>Appendix A - Troubleshooting</strong></h1>

<h2 id="diagnosticsscript"><strong>Diagnostics script</strong></h2>

<p>Installing and configuring an OpenShift Enterprise PaaS can often fail due to simple mistakes in configuration files. Fortunately, the team provides an unsupported troubleshooting script that can diagnose most problems with an installation. This script is located on the lab support website and is called <em>oo-diagnostics</em>. For this lab, running the version provided on the support website should suit your needs but when helping customers out, I suggest you pull the script from the official github repository to ensure that you have most updated version. The github script can is located at: </p>

<pre><code>https://raw.github.com/openshift/origin-server/master/util/oo-diagnostics  
</code></pre>

<p>This script can be run on any OpenShift Enterprise broker or node host. Once you have the script downloaded, change the permission to enable execution of the script:</p>

<pre><code># chmod +x oo-diagnostics  
</code></pre>

<p>To run the command and check for errors, issue the following command:</p>

<pre><code># ./oo-diagnostics -v  
</code></pre>

<p><strong>Note:</strong> Sometimes the script will fail at the first error and not continue processing. In order to run a full check on your node, add the <em>&#8211;abortok</em> switch</p>

<pre><code># ./oo-diagnostics -v --abortok  
</code></pre>

<p>Under the covers, this script performs a lot of checks on your host as well as executing the existing <em>oo-accept-broker</em> and <em>oo-accept-node</em> commands on the respective host. </p>

<h2 id="recoveringfailednodes"><strong>Recovering failed nodes</strong></h2>

<p>A node host that fails catastrophically can be recovered if the gear directory /var/lib/openshift has been stored in a fault-tolerant way and can be recovered. In practice this scenario occurs rarely, especially when node hosts are virtual machines in a fault tolerant infrastructure rather than physical machines. </p>

<p><strong>Note: Do not start the MCollective service until you have completed the following steps.</strong> </p>

<p>Install a node host with the same hostname and IP address as the one that failed. The hostname DNS A record can be adjusted if the IP address must be different, but note that the application CNAME and database records all point to the hostname, and cannot be easily changed. </p>

<p>Duplicate the old node host&#8217;s configuration on the new node host, ensuring in particular that the gear profile is the same. </p>

<p>Mount <em>/var/lib/openshift</em> from the original, failed node host. SELinux contexts must have been stored on the <em>/var/lib/openshift</em> volume and should be maintained. </p>

<p>Recreate /etc/passwd entries for all the gears using the following steps:</p>

<ul>
<li>Get the list of UUIDs from the directories in /var/lib/openshift.</li>
<li>Get the Unix UID and GID values from the group value of /var/lib/openshift/UUID.</li>
<li>Create the corresponding entries in /etc/passwd, using another node&#8217;s /etc/passwd file for reference.</li>
</ul>

<p>Reboot the new node host to activate all changes, start the gears, and allow MCollective and other services to run. </p>

<h2 id="removingapplicationsfromanode"><strong>Removing applications from a node</strong></h2>

<p>While trying to add a node to a district, a common error is that the node already has user applications on it. In order to be able to add this node to a district, you will either need to move these applications to another node or delete the applications. In this training class, it is suggested that you simply delete the application as we are working in a single node host configuration. In order to remove a users application, issue the following commands:</p>

<pre><code># oo-admin-ctl-app -l username -a appname -c stop
# oo-admin-ctl-app -l username -a appname -c destroy  
</code></pre>

<p>The above commands will stop the users application and them remove the application from the node. If you want to preserve the application data, you should backup the application first using the snapshot tool that is part of the RHC command line tools. </p>

<p><strong>Lab 32 Complete!</strong><br/>
<!--BREAK--> </p>

<h1 id="appendixa-troubleshooting"><strong>Appendix A - Troubleshooting</strong></h1>

<h2 id="diagnosticsscript"><strong>Diagnostics script</strong></h2>

<p>Installing and configuring an OpenShift Enterprise PaaS can often fail due to simple mistakes in configuration files. Fortunately, the team provides an unsupported troubleshooting script that can diagnose most problems with an installation. This script is located on the lab support website and is called <em>oo-diagnostics</em>. For this lab, running the version provided on the support website should suit your needs but when helping customers out, I suggest you pull the script from the official github repository to ensure that you have most updated version. The github script can is located at: </p>

<pre><code>https://raw.github.com/openshift/origin-server/master/util/oo-diagnostics  
</code></pre>

<p>This script can be run on any OpenShift Enterprise broker or node host. Once you have the script downloaded, change the permission to enable execution of the script:</p>

<pre><code># chmod +x oo-diagnostics  
</code></pre>

<p>To run the command and check for errors, issue the following command:</p>

<pre><code># ./oo-diagnostics -v  
</code></pre>

<p><strong>Note:</strong> Sometimes the script will fail at the first error and not continue processing. In order to run a full check on your node, add the <em>&#8211;abortok</em> switch</p>

<pre><code># ./oo-diagnostics -v --abortok  
</code></pre>

<p>Under the covers, this script performs a lot of checks on your host as well as executing the existing <em>oo-accept-broker</em> and <em>oo-accept-node</em> commands on the respective host. </p>

<h2 id="recoveringfailednodes"><strong>Recovering failed nodes</strong></h2>

<p>A node host that fails catastrophically can be recovered if the gear directory /var/lib/openshift has been stored in a fault-tolerant way and can be recovered. In practice this scenario occurs rarely, especially when node hosts are virtual machines in a fault tolerant infrastructure rather than physical machines. </p>

<p><strong>Note: Do not start the MCollective service until you have completed the following steps.</strong> </p>

<p>Install a node host with the same hostname and IP address as the one that failed. The hostname DNS A record can be adjusted if the IP address must be different, but note that the application CNAME and database records all point to the hostname, and cannot be easily changed. </p>

<p>Duplicate the old node host&#8217;s configuration on the new node host, ensuring in particular that the gear profile is the same. </p>

<p>Mount <em>/var/lib/openshift</em> from the original, failed node host. SELinux contexts must have been stored on the <em>/var/lib/openshift</em> volume and should be maintained. </p>

<p>Recreate /etc/passwd entries for all the gears using the following steps:</p>

<ul>
<li>Get the list of UUIDs from the directories in /var/lib/openshift.</li>
<li>Get the Unix UID and GID values from the group value of /var/lib/openshift/UUID.</li>
<li>Create the corresponding entries in /etc/passwd, using another node&#8217;s /etc/passwd file for reference.</li>
</ul>

<p>Reboot the new node host to activate all changes, start the gears, and allow MCollective and other services to run. </p>

<h2 id="removingapplicationsfromanode"><strong>Removing applications from a node</strong></h2>

<p>While trying to add a node to a district, a common error is that the node already has user applications on it. In order to be able to add this node to a district, you will either need to move these applications to another node or delete the applications. In this training class, it is suggested that you simply delete the application as we are working in a single node host configuration. In order to remove a users application, issue the following commands:</p>

<pre><code># oo-admin-ctl-app -l username -a appname -c stop
# oo-admin-ctl-app -l username -a appname -c destroy  
</code></pre>

<p>The above commands will stop the users application and them remove the application from the node. If you want to preserve the application data, you should backup the application first using the snapshot tool that is part of the RHC command line tools.</p>
    </div>
</body>
</html>