OpenShift Online 2.0 User Guide en US

OpenShift OpenShift Online All Versions User Guide

M anaging Appli Applicat cat ions in the t he Cloud with OpenShift Online Online Edition Edition 1.0 1 .0

Red Red Hat OpenShi OpenShift ft Documen Documentt ation at ion Team

OpenShift Online All Versions User Guide

M anaging Appli Applicat cat ions in the t he Cloud with OpenShift Online Online Edition Edition 1.0 1 .0

Red Hat OpenShift Do cumentation Team

Legal Notice

Copyright © 2013 Red Hat. T his document is is licensed by Red Hat under the Creative Commons Attribution-ShareAlike 3.0 Unported License.. If you distribute this document, or a modified version of it, you must provide attribution to Red License Hat, Inc. Inc. and provide a link to the original. o riginal. IfIf the document is modified, all Red Hat trademarks tr ademarks must be removed. Red Hat, as the licensor of this document, waives the right to enforce, and agrees not to assert, Section 4d of CC-BY-SA to the fullest extent permitted by applicable law. Red Hat, Red Hat Enterpris e Linux, the Shadowman logo, JBoss , MetaMatrix, MetaMatrix, Fedora, Fedora, OpenShift, the Infinity Logo, and RHCE are trademarks tr ademarks of Red Hat, Inc., Inc., regis tered in the United States and other countries. Linux ® is the regis tered trademark trademark of Linus Linus T orvalds in the United States States and other countries. Java ® is a registered r egistered trademark of Oracle Oracle and/or its affiliates. XFS ® is a trademark of Silicon Graphics International Corp. or its subsidiaries in the United States and/or other countries. MySQL ® is a registered trademark of MySQL AB in the United States, the European Union and other countries. Node.js ® is an official trademark of Joyent. Red Hat Software Collections is not formally related to or endorsed by the official Joyent Node.js open source or commercial project. All other other trademarks are the property of their res pective owners. owners. Abstract

This guide provides an introduction to OpenShift Online and documents its application management functions.

Table of Contents

Table of Contents Preface ............................................................................................. 1. Document Document Conventions Conventions 1.1. T ypographic Conventions 1.2. Pull-quote Pull-quote Conventions 1.3. Notes Notes and Warnings Warnings 2. Getting Getting Help 2.1. 2.1. Do You Need Help? 2.2. We 2.2. We Need Feedback! Feedbac k!

5 5 5 6 7 7 7 8

Chapte Introductio .Chapter . . . . . . .r. .1.. .Introduction . . . . . . . . . . . .n. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9 1.1. Product Product Introduction 9 1.2. Platform Overview 9 S. tarte .Chapter . . . . . . . . 2. . . .Getting . . . . . . . . .Starte .....d . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1. 1 2.1. User User Interfaces 11 2.1.1. 2.1.1. Management Console Co nsole 11 2.1.2. 2.1.2. Client Tools 12 2.2. Basic Administr Administr ation 12 2.2.1. 2.2.1. Management Console Management Console 12 2.2.2. 2.2.2. Client T ools 13 Chapte A oke .Chapter . . . . . . .r. .3.. .Authoriza . uthoriza . . . . . . . . . tion . . . . .T. okens . . . ns . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1. 5 3.1. Authorization Authorization Tokens 15 3.2. Creating Creating Authorization Authorizatio n T okens okens 15 3.3. Viewing Authorization Tokens 16 3.4. Deleting Deleting Authoriz ation Tokens 16 Chapte Dom .Chapter . . . . . . . r. .4... Domains . . . . .ains ....... ....................................................................1 .8 4.1. About About Domains 18 4.2. Creating Creating a Domain Doma in 18 4.3. Lis Lis ting Available Domains 18 4.4. Viewing Viewing a Domain 19 4.5. Renaming Renaming a Domain 19 4.6. Deleting a Domain 20 4.7. Custom Custom Domains and SSL Certificates 21 4.7.1. Using 4.7.1. Using Cus tom Domain Domain Names 21 4.7.2. Using 4.7.2. Using Custom SSL Certificates SSL Certificates 22

.Chapter . . . . . . . . 5. . . .Members . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2 .3 5.1. About About Members 23 5.2. Adding a Member 23 5.3. Listing Members 23 5.4. Removing a Member 24 .Chapter . . . . . . . . .6.. .Applications . . . . . . . . . . . . . .and . . . . .Cartridges . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .25 6.1. About Applications 25 6.1.1. About Scaled Applications 25 6.1.1.1. How Scaling Works 25 6.1.2. 6.1.2. About Non-Scaled Non -Scaled Applications 26 6.1.3. 6.1.3. Viewing Access ible Applications 26 6.2. About Cartr idges 27 6.2.1. Web Cartridges 27 6.2.2. 6.2.2. Add-on Cartridges 27

1


6.2.3. 6.2.3. Downloadable Cartridges 6.3. Creating an Application 6.3.1. Creating Scaled Applications 6.3.2. 6.3.2. Creating Single-Instance Applications 6.3.3. Manually Scaling an Application 6.4. Adding and Managing Cartridges 6.4.1. Adding Cartridges Cartridg es 6.4.2. Managing Cartridge s 6.4.2.1. 6.4.2.1. Cartridge Action Hooks 6.5. Deployment 6.5.1. Build and Deployment Action Hooks 6.5.2. 6.5.2. Preparing an Application for Deployment 6.5.3. Deploying an Application 6.5.4 6.5.4 . Configuring Application Deployment 6.5.4 6.5.4 .1. Deploying an Application From a Snapshot Snaps hot 6.5.5. About Hot Deployment 6.5.5.1. Hot Deployment Build Details 6.5.5.2. 6.5.5.2. Enabling and Disabling Disab ling Hot Deployment 6.5.6. 6.5.6. JBoss Application Deployment 6.5.6.1. 6.5.6.1. Deploying on Java 6 or Java 7 6.5.6.2. Automatic Deployment 6.5.6.3. 6.5.6.3. T ypes of Marker Files 6.5.6.4. 6.5.6.4. Example Example JBos s Application Deployment Workflows 6.6. About Jenkins Online Build System 6.6.1. 6.6.1. Configuring Jenkins 6.6.1.1. 6.6.1.1. Resource Res ource Requir ements for Jenkins 6.6.2. 6.6.2. Creating Jenkins -enabled Applications 6.6.2.1. 6.6.2.1. Creating a Scaled JenkinsJen kins-Enabled Enabled Application 6.6.2.2. 6.6.2.2. Creating a Single-Instance Jenkins-Enabled Jenkins -Enabled Application 6.6.2.3. Confirming that a Jenkins-Enabled Application is Created 6.6.3. 6.6.3. Building Applications with Jenkins 6.6.3.1. Building Custom Applications 6.7. Deleting an a n Application 6.7.1. Deleting Local Application Data 6.8. Gears and Storage Management 6.8.1. Viewing Gear Storage 6.8.2. Adding Gear Storage 6.8.3. Set Gear Storage 6.8.4 6.8.4 . Removing Removing Gear Gea r Storage Stora ge 6.8.5. 6.8.5. Managing Application Disk Space 6.8.5.1. 6.8.5.1. Disk Space Cleanup T ool

28 29 30 30 32 33 33 34 34 35 35 36 36 37 38 38 39 39 40 40 41 42 42 43 43 43 44 44 44 44 45 46 46 46 47 47 48 48 49 49 49

.Chapter . . . . . . . . .7.. .Application . . . . . . . . . . . . .Management . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .51 7.1. Application Management Commands 51 7.2. Managing Applications in a Secure Shell Environment 51 7.2.1. 7.2.1. Accessing Access ing an Application 51 7.2.2. 7.2.2. Accessing Access ing a Specific Gear 52 7.2.3. Accessing a Database Cartridge 53 7.3. Environment Environment Variables 54 7.3.1. Informational Environment Variables 55 7.3.2. 7.3.2. Directory Environment Variables 55 7.3.3. 7.3.3. Database Databas e Environment Variables 56 7.3.4 7.3.4 . Jenkins Environment Variables 57 7.3.5. 7.3.5. Gear Environment Variables 57 7.3.6. 7.3.6. JBoss Environment Variables 57 7.3.7. 7.3.7. Custom Cus tom Environment Variables Variab les 58

2

Table of Contents

7.4. About Node.js Node.js Applications 7.4.1. Repository Repos itory Layout 7.4.2. Ins Installing talling Node Modules 7.5. Scheduling Timed Jobs with Cron 7.6. Available Ports for Binding Applications 7.6.1. 7.6.1. WebSocket Port Configuration 7.6.2. Email Port Configuration

59 59 59 60 61 63 63

Chapte K . . . . . . . . r. .8. . . Authentication . . . . . . . . . . . . . . . . .and . . . .SSH . . . . .Keys . .eys . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .6 4 8.1. Viewing All Public Keys 64 8.2. Viewing a Specific Public Key 64 8.3. Generating Keys Manually 65 8.4. Adding a Key 65 8.4.1. Creating a Specific SSH SSH Key T ype 65 8.4.2. Removing a Key 66 8.5. Resolving Authentication Issues 66 8.5.1. Resolving Issues with Interactive Setup Wizard 66

.Chapter . . . . . . . . .9.. .Monitoring . . . . . . . . . . . . and . . . . .Troubleshooting . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .67 9.1. Monitoring Application Res ources 67 9.2. MongoDB Monitoring Service (MMS) 67 9.2.1. Configuring an Application with MMS 67 9.2.2. Monitoring Applications with MMS 68 9.2.2.1. Adding Hosts to MMS 68 9.2.2.2. MMS Monitoring with a Browser 69 9.3. Troubleshooting JBoss Applications 69 9.3.1. 9.3.1. Debugging with T hread Dumps 69 9.3.2. 9.3.2. Ins Inspecting pecting Server, Serve r, Boot and Other Log Files 70 9.4. Performing Application Maintenance from Workstation 71 9.4.1. Port Port Forwarding 71 9.4.1.1. Port Forwarding on Mac OS X 72 Chapt Backi U.p. .and A.pplication . . . . . . .er . . .10 . . . .Backing . . . . . ng . . . .Up . . . . .Restoring . . . . . . . . . . .Appli . . . .cation . . . . . . .Da . . .ta . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .7 4 10.1. Creating Application Snapshots 74 10.2. Restoring Application Snapshots 74 10.3. Migrating an Application to Another Gear 75 Revision Hi . . . . . . . . . .Histor . .stor . . . .y . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .77

3


4

Preface

Preface 1. Document Conventions T his manual uses s everal conventions conventions to highlight highlight certain words and phrases and draw attention attention to specific pieces of information. information. In PDF and paper editions, this manual uses typefaces drawn from the Li Liberation beration Fonts set. The Liberation Fonts Fonts set is als o used us ed in HT ML editions editions if the set is ins talled on your sys tem. tem. IfIf not, alternative alternative but equivalent typefaces are displayed. Note: Red Hat Enterprise Linux 5 and later include the Liberation Fonts set by default.

1.1. Typographic Conventions Four typographic typographic conventions conventions are us ed to call attention attention to specific words words and phras es. These T hese conventions, conventions, and the circumstances they apply to, are as follows. follows. Mono-spaced Mono-spaced Bold Used to highlight system input, including shell commands, file names and paths. Also used to highlight keys and key combinations. For example: To see the contents of the file my_next_bestselling_novel in your current working directory, enter the cat my_next_bestselling_novel command at the shell prompt and press press Enter to Enter to execute the command. The above includes a file name, a shell command and a key, all presented in mono-spaced bold and all distinguishable thanks to context. Key combinati combinations ons can be distinguished from an individual individual key by the plus s ign that connects each part of a key combination. For For example: e xample: Press Enter to Enter to execute the command. Press Ctrl+ Ctrl + Alt+ Alt+ F2 to F2 to switch to a virtual terminal. T he first example example highlights highlights a particular key to pres s. T he s econd example example highlights highlights a key combination: combination: a set of three keys pressed simultaneously. If s ource code is discuss ed, class class names, names, methods, methods, functions, variable variable names names and returned values mentioned within a paragraph will be presented as above, in m ono-spaced ono-spaced bold . For example: File-related File-related classes include include filesystem for file s ystems, file for file for files, and dir di r for directories. Each class has its own associated set of permissions. Proportional Bold

T his denotes words or phrases encountered on a sys tem, tem, includi including ng application application names; names; dialog-box text; text; labeled buttons; check-box and radio-button labels; menu titles and submenu titles. For example: Choose System → Preferences → Mouse from the main menu bar to launch Mouse Preferences. In the Buttons tab, Buttons tab, select the Left-handed Left-handed m ouse ouse check box and click Close to Close to switch the primary mouse button from the left to the right (making the mouse suitable for use in the left hand). T o insert a s pecial character character into a gedit file, choose Applications → Accessories →

5


Character Map from the main menu bar. Next, choose Search → Find… from the Search field and click Character Map menu bar, type the name of the character in the Search field Next. Next. The character you sought will be highlighted in the Character T able. able . Double-click this highlighted character to place it in the T ext to copy field copy field and then click the Copy button. Now switch back to your document and choose Edit → Paste from the gedit menu bar.

The above text includes application names; system-wide menu names and items; application-specific menu names; and buttons and text found within a GUI interface, all presented in proportional bold and all distinguishable by context. Mono-s Mono-spac paced ed Bold Bold Ital Italic ic or or Proportional Bold Italic Whether mono-spaced bold or proportional bold, the addition of italics indicates replaceable or variable text. Italics denotes text you do not input literally or displayed text that changes depending on circumstance. For example: T o connect to a remote machine machine using ss h, type type ssh username@ username@ domain.name at domain.name at a shell prompt. IfIf the remote machine is example.com and your username on that machine is john, type ssh ssh j ohn@ exam exam ple.com . The m ount -o rem ount file-system command file-system command remounts the named file system. For example, to remount the t he /home file /home file system, the command is m ount -o remo unt /home . T o see the vers ion of a currently installed installed package, use the rpm -q pac -q packag kage e command. It will return a r esult es ult as follows: packag package-v e-vers ersion ion-re -relea lease se.. Note the words in bold italics above: username, domain.name, file-system, package, version and release. Each word is a placeholder, either for text you enter when issuing a command or for text displayed by the system. Aside from standard usage for pres enting the title title of a work, italics italics denotes the first us e of a new and important ter m. For example: Publican is a DocBook publishing publishing sys tem. tem.

1.2. Pull-quote Conventions T erminal erminal output and source code listings are s et off visually from the surrounding text. Output sent to a terminal is s et in mono-spaced roman and roman and presented thus: books boo ks books boo ks_tests _tests

Desk De sktop top Desktop1

docume doc ument ntat ation ion downloads do wnloads

drafts im ages

m ss notes

photos scripts scrip ts

stuff stuff svgs

svn

Source-code Source-code listings are als o set in mono-spaced roman but roman but add s yntax highlightin highlighting g as follows: follows:

6

Preface

package org.jboss org.jboss. .book book. .jca jca. .ex1 ex1; ; import javax.na javax.nam m ing.InitialCo ing.InitialCont ntext; ext; public class class ExClient ExClient { public static void main main(String (String args[]) throws Exception throws Exception { InitialCo InitialCont ntext ext iniCtx = new new InitialContext(); InitialContext(); Object ref = iniCtx.lookup iniCtx.lookup( ("EchoBean" "EchoBean"); ); EchoHome home = (EchoHom (EchoHom e) ref; Echo echo = home.create home.create() (); ;

System.out System.out. .println println( ("Created Echo"); Echo");

System.out System.out. .println println( ("Echo.echo( "Echo.echo('Hello') 'Hello') = " + echo.echo echo.echo( ("Hello" "Hello") )); }

}

1.3. Notes and Warnings Finally, we use three visual styles to draw attention to information that might otherwise be overlooked.

Note Notes are tips , shortcuts or alternative alternative approaches to the tas k at hand. Ignoring Ignoring a note should have no negative consequences, but you might miss miss out on a trick that makes makes your life easier.

Important Important mportant boxes detail things that are easily miss miss ed: configuratio configuration n changes that only apply to the current s ess ion, or s ervices that need restarting before an update will apply. apply. Ignoring Ignoring a box labeled “Im “Important” will not cause data los s but may cause irritation and frustr ation.

Warning Warnings Warnings should not be ignored. Ignoring warnings warnings will most most likely likely cause data loss .

2. Getting Help 2.1. Do You Need Help? If you experience difficulty with a procedure or other information described in this documentation, visit the Red Hat Customer Portal at http://access.redhat.com http://access.redhat.com where where you can: search or browse through a knowledgebase of technical support articles about Red Hat products submit a s upport case to Red Hat Global Support Services Services (GSS) access other product documentation documentation

7


You can also also acces s the OpenShift OpenShift web site at https://openshift.redhat.com/ to find blogs, FAQs, forums, and other s ources of information. information. Red Hat also hos ts a large number number of electronic maili mailing ng lists for discus sion of Red Hat s oftware and technology. You can find a list of publicly available mailing lists at https://www.redhat.com/mailman/listinfo https://www.redhat.com/mailman/listinfo.. Click Click the name name of any mailing mailing list to s ubscribe to that list or to access the list archives.

2.2. We Need Feedback! If you find a typographical or any other error in this manual, or if you have thought of a way to make this manual better, we would love to hear from you! Please submit a report in Bugzilla: Online . http://bugzilla.redhat.com/ against http://bugzilla.redhat.com/ against the product Openshift Online. When submitting a bug report, be sure to mention the manual's identifier: Docs User Guide If you have a sugges tion for improving improving the documentation, documentation, try to be as specific as poss ible when describing it. If you have found an error, please include the section number and some of the surrounding text so we can find it easily.

8

Chapter 1. Introduction

Chaptt er 1. Chap 1. Introducti Introduction on 1.1. Product Introduction OpenShift Online by Red Hat is a Platform as a Service (PaaS) that enables developers to build and deploy web applications. OpenShift Online provides a wide selection of programming languages and frameworks including Java, Ruby, and PHP. It also provides integrated developer tools to support the application life cycle, including Eclipse integration, JBoss Developer Studio, and Jenkins. OpenShift Online uses an open source ecos ystem to provide a platform for mobile mobile applications, applications, database database services, and more. OpenShift Online is built on Red Hat Enterprise Linux, which provides integrated application runtimes and libraries libraries and a s ecure and scalable multi-tena multi-tenant nt operating system for address ing the needs of enterprise-class applications. This document describes how to navigate and use an OpenShift Online environment. It provides information on overall architecture, common application management tasks, and basic troubleshooting. It is intended for developers and application administrators. administrators. Report a bug

1.2. Plat Platff orm Overview OpenShift Online enables you to create, deploy and manage applications online. It provides disk space, CPU resources, memory, network connectivity, and an Apache or JBoss server. For most types of applications, applications, OpenShift OpenShift Online creates a file s ystem layout that you can us e as a template template for building an application. OpenShift Online also generates a limited Domain NameSpace (DNS) so that your application application is access ible online. online. T he two main main functional units of OpenShift Online are the broker and cartridges . Broker

T he broker is respons ible for managing managing user logins, DNS, DNS, and application application state. Users interact with with the broker using the Management Console, command line interface tools, or a REST-based API. Cartridges

Cartridges provide the functionality functionality to run applications. applications. Numerous Numerous cartridges are currently available available to support languages such as Perl, PHP, PHP, and Ruby, Ruby, as well as many database database cartridges s uch as PostgreSQL Postg reSQL and MySQL. Syste m Resources and Applic Applicat at ion Containers

T he sys tem resources and s ecurity containers containers provided by the OpenShift OpenShift Online Online platform are gears and nodes. Gears provide a resource-constrained container where you can run one or more cartridges. They determine the amount of RAM and disk space available to a cartridge. OpenShift OpenShift Online currently provides provides three gear siz es: Small gears provide 512MB of RAM, 100MB of swap space, and 1GB of disk space Medium gears provide 1GB of RAM, 100MB of swap space, and 1GB of disk space Large gears provide 2GB of RAM, 100MB of swap space, and 1GB of disk space

9


By default, you can use up to three small gears (a total of 1.5GB of RAM and 3GB of disk space). OpenShift OpenShift Online can ass ign these three gears to a s ingle applicatio application n and its cartridges (Cron, MySQL MySQL,, etc.), etc.), use each gear for a s eparate application, application, or use the gears for s caling caling an application. Nodes enable res ource sharing s o that multiple multiple gears can run on a single physical or virtual machine. machine. This machine is referred to as a node host. Report a bug

10

Chap te terr 2. Getting Getting Started

Chapter 2. Getting Started 2.1. User Interfaces 2.1.1. Management Console T he OpenShift Online Online Management Management Console is a graphical interface interface access ed with a web browser at https://www.openshift.com/.. The management https://www.openshift.com/ management console is bes t suited s uited for: T he Managem Management ent Console is bes t suited for: Setting up, administering and managing accounts Launching new applications Managing and monitoring applications T he following following screens hot s hows the home page of the Managemen Managementt Console when you first log into your account. Each tab across the top navigation bar provides further functionality to help you manage your account, applications, and more.

Figure 2.1. Management Console

T he table below provides provides a brief description of the different pages and s ettings available available in the Management Console. P a ge

D e sc r ip t io n

Applications

View and manage your applications and cartridges. If you do not have any applications, you can create new applications from this page.

Settings

View and manage SSH keys, domains, and account authorizations.

Help

Access to KBase articles, community forums, tutorials, and other community resources . A wide wide variety of resources are available available for diagnosing and resolving iss ues with your account account or your applications. applications.

My Account

View and manage account information, including account upgrades. This page shows your account details, subscription plan, and your account

11


usage. Red Hat technical support is available from here if you are subs cribed to the upgraded plan. plan. Note that the Management Console currently provides limited functionality. Therefore, most of the instructions in this guide are for the client tools. However, However, tasks that can be performed in the Management Console will be highlighted accordingly in their respective sections. An OpenShift Online user account is required for creating and managing applications within a unique namespace. namespace. This guide ass umes umes a us er account is already set up and configured. Report a bug

2.1.2. 2.1. 2. Clien Clientt T ools The OpenShift Online CLI tools, or more commonly referred to as the client tools, are used to manage a cloud environment using a command line interface, and provide features that are not currently available in the Managem Management ent Console. The client tools are bes t suited s uited for: Coding Debugging Advanced application management For example, although you can create an application using the Management Console, the application must be cloned to your workstation to make any code changes, and then redeployed to the remote server us ing the client client tools. T his guide as sumes the client tools are already installed and configured. See the OpenShift OpenShift Online Client Tools Installation Guide for ins tructions on how to install and configure the client tools. tools. For a full list of client tool commands, run rhc --help. --help . Report a bug

2.2. Basic Administration You can manage your account using either the Management Console or client tools. Report a bug

2.2.1. Management Console T he OpenShift Online Online Management Management Console is used for most account administrative administrative tas ks, with some of the more common tasks described below. Changing a Password

Navigate to the My Acco Acco unt page, unt page, and click Chang e your settings settings to to change your password. Mana ging Subscription Subscription Plans

Navigate to the My Acco Acco unt page, unt page, and click Plan Details to Details to view your current plan, and to view the available available upgrade and downgrade options . Account Acc ount Help and T echnical Support

T here are two types of help and support available based based on the type of s ubscription plan.

12

Chap te terr 2. Getting Getting Started

Silver Plan

Navigate to the My Acco Acco unt page, unt page, and click Account Help to Help to access the help page. If the problem is not addres sed in the frequently asked questions list, submit submit your account-related questions using the Submi t a quest question ion re gardi ng your account box. account box. For technical support, visit the Red Hat Customer Portal at https://access.redhat.com/support/offerings/openshift/.. You can also go to the OpenShift Online https://access.redhat.com/support/offerings/openshift/ Forum at https://www.openshift.com/forums/openshift or log on to IRC on Freenode (#openshift) for support.

Note You are prompted to accept the terms and conditions when acces sing Red Hat Customer Portal for the first time.

Free Plan

Click Help to information about how to get started Help to access the help page. T his page gives out information with OpenShift Online, explore the OpenShift Online platform, plat form, basic bas ic troubles hooting, and getting involved with the OpenShift Online community. T ype in a keyword in the Search the forums box forums box to access the Knowledge Knowledge Base for known iss ues and general questions. You can also go to the OpenShift Online Online Forum at https://www.openshift.com/forums/openshift or log on to IRC on Freenode (#openshift) for support.

Report a bug

2.2.2. 2.2. 2. Clien Clientt T ools Although using the OpenShift Online Management Console for account administration is recommended, the following following tasks can be performed using the client tools. tools. Viewing Vi ewing Account Account D et ails

Use the rhc account command account command to get an overview of the currently logged in user and their capabilities: $ rhc account Server: broker.example.com broker.example.com Login: dem o Gears Ge ars Used: 1 Gears Allowed: Allo wed: 100 Allowed Gear Sizes: small SSL Certificat Certifi cates es Supported: no

You can also view account details in the Management Console by navigating to the My Acco Acco unt page. unt page.

13


Note The rhc package rhc package found in the OpenShift Online client tools channel is based on the RHEL6 rpm version of the client tools, and not the Ruby gem version, which are updated more frequently. This leads to updated features being temporarily temporarily only available available in the Ruby gem version. version. T o ens ure you have the latest vers ion and all available available features, see the OpenShift Online Client Tools Installation Guide for the Ruby gem installation method.

Ending Endi ng the Current Sessio Session n

Use the rhc logout comm logout command and to end the current s ess ion with the OpenShift OpenShift Online Online server s erver and remove remove all local local ses sion files: $ rhc logout Ending session on server ... deleted All local sessions removed.

Report a bug

14

Chapter 3. Authorization Tokens

Chaptt er 3. Aut Chap Authorizat horization ion Tokens T okens 3.1. Authorization Tokens An authorization token is a secret s ecret value that is us ed with an OpenShift OpenShift Online account account without entering login informat information. ion. A token is also used to grant another user full or partial access access to your account depending on the token's scope . The table below describes the different types of s copes available with with authorization tokens. Ta ble 3.1. Authori Authorizat zat ion Token Scopes Scopes S co p e

D e s c r i p t io n

Va lid it y

s es s ion

Acces s to all API functions agains t an account.

1 day

read

Read-only ac acces s to to ac account re res ou ources , but ca cannot vi view authoriz at ation tokens.

1 month

us erinfo

Acces s to login name, unique id, and us er capabilities .

1 month

When the client tools tools are installed and the rhc setup setup command is initially run to configure the client tools, the setup wizard prompts you to create an authorization token. If If you ans wer YES, YES , the wizard creates a session token in the ~/.openshift directory. ~/.openshift directory. With this token, all client tool commands can be run without entering your login credentials each time. When the token expires the client tools automatically prompt you to renew the token by reentering your login information. See the Client Tools Installation Guide for more information on installing and configuring the client tools. If an authorization token was not created during the client client tools ins tallation tallation process , use the rhc setup setup comma command nd to run the s etup wizard again to create one. If an exis ting authorization token is no longer required and you do not wish to be prompted for token renewal, run the rhc logo ut command to delete the token. Management Conso Console le

Authorization tokens can be managed in the Management Console. Click Settings in Settings in the navigation bar to view a list of current authorization tokens for your account. From From this page you can add new tokens, edit current tokens, and delete tokens. Report a bug

3.2. Creating Authorization Tokens Run the rhc authorization authorization a dd command to create a new token. Specify the scope for the token with the --scopes option, --scopes option, and a name for the token with the --note option: --note option:

15


$ rhc authori authori zation add --scopes --scopes session --note session --note My_token My_token Adding authorization ... done My_token -------Token: Token: Scopes: Sco pes: Created: Expire Exp ires s In: In:

787a57211d42f2 787a57211d42f251204136b05d4900388 51204136b05d490038830d9b7057f5 30d9b7057f54f816c2a 4f816c2a9fcd0c833 9fcd0c8333b8 3b8 session session 4:40 PM about 1 day

After creating a new authorization token, use the --token token_string global token_string global option to run rhc rh c comma commands nds as the user ass ociated with with the authorization token you provide. Report a bug

3.3. Viewing Viewing Authorization Authorizat ion Tokens View the the tokens as sociated with your account using the rhc authori authori zation zation command: $ rhc authorizatio authorizatio n My_token -------Token: Token: Scopes: Sco pes: Created: Expire Exp ires s In: In:

787a57211d42f2 787a57211d42f251204136b05d4900388 51204136b05d490038830d9b7057f5 30d9b7057f54f816c2a 4f816c2a9fcd0c833 9fcd0c8333b8 3b8 session session 4:40 PM about 23 hours

RHC/1.8.0 RHC/1.8.0 (from laptop.exa laptop.exam m ple.com on x86_64-linu x86_64-li nux) x) --------------------------------------------------------------------------------------------------Token: Token: 28f6e375dc7ea57b0dca 8f6e375dc 7ea57b0dcabb3850d08 bb3850d08ee9bc023f7df5dbfa4958afe7a ee9bc023f7df5dbfa4958afe7ad71d33e37 d71d33e37 Scopes: Sco pes: session session Created: 12:58 12:58 PM Expire Exp ires s In: In: about 19 hours hours

Report a bug

3.4. Deleting Authorization Tokens Follow Follow the instructions below to delete authorization tokens when they are no longer required, or when you no longer wish wish to grant acces s to your account to other users. Delet e Specif Specific ic Authori Authorizat zat ion Tokens

Run the rhc a uthorization uthorization del ete command ete command to delete one or multiple tokens: $ rhc authorizatio authorizatio n delete token_1, token_2 Deleting authorization ... done

Delet e Al Alll Authorization Authorization Tokens

Run the rhc a uthorization uthorization del ete-all ete-all command to delete all the tokens associated with your account:

16

Chapter 3. Authorization Tokens

$ rhc authorizatio authorizatio n delete-all delete-all Deleting all authorizations ... done

Report a bug

17


Chapter 4. Domains 4.1. About Domains An OpenShift Online domain forms part of an application's application's URL and is unique to your account. The syntax for an application URL is applicationapplication-domain.example.com. domain.example.com. Each user name supports a single domain, but you can create multiple applications within the domain. Note that you must create a domain before you can create an application. OpenShift OpenShift Online uses a blacklist blacklist to res trict the domains domains available available to you. The blacklist blacklist is maintained maintained on the server. A mess mess age warns you that you have chosen a blacklisted blacklisted name and asks you to choos e a different domain if you try to create or alter a domain using a blacklisted name. Domains Domains cons ist of a maxim maximum of 16 alphanumeric alphanumeric characters and cannot have spaces or s ymbols. ymbols. Management Conso Console le

Click Settings in Settings in the navigation bar to view domain management options and manage domains in the Management Console. Report a bug

4.2. Creating a Domain Run the rhc dom ain create command create command to create a new domain: $ rhc domain create automobile Creating domain 'automobile' You may now create an application using the 'rhc app create' command

This command will create the domain automobile. automobile.

Note Silver Plan users can create multiple domains. You are unable to create more domains than your account limit (Silver plan users can use up to 16 gears at any time). You will receive a message when you try tr y to go beyond be yond the allowed a llowed limitations limitations of your account.

Report a bug

4 .3. Listin List ing g Available Av ailable Domain Domains s Run the rhc dom ain list list command to see all available domains.

18

Chapter 4. Domains

$ rhc domain domain l ist Domain automobile --------------Created: Oct 01 7:28 7:28 PM Allowed Gear Gear Sizes: small, m edium Dom ain automobile2 automobile2 ----------------Created: Oct 01 7:46 PM Allowed Gear Gear Sizes: small, m edium

Alternatively, run the rhc domains command domains command to list all available domains. Report a bug

4 .4. Viewing Viewing a Dom Domain ain Run the rhc dom ain show show command command to view information about a domain. $ rhc domain show Domain automobile --------------Created: Oct 01 7:28 7:28 PM Allowed Gear Gear Sizes: small, m edium racer @ http: http://racer //racer-au -automo tomobile bile.example .example.com .com/ / (uuid: (uuid: 926056f8845b4e388b37f6735c89d0eb) ----------------------------------------------------------------------------Dom ain: ain: automo automobile bile Created: Oct 01 7:28 7:28 PM Gears: Ge ars: 2 (defaults to small) small ) Git URL: ssh: ssh://926056f8845b4e388 //926056f8845b4e388b37f6735c8 b37f6735c89d0eb@ 9d0eb@ racerautomobile.example.com automobile.example.com/~/git/ra /~/git/racer.git cer.git/ / SSH: 926056f8845b4e388b37f6735c89d0 926056f8845b4e388b3 7f6735c89d0eb@ eb@ racer-aut racer-autom omobile.exa obile.exam m ple.com

php-5.3 (PHP 5.3) ----------------Scaling: x2 (minim um: 2, m aximum: axim um: 2) on small gears

You have have 1 application in your dom ain. ain.

If you have multiple domains, you can specify which domain you would like to view by adding the -n (namespace) option, followed by the name of the domain you would like to view. $ rhc domain show -n automobile

Report a bug

4.5. Renaming a Domain Because renaming a domain deletes the old domain and creates a new one, you must first ensure the domain to be renamed does not contain any applications. When the domain is empty, run the rhc domain rename command rename command to alter it.

19


Procedure Procedure 4 .1. To Rename Rename a Domain Domain

1. Ensure Ensur e the domain does not contain any applications . $ rhc apps No applications. Use 'rhc app create'.

If any applications applications are listed, use the rhc app del ete comm ete command and to t o remove them. t hem. $ rhc app delete App_Name delete App_Name

Warning Application removal is not reversible. All remote data associated with the application is deleted and cannot be recovered.

2. Use the rhc domain rename command rename command to alter the domain. $ rhc domain rename Old_Domain_Name New_Domain_Name Password: ******* Renaming domain 'Old_Domain_Name' to 'New_Domain_Name'... done Applications in this domain will use the new name in their URL.

Report a bug

4.6. Deleting a Domain If a particular domain is no longer needed, run the rhc dom ain delete comm delete command and to delete it. Before you can delete a domain, you need to ensure it does not contain any applications. Procedure Procedure 4 .2. To Delete a Domain

1. Ensure Ensur e the domain does not contain any applications . $ rhc domain show Domain_Name

If any applications applications are listed, use the rhc app del ete comm and to t o remove them. t hem. ete command $ rhc app delete App_Name delete App_Name

Warning Application removal is not reversible. All remote data associated with the application is deleted and cannot be recovered.

2. Use the rhc dom ain delete command delete command to delete the domain.

20

Chapter 4. Domains

$ rhc domain delete Domain_Name Deleting domain 'Domain_Name' ... deleted

After you delete a domain, you must create a new one before creating any new applications. Report a bug

4.7. Custom Domains and SSL Certificates OpenShift OpenShift Online enables you to designate cus tom domain domain aliases for applications applications to us e your own DNS entries ins tead of us ing the domain domain generated for you by the s ystem. For the alias to work correctly, ensure you have a CNAME record with your DNS provider. For added security, you can use custom SSL certificates with domain aliases. Note that custom SSL certificates certificates are only available available to us ers with upgraded OpenShift OpenShift Online accounts. accounts. Management Conso Console le

Click on an application name in the My Applic Applic ations tab ations tab in the Management Console to view custom domain name and SSL certificate management options for the selected application. Report a bug

4 .7. .7.1. 1. Using Cust Cust om Domain Names Names Adding a Custom Domain Name

Add domain domain name name aliases to applications applications using the rhc alias add App add App_Na _Name me Ali Alias as command: command: $ rhc alias add racer fast.cars.com RESULT: Alias Ali as 'fast. 'fast.cars.com cars.com ' has has been be en added. added .

Viewing Custom Domain Names

View domain name aliases and SSL Certificate status using the rhc a lias list App list App_Na _Name me command: $ rhc ali ali as li st racer Alias Has Certificat Certific ate? e? Certificat Certifi cate e Added Adde d ------------- ---------------- --------------------------------fast. fast.cars. cars.com com yes 2013-08-05 2013-08 -05 quick.cars. quick.cars.com com no -

Removing a Custom Domain Name

Remove domain name aliases from applications using the rhc alias rem ove App ove App_Na _Name me Ali Alias as command:

21


$ rhc alias remove racer fast.cars.com RESULT: Alias 'fast.cars.com' has been removed.

Report a bug

4.7.2. Using Custom SSL Certificates Adding Addi ng a Custom SSL Cert ific ificat at e

Add a custom SSL certificate to an alias using the rhc al ias update-cert update-cert command. command. If the private key is encrypted, specify the pass phrase with the --passphrase option. --passphrase option. Cert_File --private$ rhc alias update-cert racer fast.cars.com --certificate Cert_File --privatekey Key_File RESULT: SSL certificate cer tificate successfully successfully added.

Viewi iewing ng Custom SSL Certificat Certificat e Sta tus

View domain name aliases and SSL Certificate status using the rhc a lias list App list App_Na _Name me command: $ rhc ali ali as li st racer Alias Has Certificat Certific ate? e? Certificat Certifi cate e Added Adde d ------------- ---------------- --------------------------------fast. fast.cars. cars.com com yes 2013-08-05 2013-08 -05 quick.cars. quick.cars.com com no -

Removing Remo ving a Custom SSL Cert ific ificat at e

Remove a custom SSL certificate from an alias using the rhc al ias delete-cert App delete-cert App_Na _Name me Ali Alias as command: $ rhc ali as delete-cert racer fast.cars.com This is a non-reversible action! Your SSL certificate will be permanently deleted from application 'racer'. Are you sure you want to delete the SSL certificate? (yes|no): yes RESULT: SSL certificate successfully deleted.

Report a bug

22

Chap ter 5. Members Members

Chapt er 5. Members Members 5.1. About Members Developer teams can work collaboratively on applications with domain memberships. There are three roles available in domain membership: View

Member has read-only access to view information about the domain and its applications and cannot make make any changes . Edit

Member can create, update, and delete all applications in the domain, and has Git and SSH access. Administer

Membe Memberr has access to all features, but cannot change allowed allowed gear sizes or edit the domain domain name.

Each member is given the edit role by default. Use the rhc mem ber add comm add command and with the th e --role option to change the role of a member, and specify the desired role to change to. Management Conso Console le

Click the Settings tab Settings tab in the Management Console to view a list of available domains and manage domain members. Click on the desired domain to view applications, members, gears and allowed gear sizes, and the add-on cartridges of an application. From here you can manage membership options, such as adding a member, and editing a member's role. Report a bug

5.2. Adding a Member Run the rhc member add command add command to add a member to a domain, specifying the user login and domain name: $ rhc member member add add lo [email protected] [email protected] -n automo bil e Adding 1 editor to domain ... done

T he default role for the new memb member er is edit. edit. To update the role of the member, run the command with the --role option, --role option, followed by either view, view, edit, edit, or admin depending admin depending on the desired role. Report a bug

5.3. Listing Members Run the rhc mem ber list list command to list the existing members of a domain. You can specify the desired domain name with the -n option, -n option, or the desired application with the -a option. -a option.

23


$ rhc membe member r li st automo automo bil e Login Role ----------------------------------------------- [email protected] login@exam ple.com admin (owner) (owner) [email protected] view [email protected] edit [email protected] admin

T he existing members members and their roles are displayed. Report a bug

5.4. Removing a Member Run the rhc mem ber remove remove command command to remove an exis ting member from a domain. $ rhc membe member r remove remove -n automo automo bil e lo gin4 @example.com Removing 1 member from domain ... done

Use the rhc mem ber remove remove command command with the t he --all option --all option to remove all existing members from a domain. Note that this command does not remove the owner. Report a bug

24

Chapter 6. Applica Applica tions an d Cartridges

Chapter 6. Applications and Cartridges 6.1. About Applications When an OpenShift Online application is created, a domain-namespace name that is a combination of the application name and the domain name is registered in DNS. A copy of the application code is checked out locally in a folder with the same name as the application created. OpenShift Online runs the components components of the application application on small virtual virtual servers , referred referred to as " gears" . T he table below des cribes each component component that makes up an OpenShift Online application. application. Table 6.1. Application Components C o mpon e nt


Domain

T he he domain provides a unique group identifier for all the applications of a specific user. The domain is not directly related to DNS; instead, it is appended to the application name to form a final application URL of the form http://[APP_NAME]-[DOMAIN].example.com http://[APP_NAME]-[DOMAIN].example.com

Appl pplicati cation on Name ame

The nam name e of of the the appl appliicati cation on is selec selecte ted d by by a user. user. The fifinal nal UR URL to acc access the application is of the form http:// [APP_NAME]-[DOMAIN].example.com

Alias

DNS names ca can be provided for the application by regis tering an alias with OpenShift Online and pointing the DNS entry to the OpenShift Online servers.

Git re reposit sitory

Used sed to to mo modify ap application co code lo locally. Once th the co code is is app applied, the git push command push command is run to deploy the revised code.

OpenShift Online provides dedicated /var/tmp and /var/tmp and /tmp directories /tmp directories for each us er application. application. The /var/tmp directory /var/tmp directory is a symbolic link to /tmp. /tmp . Each /tmp directory /tmp directory is completely isolated from the /tmp directories /tmp directories of all other applications. applications. OpenShift OpenShift Online deletes deletes files in thes e directories that are untouched for any 10-day period. Report a bug

6.1.1. About Scal Scaled ed Applicat Applicat ions Application scaling enables the automatic allocation of resources based on demand. OpenShift Online monitors monitors the res ource requirements requirements of scaled applications, applications, and increases or decreases available available resources accordingly. accordingly. An An application application must be defined as s caled or non-scaled at the time time of creation. A scaled application cannot be converted to a non-scaled application. Likewise, a non-scaled application cannot be converted to a s caled application. application. Report a bug 6.1 .1.1. How Scaling Works

Each application application created on OpenShift OpenShift Online always always has the web cartridge ass ociated with with it. The web cartridge can, for example, be a PHP cartridge. When an application is scaled, a second cartridge, called HAProxy, is added to the application. The HAProxy cartridge listens to all incoming web page requests for an application and pass es them on to the web cartridge, followi following ng defined guidelines guidelines for load monitoring. As the number of web page requests to an application increase, the HAProxy will inform OpenShift Online when an overload of requests is detected. OpenShift OpenShift Online will will then create a copy of the existing

25


web cartridge on a s eparate gear. In In such s uch a cas e, the web cartridge now has been s caled up two times . T his proces s is repeated as more web page requests requests are detected by the HAProxy HAProxy cartridge, cartridge, and each time time a copy of the web cartridge is created on a separate gear, the application application scale factor increases by one. If an application's ratio of total number of gears to HAProxy gears is ever greater than two, the HAProxy cartridges' routing function is dis abled to the web cartridges collocated collocated on their gear. This allows allows full gear res ource usage for the HAProxy HAProxy cartridges, which which continue continue routing requests to other gears ' web cartridges. If If the ratio returns to two or below, below, routing to the HAProxy HAProxy gears' web cartridges is reenabled.

Figure 6.1. Cartridges on Gears in a Scaling Application

Report a bug

6.1.2. About Non-Scaled Applic Applicat at ions When a non-scaled application application is created, it only only consumes one of the default quota of gears as signed to users . That is , itit only consumes one of the available three gears. On the other hand, a scaled application consumes two of the available gears; one for the high-availability proxy (HAProxy) itself, and one for the actual application. When MySQL is added to an application, it is installed in its own dedicated gear. Report a bug

6.1.3. Viewing Accessible Applications Run the rhc apps command apps command to display information about all the applications you have access to: $ rhc apps racer @ http://racer-automobile.example.com/ (uuid: 926056f8845b4e388b37f6735c89d0eb) -------------------------------------------------------------------------------------------------------------------------------------------------------------Dom ain: ain: automo automobile bile Created: Dec 19 10:20 PM Gears: 1 (defaults to small) small ) Git G it URL: ssh: ssh://926056f8845b4e388 //926056f8845b4e388b37f6735c8 b37f6735c89d0eb@ 9d0eb@ racerautomobile.example.com automobile.example.com/~/git/ra /~/git/racer.git cer.git/ / SSH: 926056f8845b4e388b37f6735c89d0 926056f8845b4e388b3 7f6735c89d0eb@ eb@ racer-aut racer-autom omobile.exa obile.exam m ple.com Deploy Dep loym m ent: auto auto (on git push) push) php-5.3 (PHP 5.3) ----------------Gears: 1 small

26


Report a bug

6.2. About About Cartridges Cartridges are the components components of an OpenShift OpenShift Online application. application. They include include databases , build build systems, and have management capabilities. Adding a cartridge to an application provides the desired capability without having to administer or update the included feature. T o view a list of available available cartridges, run the rhc car tridge l ist command. ist command. Report a bug

6.2.1. Web Cartridges Every OpenShift OpenShift Online application application created must have one web cartridge to serve web requests . Web cartridges can only be added to new applications and are available for a variety of programming languages and frameworks. Run the rhc cartridge list command list command to view the current list of available web cartridges. Currently, there are a number of web cartridges available for OpenShift Online. Scalable Web Cartridges

JBoss AS JBoss EAP Node.js Perl PHP Python Ruby T omcat omcat (JBoss EW EWS) S) Non-Scalable Non-Scalable Web Ca rtridges

Zend Server Jenkins Server Do-It-Yourself (DIY) Report a bug

6.2.2. Add-on Cartridges After an OpenShift Online application is created with the required web cartridge, a number of other cartridges can be added that provide capabilities capabilities s uch as databases , scheduled jobs, jobs, or continuous integration. integration. The table below describes the functionality functionality of the different types of add-on cartridges available with OpenShift Online.

27


Ta ble 6.2. Add-on Cartridge Functions Functions F u n c t io n


Databas e

Provide the application with one of s ev everal databas e back ends . Examples include MySQL and PostgreSQL. Postg reSQL.

Database Database manage managem ment

Provid Provide e functional functionality ity for manag managing ing the appli applicati cation's on's database using thirdparty software. Examples include HAProxy.

Monitoring and Management

Provide a range of options for managing and monitoring the application. Examples include the Cron task scheduler, and the Jenkins Client.

Run the rhc cartridge list command list command to view the current list of available add-on cartridges. Currently, the following add-on cartridges are available: Data base Cartridges Cartridges Scalable Scalable Dat abase Cartridges Cartridges MySQL database is a multi-user, multi-user, multi-threaded multi-threaded SQL database s erver. MongoDB NoSQL databas e is a s calable, calable, high-performan high-performance, ce, open source NoSQL database.

object-relational database management management s ystem. PostgreSQL 8 database is an advanced object-relational Management Cartridges Scalable Management Cartridges phpMyAdmin 3 is a web-based MySQL administration tool. HAProxy HAProxy 1 is a high performance TCP/HTT P load balancer. balancer. Cron 1 is a daemon that runs s pecified pecified programs at s cheduled times. times. SwitchYard 0 is a lightweight service delivery framework providing full lifecycle support for developing, deploying, and managing service-oriented applications. Non-Scalable Non-Scalable Manage ment Cart ridges ridges RockMongo 1 is a web-based MongoDB administration tool. Jenkins Client Client 1 is a client for managing Jenkins-enabled Jenkins-enabled applications. OpenShift Met rics rics 0 is an experimental cartridge for monitoring applications.

Report a bug

6.2.3. Downloadable Cartridges In addition to the supported standard cartridges available in OpenShift Online, downloadable cartridges can also be deployed into new or existing applications. applications. Downloadable Downloadable cartridges cartridges can be cus tom cartridges created by a user or community cartridges found in the OpenShift community. By providing the URL to the hosted downloadable cartridge's manifest in the Management Console or client tools, OpenShift Online will download and install the cartridge to the application. Usage s teps for downloadable downloadable cartridges cartridges are provided in Section 6.3, “Creating an Application” . See https://www.openshift.com/developers/download-cartridges for more community tips and solutions surrounding downloadable cartridges. Report a bug

28


6.3. Creating an Application Before creating an application, application, there are certain options to be cons idered. T hese options include whether you wish to t o enable s caling and the type of web cartridge. For example, you will not be able to enable scaling or change the type of web cartridge after an application application is created. Management Conso Console le

Click on the Applications tab Applications tab in the Management Console to show a list of your applications, and create new applications. From there, click on the Add Application button to start creating an application. If you have no applications, you will automatically be directed to the Create an Application page. After creating an application with the Management Console, run the rhc git-clone comm git-clone command and to copy the application's remote repository into a local working directory. $ rhc git-clone App_Name git-clone App_Name Cloning int i nto o 'App_Name'. 'App_Nam e'... .. Your application Git repository has been cloned to '/home/apps/App_Name'

The rhc git-clone command git-clone command copies the template application files from the remote repository into the working director y. Edit Edit the template application files to suit s uit the application. ap plication. Client Cli ent Tools

When creating applications with the client tools, the rhc app cr eate command eate command creates a new application application by populating populating a remote Git repos itory with the selected cartridge and clones the repository to the current directory on the local machine. machine. The command command also adds the hos t name and IP IP address of the application application to the list of known hosts ( ~/.ssh/known_hosts ~/.ssh/known_hosts). ). The rhc app cre ate comm ate command and can be us ed with several optional parameters parameters that customize the configuration configuration of an application application when it is created. Note that s ome ome of thes e options, such as ability ability to select larger gear s izes for the cartridges, are only available available to users with upgraded plans. plans. See rhc app cr eate --help --help for a complete list list of options. Prerequisites

Application creation requires a reliable network connection. The rhc app c reate command reate command only makes makes a s ingle attempt attempt to create an application. application. OpenShift OpenShift Online makes makes up to s even checks for the DNS entry entry to exist, and returns a failure mess mess age if not found. The --timeout option --timeout option on the command command line is us ed to override the default values when there are constant timeout iss ues. OpenShift Online Online us es two timeout timeout parameters: a connection timeout, which determines how long the client tries to connect to the server before timing out; and a read timeout, timeout, which determines determines how long the client client waits for a res ponse from the server. T he default connection connection timeout timeout value is 20 seconds. The default read timeout value is 120 seconds. The --timeout option --timeout option affects both timeout parameters, parameters, but it can only be used to increas e values from the default. The timeout value cannot be set to be less than the default. For example, if --tim --tim eout 50 is us ed, itit sets s ets the connection connection timeout timeout value to 50 seconds , but does not affect the read timeout value. value. Similarly, if --timeout 150 is 150 is used, it sets both the connection and read timeout timeout values to 150 seconds. Report a bug

29


6.3.1. Creating Scaled Applications Scaled applications automatically allocate resources based on demand. Use the rhc app cr eate command command with the -s (or -s (or --scaling) --scaling ) option to create a scaled application. See Section 6.1.1, “About Scaled Applications” for Applications” for more information. Note that if a cartridge type is specified with multiple versions, the client tools prompt to specify the version to use. The following command will create a scaled application named hybrid. hybrid . $ rhc app create hybrid php-5.3 php-5.3 -s Application Options ------------------ Namespace: automobile Cartridges: php-5.3 Gear Size: Size : default Scaling: yes Creating application 'hybrid' ... done Waiting for your DNS name to be available ... done Cloning into 'hybrid' ... The authenticity of host 'hybrid-automobile.example.com (21.20.161.211)' can't be established. RSA key fingerprint fingerp rint is cf:eb:77:cb: c f:eb:77:cb:0b:fc:02: 0b:fc:02:d7:72: d7:72:7b:ab: 7b:ab:80:c0:90:88:b7. 80:c0:90:88:b7. Are you sure you want to continue connecting (yes/no)? yes Warning: Warning: Perm anent anently ly added 'hybrid-au 'hybrid- automo tomobile bile.exampl .example.com e.com ,21.20.161.2 ,21.20.161.211' 11' (RSA) to the list of known hosts. Your application 'hybrid' is now available. URL: ssh://[email protected] automobile.example.com/~/git/h /~/git/hybrid.git ybrid.git/ / SSH to: fjoe04cabdc4efa8f2513a21e2ed27d@hybr fjoe04c abdc4efa8f2513a21e2ed27d@hybrid-aut id-autom om obile.exampl obil e.example.com e.com Git remote: ssh://[email protected] automobile.example.com/~/git/h /~/git/hybrid.git ybrid.git/ / Cloned to: /home/Us /home/U ser/hybrid Run 'rhc show-app hybrid' for more details about your app.

When a scaled application is created, the automatic scaling feature is enabled by default. However, an application application can be manually manually scaled to control the number number of gears being used. If you have more than one domain, specify the domain in which you wish to create the application by using the -n (namespace) -n (namespace) option: $ rhc app create hybrid php php -n Domain_Name

Report a bug

6.3.2. 6.3. 2. Creat Cre at in ing g Single-Inst Single-Instance ance Appl Applic icat at ions The following example demonstrates the creation of a non-scaled PHP application called racer. racer . Note that if a cartridge type is specified with multipl multiple e vers ions, the client client tools prompts prompts to specify s pecify the version to use.

30


$ rhc app create racer php-5.3 Application Options ------------------Dom ain automo automobile bile Cartridges: php-5.3 Gear Size: Size : default Scaling: Scali ng: no Creating application 'racer' ... done Waiting for your DNS name to be available ... done Cloning into 'racer' ... The The authent authentici icity ty of host 'racer-au 'racer- autom tomobi obile.ex le.examp ample.co le.com m (21.26.2 (21.26.220.40)' 20.40)' can't can't be established. RSA key fingerprint fingerp rint is bf:eb:77:cb:0b:fc:02 bf:eb:77:cb:0b:fc:02:b7:72 :b7:72:7e:a :7e:ab:80:c0:90:88: b:80:c0:90:88:a7. a7. Are you sure you want to continue connecting (yes/no)? yes Warning: Warning: Perm Pe rm anent anently ly added 'racer'racer-au automo tomobile bile.example .example.com .com,21.2 ,21.26.2 6.220. 20.40' 40' (RSA) to the the list of known hosts. Your application 'racer' is now available. URL: ssh://[email protected] automobile.example.com/~/git/ra /~/git/racer.git cer.git/ / SSH to: 516cd60e4382ecb972 516cd60e43 82ecb972000006@ 000006@ racer-aut racer-autom omobile.exa obile.exam m ple.com Git rem ote: ssh ssh://516cd60e4382ecb972000006@ ://[email protected] automobile.example.com/~/git/ra /~/git/racer.git cer.git/ / Cloned to: /home/User/racer Run 'rhc 'rhc show-app show-app racer' for m ore details about about your app.

If you have more than one domain, you can specify the domain in which you would like to create the application, by specifying the domain with the -n (namespace) -n (namespace) option: $ rhc app create racer php-5.3 -n automobile

As mentioned in Section 4.2, “Creating a Domain” , each domain can support multiple applications. By running rhc app c reate hybrid hybrid php , for example, another application can be created in the domain automobile. automobile. The application application URLs URLs would appear as follows: http://racer-automobile.example.com http://hybrid-automobile.example.com Creating an Application Using a Downloadable Cartridge

Provide the URL of the hosted cartridge's manifest in place of the cartridge type to create an application using a downloadable cartridge: $ rhc app create [App_Name] https://www.example.com/manifest.yml

Creating an Empty Application

OpenShift OpenShift Online can be us ed to create applications of no specific type, for build build or other tes ting purposes , using the DIY DIY cartridge: $ rhc app create [App_Name] di [App_Name] di y

31


T he DIY DIY cartridge creates an application application that is not publicly publicly available available nor does it have anything running. Use git push and push and a .openshift/action_hooks/ script s cript to start the application. application. Report a bug

6.3.3.. Manuall 6.3.3 Manua lly y Scaling an Applicat Applicat ion T he following following are cas es where a s caled application application must must be manually manually scaled: If a certain load is anticipated on an application and it must be scaled accordingly. There are a fixed set of resources for an application. T he cost must must be controlled manually manually.. Procedure 6.1. To Scale an Application Manually

1. Run rhc app show to show to view the cartridges in the scaled application. Locate the cartridges that are indicated as scaling. In the following example, the php-5.3 cartridge is scaling: $ rhc app show hybrid hybrid @ http://hybrid-automobile.example.com/ (uuid: fjoe04cabdc4efa8f2513a21e2ed27d) ------------------------------------------------------------------------------------------------------------------------------------------------Dom ain: ain: automo automobile bile Created: 11:48 AM Gears: 1 (defaults to small) small ) Git URL: ssh: ssh://fjoe04 //fjoe04cabdc4ef cabdc4efa8f2513a2 a8f2513a21e2ed27d@ 1e2ed27d@ hybridautomobile.example.com automobile.example.com/~/git/h /~/git/hybrid.git ybrid.git/ / SSH: fjoe04cabdc4efa8f2513a21e2ed27d@hybr fjoe04c abdc4efa8f2513a21e2ed27d@hybrid-aut id-autom omobil obile.exampl e.example.com e.com Deploy Dep loym m ent: auto auto (on git push) push) php-5.3 (PHP 5.3) ----------------Scaling: x1 (minim um: 1, m aximum: axim um: available) available) on small gears haprox haproxy-1.4 y-1.4 (OpenShift (OpenShift Web Balan Balancer) cer) -----------------------------------Gears: Ge ars: Located with php-5.3 php-5 .3

2. For each scaling cartridge, run rhc cartridge scale comm and to set se t the minimum minimum and scale command maxim maximum um gears the cartridge can us e for scaling: $ rhc cartridge scale php -a hybrid --min 1 --max 10 Setting scale range for php ... done php-5.3 (PHP 5.3) ----------------Scaling: Scaling: x1 (m (m inimum: 1, maximum: 10) on small gears gears

3. Set the minimum minimum and maximum gears gear s to 1 using the rhc cartridge scale command scale command to stop a cartridge from scaling:

32


$ rhc cartridge scale php -a hybrid --min 1 --max 1 Setting scale range for php-5.3 ... done php-5.3 (PHP 5.3) ----------------Scaling: Scaling: x1 (m (m inimum: 1, maximum: 1) on small gears

Report a bug

6.4. Adding and Managing Cartridges OpenShift OpenShift Online supports a wide range of add-on cartridges . The OpenShift OpenShift Online Client Client T ools provide a range of commands for managing cartridges. View the cartridges cartridges ass ociated with with your applications applications by running the rhc apps comm apps command. and. Use the rhc app show App show AppNam Name e command to view information about an individual application. Installed cartridges are listed under the Cartridge heading. Cartridge heading.

Note An error mess mess age is displayed if any rhc rh c command command is us ed and the us age exceeds the node's disk quota limit. Warning Warning gear #{uuid} is using #{usage pct} of disk quota Warning Warning gear #{uuid} is using #{usage pct} of inodes allowed

Management Conso Console le

Click on the Applications tab Applications tab in the Management Console, then click on the desired application to add cartridges to your application. Note that some add-on cartridges are only available with the required web cartridge. cartridge . The available add-on cartridges are dis played under your application. Report a bug

6.4.1. 6.4 .1. Addi Adding ng Cart ridg ridges es Use the rhc cartridge list command list command to view the current list of available cartridges. This command lists all available available cartridges, provides provides a brief des cription cription of each cartridge, and labels each cartridge as a web cartridge or add-on add- on cartridge. cartr idge. Mos Mostt add-on cartridges can only be a dded after afte r a prerequis pre requis ite web cartridge is ins talled. talled. Procedure Procedure 6 .2. To Add a Ca rtridge Using Using the CLI

Run the following command, command, replacing Cart_Type and with the application name and the Cart_Type and App_Na App_Name me with desired cartridge: $ rhc cartridge add Cart_Type -a Cart_Type -a App_Name App_Name

Specifyin Specif ying g Cart rid ridge ge G ea r Size

Use the -g, -g, or --gear-size option --gear-size option with small, small , medium , or large when large when adding a cartridge to s pecify the gear s ize. Note that this option is not available to non-scaled applications, applications, as thes e run the web

33


cartridge and any add-on cartridge on the s ame ame gear. $ rhc cartridge add Cart_Name -a Cart_Name -a App_Name App_Name -g medium -g medium

This allows you to add an add-on cartridge on a medium gear to your application, which can be on a gear of any size.

Note Only silver plan users have access to medium medium and large large gears. Free plan users are limited limited to small gears. Use the My Account tab Account tab in the Management Console and follow the directions to upgrade your account to a silver plan. Report a bug

6.4.2. Managing Cartridges Different actions actions can be performed with the rhc cartridge command cartridge command using the following syntax: $ rhc cartridge Action Car t_Type -a App_Name -a App_Name

Ta ble 6.3. Cartridge Management Actions Actions Act ion

D e t a ils

lis t

Lis t s upported cartridges .

add

Add a cartridge.

remove

Remove a cartridge.

s top

Stop a cartridge.

s tart

Start a cartridge.

res tart

Res tart a cartridge.

s t a tu s

Return the current s tatus of a cartridge.

reload

Reload the configuration of a cartridge.

s h ow

Show information about a cartridge.

s torage

View and manipulate s torage on a cartridge.

s cale

Set the s caling range of a cartridge.

Report a bug 6.4.2.1. Cartridge Action Hooks

Action Action hooks are us ed to modify certain certain process es during an application's application's lifecycle. lifecycle. Cartridge action action hooks are specifically specifically used us ed to interact with cartridges. Each Each time OpenShift OpenShift Online invokes invokes one of thes e cartridge actions, the action hooks directory is checked for an executable file. Create a file in the [App_Name]/.openshift/action_hooks [App_Name]/.openshift/action_hooks directory with with the s ame ame name as the des ired event to use cartridge action hooks. Use the following list list for a reference to all poss ible action action hooks ass ociated with with a cartridge control action.

34


Ta ble 6.4 . Cart ridge ridge Action Action Hook Hooks s Act ion

D e scr ip t ion

E ve nt spe cific e xa mple s

Start

Start the s oftware the cartridge controls.

pre_start_ Cart-Name, Cart-Name, post_start_ Cart-Name Cart-Name

Stop

Stop the s oftware the cartridge controls.

pre_stop_ Cart-Name, Cart-Name, post_stop_ Cart-Name Cart-Name

Reload

T he cartridge and the package software will re-read the configuration information.

pre_reload_ Cart-Name, Cart-Name, post_reload_ Cart-Name Cart-Name

Res tart

Current cartridge proces s is stopped and started again.

pre_restart_ Cart-Name pre_restart_ Cart-Name,, post_restart_ Cart-Name Cart-Name

T idy

All unus ed res ources are released.

pre_tidy_ Cart-Name pre_tidy_ Cart-Name,, post_tidy_ Cart-Name Cart-Name

Cart_Name is Cart_Name is a replaceable term used to represent the cartridge short-name. For example, for a JBossAS cartridge to be implemented implemented during the pre-s tart proces s, create the file [App_Name]/.openshift/action_hooks/pre_start_jbossas [App_Name]/.openshift/action_hooks/pre_start_jbossas and and edit the file to contain the desired information. Report a bug

6.5. Deployment T he application application deployment deployment proces s involves involves making making any required changes to the application application code base, committing those changes to the local repository, and then updating the remote repository. Application Application files files are s tored in the local Git repository that was cloned as part of the application application creation process. T he deployment deployment process uses the application application space as part of the build and and test proces s, and requires the currently running application be shut down to use its memory. Therefore, the application will be unavailable unavailable for the duration of the build and all ass ociated tasks , which which are des cribed below: below: 1. Pre-receive Pre-receive - T his occurs when git p ush ush command is run, but before the push is fully committed. 2. Build Build - T his builds an application, application, downloads downloads required dependencies, dependencies, executes executes the .openshift/action_hooks/build s cript and prepares everything for deployment. deployment. 3. Deploy - T his performs any required tasks necess ary to prepare the applicati application on for starting, including running the .openshift/action_hooks/deploy .openshift/action_hooks/deploy script. script. This step occurs immediately before the application is issued a start command. start command. 4. Post-deploy - T his s tep enables interaction with with the running application, application, including including running the .openshift/action_hooks/post_deploy script. s cript. T his s tep occurs immediatel immediately y after the application application is res tarted. Report a bug

6.5.1. Build Build and Deployment Deployment Action Hooks Ho oks Action Action hooks are s pecific pecific files created to modify modify the process es of an application's life cycle. With specific action hooks, you can modify the build and deploy process . T he list of action hooks for build and deploymen deploymentt are:

35


pre-build build deploy post-deploy Create a new file in the [App_Name]/.openshift/action_hooks [App_Name]/.openshift/action_hooks directory to use the build and deployment action hooks. For example, to implement an action hook for use during the build phase, create the file [App_Name]/.openshift/action_hooks/build [App_Name]/.openshift/action_hooks/build , and edit the file to contain the desired information. Example 6.1 . Adding Adding an Action Hook Hook to t he B uild Process Process

T o download a file from another site during your application's application's build phase, create an [App_Name]/.openshift/action_hooks/build [App_Name]/.openshift/action_hooks/build file, then add the following to the file's contents: echo Downloading my.zip... curl -o $ OPENSHIFT OPENSHIFT_DATA_DIR/m _DATA_DIR/m y.zip http://myserver/my.zip

T he file is downloaded during the git push process. push process. Report a bug

6.5.2. Preparing an Applicat Application ion for fo r Depl De ploym oyment ent The rhc app cre ate comm ate command and creates a s tarting point to create and develop applications. applications. T o synchronize application files with the remote cloud repository, all files must be committed to the appropriate directories in the local Git repository, and then pushed to the remote repository. For example, for developing a PHP application and to add new files and directories to or other directories. $_ENV['OPENSHIFT_APP_NAME']/php/ or $_ENV['OPENSHIFT_APP_NAME']/php/ Procedure 6.3. To Pre pare an Applicat Applicat ion for for De ployment ployment Using Using the Command Command Line

1. Use the following command command to add each new file file and directory to the Git index: $ gi t add path/ path/to/newfile to/newfile

2. Use the following command command to commit commit an application to the local local repos itory: $ gi t commit -m "commi t message message" "

Report a bug

6.5.3. Deploying an Application After adding application files to the local repository, push them to the remote repository. By default, OpenShift Online automatically stops, builds, and restarts the application with the committed changes. Procedure 6.4 . Deploying an Appli Applicat cat ion to the Cloud Using Using the Command Command Line

Use the following command to deploy the application to the remote repository: $ git push

36


Report a bug

6.5.4. Configuring Application Deployment When the git pus p ush h command is run, the application data is sent to the remote repository and the application is deployed by default. However, using the rhc deploym deploym ent commands ent commands to configure the deployment deployment proces s provides more options during the application application deployment deployment s tage. Use the rhc configure-app commands to configure your application's deployment. Configuring Configuri ng Auto- deploy

Use the --no-auto-deploy --no-auto-deploy option option to configure your application to not deploy automatically when your data is added to the remote repository with with git push. push . $ rhc configure-app -a App_Name --no-auto-deploy

Note that in this case, when the git p ush ush command is run the application data is pushed to the remote repository, but the application is not deployed. If your application is set to --no-auto-deploy --no-auto-deploy then then both git pus p ush h and git deploy must deploy must be run. Change back to deploying automatically using the -auto-deploy option. auto-deploy option. Keeping Deploym Deployment ent Meta data

Use the --keep-deployment --keep-deployment x x option option to s et your application application to record its deployments. deployments. T his will help in performing a rollback to a previous deployment. Replace x Replace x with any number to record that number of with deployments in the application's history. Any older deployments after the set number will be deleted. $ rhc configure-app -a App_Name --keep-deployments 10

De ployi ploying ng From a G it Bra nch

Use the following command to choose the deployment branch to be from any branch of the Git repository. $ rhc configure-app -a App_Name deployment-branch deployment-branch master master

T his example comma command nd deploys the master branch. Other Other Git references are s upported, such as comm commit SHA, branch, or tag. Listing Previous Deployment Deployment s

Use the following command to view the list of previous deployments for an application, and the individual ID of each deployment. $ rhc deployments App_Name

Activating a Pre vious De ploym ployment ent

Roll back to a previously deployed version of your application with the rhc deployments command deployments command to obtain the desired deployment's ID, then run the following command: $ rhc activate-deployment deploy_ID -a deploy_ID -a App_Name App_Name

Report a bug

37


6.5 .4 .1. Deploying an Appli Applicat cat ion From From a Sna pshot

OpenShift Online supports deploying an application from a binary artifact. Use the --deployment option --deployment option when saving a s napshot of an application application to build a deployable deployable version of your application. $ rhc save-snapshot App_Name save-snapshot App_Name --deplo yment yment

Note See Chapter 10, 10 , Backing Up and Restoring Application Data for full information on saving shapshots.

T his command command saves a .tar.gz .tar.gz snaps hot of your application. application. Next, configure your application to binary deployments: $ rhc configure-app App_Name --deployment-type binary

T his command command changes your application's application's deployment deployment procedure and dis ables the git push command, push command, but enables your application application to deploy binary artifacts. artifacts. T he rhc deploy command deploy command can then be used to deploy your application. Use the following command to deploy a binary artifact: $ rhc deploy ./app.tar.gz -a App_Name

Alternatively, you can also deploy from a URL using the command: $ rhc deplo y http://foo http://foo .com/path/to/fil .com/path/to/fil e.tar.gz e.tar.gz -a App_Name

Report a bug

6.5.5. About Hot Deployment When the git pus p ush h command is run to upload code modifications, OpenShift Online stops, builds, deploys and restarts an application. application. T his entire process takes time to compl complete ete and is unnecess ary for many many types of code changes. Hot deploying deploying an application enables enables the changes to take effect without restarting the application cartridge, thus increasing deployment speed and minimizing application downtime. OpenShift OpenShift Online provides support for hot deployment deployment through a hot_deploy marker hot_deploy marker file. If the marker is present, s upported application application cartridges automatical automatically ly hot deploy when the git push command push command is executed.

38


Ta ble 6.5. Appli Application cation Types That Can or Cannot Be Hot Hot De ployed ployed T ype o f App lica t ion

Hot D e plo y

JBos s Application Server

Yes

JBos s Enterpris e Application Platform

Yes

Tom Tomcat 6 (JB (JBoss En Enterprise Web Serve rver 1.0)

Yes

Tom Tomcat 7 (JB (JBoss En Enterprise Web Serve rver 2.0)

Yes

PHP

Yes

Perl

Yes

Ruby

Yes

Python

Yes

Node.js

Yes

Z end Server

Yes

Jenkins

No

HAProxy

No

DIY

No

Report a bug 6.5.5.1. Hot De plo ploym yment ent Buil Build d De ta il ils s JBoss AS, AS, JBoss EAP, Tomcat 6, a nd Tomcat 7

When JBoss AS, JBoss EAP, Tomcat 6, and Tomcat 7 applications are hot deployed, the Maven build is executed (either with Jenkins or without), but the server does not restart. Following the build, the JBoss HDScanner notices any modifications and redeploys them. If previously deployed artifacts are removed as part of the update, they are undeployed automatically. PHP, Zend Se rver, Pe rl, Python, and Node.js

When PHP, Zend Server, Perl, Python, and Node.js applications are hot deployed, the application code is built (dependencies (dependencies are proces sed and user build action_hooks action_hooks are run) and deployed to the application application server. The server does not restart. This is true for both Jenkins and non-Jenkins enabled applications. For Jenkins Jenkins enabled applications, applications, the build build is performed performed on a Jenkins Jenkins slave instance and then s ynced to the gear(s) where the application application server is running. Ruby

When a Ruby application is hot deployed, the Passenger restart.txt file restart.txt file is touched, causing the application application server to s erve the new code without the need for a full server res tart. For For further details on this process, see the Pass Passenger enger Docum Documentation entation.. Report a bug 6.5 .5.2. Ena blin bling g and Disabling Hot Hot De ploym ployment ent Procedure Procedure 6.5. T o Enable Hot De ploym ployment ent

Open a terminal and run the command applicable to the operating system from the application's root directory to create the hot_deploy marker hot_deploy marker file: Windows

39


C:\app_directory> copy NUL > .o penshift\mark penshift\markers\h ers\hot_deplo ot_deplo y

Linux and Ma c [user@ [user@ user user app_directory]$ app_directory]$ touch .openshift/marker .openshift/markers/hot_dep s/hot_deplo lo y

Procedure 6.6. To Disable Hot Deployment

Hot deployment deployment is disabled by deleting the hot_deploy marker hot_deploy marker file. To delete this file, run the command applicable to the operating system from the application's root directory: Windows C:\app_directory> del .openshift\marker .openshift\markers\hot_dep s\hot_deplo lo y

Linux and Ma c [user@ [user@ user user app_directory]$ app_directory]$ rm .openshift/markers .openshift/markers/hot_deploy /hot_deploy

Report a bug

6.5.6. JBoss Application Deployment 6.5.6.1. De plo ployin ying g on Java 6 or Java 7

T he JBoss AS 7 and JBoss JBoss EA EAP P 6.0 6.0 applications applications can be run on either Java 6 or Java 7. The Java version is s pecified pecified by a java7 marker java7 marker file in the application's markers directory. markers directory. By default, new JBoss applications applications have the java7 marker java7 marker enabled. Applications without the java7 marker java7 marker are deployed using Java 6. Procedure Procedure 6 .7. To Use Use Java 7

Open a terminal and run the commands applicable to the operating system from the application's root directory to create the java7 marker java7 marker file and update the remote repository: Windows C:\app_directory> C:\app_directory> C:\app_directory> C:\app_directory>

copy NUL > .openshift\markers\java7 git add .openshift\markers\java7 git commit -a -m "Add Java 7 marker" git push

Linux and Ma c [user@ [user@ user user [user@ [user@ user user [user@ [user@ user user [user@ [user@ user user

app_directory]$ app_directory]$ app_directory]$ app_directory]$ app_directory]$ app_directory]$ app_directory]$ app_directory]$

touch .openshift/markers/java7 git add .openshift/markers/java7 git commit -a -m "Add Java 7 marker" git push

Procedure Procedure 6 .8. To Use Use Java 6

Java 6 is enabled by deleting deleting the java7 marker java7 marker file. Run the commands applicable to the operating sys tem from the the application's application's root directory to delete the java7 marker java7 marker file and update the remote repository:

40


Windows C:\app_directory> del .openshift\markers\java7 C:\app_directory> git co mmit -a -m "R emove Java 7 marker" marker" C:\app_directory> git push

Linux and Ma c [user@ [user@ user user app_directory]$ app_directory]$ rm .openshift/markers/java7 [user@ [user@ user user app_directory]$ app_directory]$ git co mmit -a -m "R emove Java 7 marker marker" " [user@ [user@ user user app_directory]$ app_directory]$ git push

Report a bug 6.5.6.2. Automatic Deployment

Applications are automatically deployed to the OpenShift Online server runtime by placing the deployment content , for example, .war, .war , .ear, .ear , .jar, .jar , and .sar files, .sar files, in the JBoss Application Server (AS) or JBoss Enterprise Application Platform (EAP) deployments/ directory. deployments/ directory. T he file sys tem deploym deployment ent s canner in JBoss JBoss AS 7 and JBoss EA EAP P 6.0 6.0 relies on a s ystem of marker marker files. Add Add or r emove emove various marker files and the s canner deploys, withdraws, withdraws, or redeploys content based on the type of marker marker file. These marker files always have the same name as the deployment content to which they relate, but with an additional file suffix to indicate the type of action to perform. For example, the marker file to indicate that the example.war file is to be deployed is named example.war.dodeploy . Opt ion 1: Upl Uploading oading Conte nt in a Mave n src Struct ure

Content can be uploaded in a Maven src structure similar to the example ROOT.war file. ROOT.war file. When a git push is push is performed, the application is built and deployed. This is the typical deployment option, and requires that the pom.xml be pom.xml be s tored at the root repository, and and that the sys tem has has a maven maven-war war plugin plugin similar similar to the one in the example file to move the output from the build to the deployments/ directory. By default, the warName is within the pom.xml file. warName is ROOT within pom.xml file. T his will render the webapp contents at http://app_name http://app_name--domain.exam domain.example.com ple.com.. If If the th e warName is changed in pom.xml to pom.xml to app_name, app_name , then the base URL would become http://app_name http:// app_name--domain.example.com/app_name. domain.example.com/app_name.

Important While building locally, add any output .war and .war and .ear files .ear files in the deployments/ directory deployments/ directory from the build to the .gitignore file. .gitignore file.

Opt ion 2: Upl Uploading oading Prebuilt Conte nt

git push can push can be used to pus h prebuilt .war files .war files (with the corres ponding .dodeploy file .dodeploy file for exploded .war files) .war files) into the deployments/ directory. deployments/ directory.

41


Important While While applying this method using the default repos itory, first run git rm -r src/ pom .xm .xm l from the root directory of the repository. If the pom.xml file pom.xml file still exists, the build will run again and replace any prebuilt content.

Report a bug 6.5.6.3. Types of Marker Files

Different marker marker file suffixes have different meanings. meanings. The relevant marker marker file types are as follows: follows: Ta ble 6.6. Sample Sample Table Marker File Type

Description

.dode dodepl ploy oy

Place laced d by by the the user to indi indica cate te that that the the giv given en cont conten entt is is to be depl deploy oyed ed into into the the runtime (or redeployed if already deployed in the runtime.)

.depl deploy oyin ing g

Place laced d by by the the depl deploy oym ment ent scan scanne nerr servi service ce to indi indica cate te that that it has has detec detecte ted da .dodeploy file .dodeploy file and is in the proces s of deploying deploying the content. This marker marker file is deleted when the deployment deployment process completes. completes.

.depl deploy oyed ed

Place laced d by by the the depl deploy oym ment ent scan scanne nerr servi service ce to indi indica cate te that that the the giv given en cont conten entt has has been deployed to the runtime. If this file is deleted, the content will be withdrawn.

.faile failedde ddepl ploy oy

Place Placed d by the the deplo deploym yment ent scanne scannerr service service to indi indicat cate e that that the giv given en conte content nt fail failed ed to deploy to the runtime. The content of this file will include some information about the cause of the failure.

.undepl undeploy oyin ing g

Place Placed d by the the depl deploy oym ment scann scanner er servic service e to indi indicat cate e that that it has has detecte detected da .deployed file .deployed file has been deleted and the content is being withdrawn. withdrawn. This marker marker file is deleted when the withdrawal process completes. completes.

.undepl undeploy oyed ed

Place Placed d by the deplo deploym yment ent scanner scanner servi service ce to to indi indicat cate e that that the the giv given en cont content ent has been withdrawn from the runtime. Deleting this file has no impact.

Report a bug 6.5 .6.4 . Example JBoss Application Application De ploym ployment ent Wo Workflow rkflows s

T his section des cribes the basic workflows involved in deploying, withdrawing, withdrawing, and redeploying redeploying JBoss prebuilt applications to OpenShift Online. After running the desired commands, run git comm it and it and git push to push to deploy the changes to the application. application. To Add New New Z ipp ipped ed Conte nt a nd Deploy It It

Run the following command: command: $ cp target/example.war deployments/

To Add New New Unzipped Conte nt a nd Deploy It

Run the following commands:

42


$ cp -r target/example.war/ deployments/ $ touch deplo yments/e yments/example.wa xample.war.dodeploy r.dodeploy

To Withdraw Deployed Content

Run the following command: command: $ git rm deplo yments/ex yments/example.war ample.war.dodeplo .dodeplo y deplo yments/ex yments/example.war ample.war

To Replace D eploy eployed ed Z ipp ipped ed Conte nt with a New Version Version and Deploy It It

Run the following command: command: $ cp target/example.war deployments/

To Replace De ployed Unzipped Unzipped Conte nt with a New Version and De ploy It

Run the following commands: $ git rm -rf deployments/example.war/ $ cp -r target/example.war/ deployments/ $ touch deplo yments/e yments/example.wa xample.war.dodeploy r.dodeploy

Report a bug

6.6. About Jenkins Online Build System Jenkins integrates with other OpenShift Online Online applications. applications. T o s tart building with Jenkins, Jenkins, Jenkins Client must be added to an existing application. From then on, running a git push command push command initiates a build process inside a Jenkins builder builder instead ins tead of ins ide the normal applicatio application n compute space. For For cus tom applications, applications, or applications applications that have no ups tream repositories, the build process can be initiated directly from the Jenkins web interface, without having to run the git p ush ush command. Using the embedded Jenkins Jenkins Client Client build sys tem provides provides numerous numerous benefits: Archived build information No application downtime during the build process Failed builds do not get deployed (leaving the previous working version in place) Jenkins builders have additional resources, for example example memory memory and s torage A large community of Jenkins plug-ins Report a bug

6.6.1. Configuring Jenkins T his s ection describes how to s et up Jenkins to rebuild an application application automatical automatically ly when changes are made made to a local repository and then to pus h those changes to the remote repository. Report a bug 6.6 .1.1. Resource Requirements for Jenkins

The Jenkins application can be used to build any number of applications; this is limited only by the number of gears you have available. For example, if a PHP application application is created and MySQL database

43


is on the first gear, then Jenkins will be added to a separate gear. A third gear will will be used for the Jenkins builder. In other words, whenever the Jenkins builder is active, it occupies one of the available gears. Report a bug

6.6.2. Creat Crea t in ing g Jenkins-e Jenkins-enabled nabled Appli Applicat cations ions Jenkins can be enabled with new applications, applications, either scaled or non-scaled. Use Use the rhc app cre ate ate command to create a scaled or non-scaled application with an associated Jenkins application, and to add the Jenkins client to your application. Report a bug 6.6.2.1. Cre at ing a Scaled Jenki Jenkins-Enabled ns-Enabled Appli Application cation

Use the rhc app crea te command command with the t he -s (or -s (or --scaling) --scaling) option to create a scaled application, application, and the --enable-jenkins --enable-jenkins option option to add the Jenkins client to your application. If a cartridge type is specified with multipl multiple e vers ions, the client tools tools will will prompt you to specify the vers ion to us e. $ rhc app create App_Name php --enable-jenkins -s

Important T ake note of the login credentials credentials that this comm command outputs to the s creen. T hese credentials will be required to log in to the Jenkins home page.

Report a bug 6.6.2.2. C rea ting a Sing Single-Instance le-Instance Jenki Jenkins-Enabled ns-Enabled Appli Application cation

Use the rhc app crea te command to create a non-scaled application with an associated Jenkins application, and to add the Jenkins client to the application. If a cartridge type is specified with multiple versions, the client tools will prompt prompt to s pecify the version to use. T ake note of the login login credentials credentials that this command command outputs to the s creen. T hese credentials are required to log in to the Jenkins home page. $ rhc app create App_Name php --enable-jenkins

Report a bug 6.6.2.3. Confirming that a Jenkins-Enabled Application is Created

Run rhc apps to apps to confirm that the Jenkins-enabled Jenkins-enabled application application has been created. This can also be verified by navigating to the public URL returned by the rhc app cr eate command eate command to view the Jenkins home page.

44


Report a bug

6.6.3. Building Building Applicat Applications ions with Jenkins Building applications with Jenkins uses dedicated application space, which can be larger than the application application runtime runtime s pace. The Jenkins online build build s ystem monitors monitors applications applications that have an embedded Jenkins Client, and automatically rebuilds and deploys those applications whenever changes to the Git repository are pus hed to the remote server. No further interaction interaction is required by the us er. The existing application application is not affected until a new, succes sful build has been created. Should Should the build fail, the existing application application continues to run, although although a failure in the deployment deployment process (deploy - s tart post_deploy) may leave the application partially deployed or inaccessible. T he actual build build and deploym deployment ent process that Jenkins Jenkins executes involves involves numerous s teps, as des cribed below. 1. T he user iss iss ues a git push command, push command, and Jenkins is notified that a new push is ready. 2. A dedicated Jenkins slave (a builder ) is created. The rhc apps command apps command can be used to display this slave information. The application name is the same as that of the originating application, but with a " bldr" suffix. su ffix.

Important T he first 28 characters of the application application name name must be unique, or builders builders will be shared across applications. This can lead to build issues.

3. Jenkins runs the build. 4 . Content from the originating application is downloaded to the builder application using git gi t (for source code) and rsync (for rsync (for existing libraries). 5. ci_build.sh is ci_build.sh is called called from the Jenkins Jenkins shell. This sets up the builder application application for the Jenkins environment environment and performs performs some built-in bundling bundling s teps (PHP pear process ing, Python Python virtual environment, etc). 6. .openshift/action_hooks/build is executed on the Jenkins Jenkins builder. builder. 7. Any additional desired des ired steps step s are executed from the Jenkins she ll (Maven (Maven build, Gem install, ins tall, test tes t cases, etc). 8. Jenkins stops the currently running applicatio application, n, and runs rsync to rsync to s ynchronize all new content content over to the originating application. 9. .openshift/action_hooks/deploy .openshift/action_hooks/deploy is is executed on the originating application. 10. Jenkins starts the originating originating applicatio application, n, and .openshift/action_hooks/post_deploy is executed on this application. 11. Jenkins archives archives all build artifacts artifacts for later reference. 12. After 15 minutes minutes of o f idle time, time, the "build " build app" will be destroyed destro yed and will no longer appear in the output of the rhc apps command. apps command. The build artifacts, however, will still exist in Jenkins and can be viewed there. T he build job can be monitored monitored using the Jenkins interface. The interface provides an extensive range of information about the current build, build history, artifacts, as well as plug-ins to graph, track, run tests and perform other operations. The following following is an example example build history of an application application built using the embedded Jenkins Client. Logging for Jenkins-level errors (for example, DNS timeouts, builder configuration, etc.) is available in the

45


Jenkins logs from the command line using the rhc tail command. tail command. Replace jenkin jenkins s with the Jenkins application name in the following, if different: $ rhc tail jenkins tail jenkins

Logging for application-level errors (for example, compilation failures, test failures, etc.) is available via the Jenkins web interface under the corresponding build history, while logging for deployment-level errors is available in the application's logs from the command line: $ rhc tail App_Name tail App_Name

Report a bug 6.6 .3.1. Building Building C ustom Applications Applications

Build custom applications, or applications that have no upstream repositories, directly from the Jenkins web interface instead inst ead of using u sing the git push command. push command. T o build an application from the Jenkins web web interface, click on the located on the right s ide of the interface.

icon for the application to build,

T he status of the build process process can be viewed viewed in the web interface interface under the section labeled labeled Build Executor Status Status. Report a bug

6.7. Deleting an Application Warning Application removal is irreversible. All remote data associated with the application will be removed. If an application is no longer required, it can be deleted. Management Conso Console le

Click on the Applications tab Applications tab in the Management Console, then click on the desired application to delete it. Click on the Delete this appli cation button and follow the instructions on the s creen. Client Cli ent Tools

Run the following command to delete all the remote data for your application, typing yes when yes when prompted: $ rhc app delete App_Name delete App_Name

This process only deletes your remote application data. You must manually delete application data stored on your local machine. Report a bug

6.7.1. Deleting Local Application Data

46


Warning T he following following procedure deletes the s elected directory directory and all the files it contains. Enter Enter the correct directory and ensure the files it contains contains are no longer needed before running this command.

Procedure Procedure 6 .9. To De lete Local Local Appli Application cation Dat a

Open a terminal and use the following command to delete the application data stored on the local machine: $ rm -rf ~/ path/to/app_directo path/to/a pp_directory/ ry/

Report a bug

6.8. Gears and Storage Management As an application is developed and the changes are pus hed to the Git repos itory, the amount amount of disk space that is available available to run the application application is slowly reduced. T his is because Git stores all repository information, information, whether it is s till required required or not. Other Other as pects of developing developing and running applications applications also result in was ted disk s pace, such as old log files files and unused application libraries. libraries. In In such s uch cases either additional additional storage is required, or the existing disk space is optimized optimized to achieve the best poss ible performance of the applications. . T his s ection describes how to us e the OpenShift Online Online client client tools to add additional additional gear s torage, and to manage the existing disk space to optimize application performance. Refer to rhc cartridge storage --help for --help for a list of all available command options.

Note Free plan users must upgrade their OpenShift OpenShift Online subs cription cription for additional gear storage. Log onto the Management Console, and click My Account to Account to view upgrade options before attempting attempting to increase the gear s torage.

Management Conso Console le

Click the Applications tab Applications tab in the Management Console, then click on the desired application to manage manage its gear s torage. Click Click on the current gear s torage of the cartridge you wish to alter, then choose the new desired amount. Click Save to Save to commit your changes. Report a bug

6.8.1. Viewing Gear Storage Use the rhc cartridg e storage command and with the t he --show option storage comm --show option to view the current gear storage allocation for each cartridge that exists in an application, as shown in the example below.

47


$ rhc cartridge storage --show -a App_Name RESULT: MySQL Database 5.1 -----------------Base Base Gear Storage: 1GB Additiona Addi tional l Gear Storage: 3GB OpenShift Web Balancer Balancer ---------------------Base Base Gear Storage: 1GB Additiona Addi tional l Gear Storage: None PHP 5.3 ------Base Base Gear Storage: 1GB Additiona Addi tional l Gear Storage: None

Use the rhc cartridg e storage storage comm command and with the t he -c option -c option to view gear storage for a specifi s pecific c cartridge that exists in an application, as shown in the example below. $ rhc cartridge storage --show -a App_Name -c php-5 -c php-5 RESULT: PHP 5.3 ------Base Base Gear Storage: 1GB Additiona Addi tional l Gear Storage: None

Report a bug

6.8.2. Adding Gear Storage Use the rhc cartridg e storage storage comm command and with the t he --add option --add option to add a specified amount of gear storage to your application. application. $ rhc cartridge storage php-5.3 -a App_Name -a App_Name --add 3gb Set storage on cartridge ... set to 3GB Storage Info -----------Base Base Gear Storage: 1GB Additiona Addi tional l Gear Storage: 3GB

If the same command is used to add another 1GB of storage, there will be a total of 4GB of additional gear storage. Report a bug

6.8.3. Set Gear Storage Use the --set option --set option with the rhc cartridge storage command storage command to set the amount of gear storage of an application. T his is different from the --add option --add option in that you are specifying the amount of gear storage rather than adding more.

48


$ rhc cartridge storage php-5 -a php-5 -a App_Name App_Name --set 5gb Set storage on cartridge ... set to 5GB Storage Info -----------Base Base Gear Storage: 1GB Additiona Addi tional l Gear Storage: 5GB

Report a bug

6.8.4. Removing Gear Storage Use the rhc cartridg e storage storage comm command and with the t he --remove option --remove option to remove a specified amount of gear storage. $ rhc cartridge storage php-5 -a php-5 -a App_Name App_Name --remove 3gb Set storage on cartridge ... 2GB Storage Info -----------Base Base Gear Storage: 1GB Additiona Addi tional l Gear Storage: 2GB

Report a bug

6.8.5. Managing Application Disk Space OpenShift OpenShift provides tools to optimize optimize the dis k space to help achieve the best poss ible performance performance of the applications. Report a bug 6.8.5.1. Disk Space Cleanup T ool

The Disk Space Cleanup Tool can can help manage manage an application application disk s pace. T his tool is part of the rhc app ap p command suite, and performs the following functions: Runs the git gc comm gc command and on the application's Git repos itory on the s erver Clears the application's /tmp and /tmp and log file directories. directories. T hese ar e specified by the application's application's OPENSHIFT_ OPENSHIFT_ _LOG_DIR and _LOG_DIR and OPENSHIFT_TMP_DIR OPENSHIFT_TMP_DIR environment environment variables.

Important OpenShift Online does not automatically back up or rotate log files. The Disk Space Cleanup T ool runs runs the rm -rf comm rf command and to clear the contents of these directories. T o save s ave their contents, use the rhc snapshot save com save comman mand d first to create a s napshot of the s ystem.

Clears unus ed application application libraries. libraries. T his means that any library files previously installed by a git push comm push command and are removed. T he Disk Space Cleanup Cleanup Tool us es the following syntax: $ rhc app app tidy App_Name

Report a bug

49


50

Chapter 7. Application Management

Chapter Chapt er 7. Appli Applicat catio ion n Mana Managemen gementt 7.1. Application Management Commands Use the rhc app command app command to manage your applications, view application status, and start, stop, restart, reload and delete applications. Run rhc app --help for --help for more information and a full list of the available available options . $ rhc app action App_Name action App_Name [Optional Arguments]

The following table describes the application management command options that you can use to manage an existing application in the cloud. Table 7.1. Application Management Command Argument Options O p t io n

D e t a ils

s tart

Start an application.

s top

Stop an application.

force-s top

Stops all application proces s es .

res tart

Res tart an application.

reload

Reload an application.

s t a tu s

Dis play the current s tatus of an application.

s h ow

Show information about an application.

tidy

Clean out the application's logs an and tmp directories an and tidy up the Git repo on the server.

create

Create an application and add it to a domain.

git-clone

Clone and configure an application's repos ititory locally.

delete

Remove an application.

Report a bug

7.2. Managing Applications in a Secure Shell Environment Manage your OpenShift Online applications in a shell environment to perform specialized operations and general debugging. debugging. The s hell access access provides s pecialized pecialized tools for managing managing your applications. applications. Using the s hell environmen environmentt to acces s your OpenShift Online Online applications applications is protected and res tricted with Security-Enhanced Linux (SELinux) policies.

Important Shell access access is quite powerful and it is poss ible to accidentally accidentally damage damage an application. application. Therefore it is recommended recommended you only use shell access when necessary.

Report a bug

7.2.1. Accessing an Application Use the rhc ap p ssh ssh command to access an application in a secure shell environment. After you have

51


gained shell access , you you can run the help command help command at the shell prompt to see the shell commands available to you. You can also use general Linux commands to perform routine operations in the shell environment. The following example below shows a connection to the application racer. $ rhc app ssh racer Connectin Connecting g to 517623ecdbd93cdffa000001@ 51 7623ecdbd93cdffa000001@ racer-aut racer-autom omobile.exa obile.exam m ple.com ... ...

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

You are accessing a service servi ce tha that t is for use use only by auth authori orized zed users. users. If you yo u do not have have auth authori orization, zation, discontinu di scontinue e use use at once. Any use use of the the services servi ces is subject subject to the the applicable appli cable term term s of the the agreem agree m ent which can be found at: at: https://www.openshift.com/legal

********************************************************************* Welcom Welc om e to OpenShift shell shell This This shell shell will wi ll assist assist you in m anaging anaging OpenShift Ope nShift applications. appli cations. !!! !!! IMPORTANT IMPOR TANT !!! !!! IMPORTANT IMPOR TANT !!! !!! IMPORTANT IMPOR TANT !!! !!! Shell access is quite powerful powe rful and and it is possible for you to accidentally accidentally damage your application. Proceed Proc eed with care! If worse com es to worst, destroy your application with 'rhc 'rhc app delete' dele te' and and recreat recr eate e it !!! !!! IMPORTANT IMPOR TANT !!! !!! IMPORTANT IMPOR TANT !!! !!! IMPORTANT IMPOR TANT !!! !!! Type "help" for m ore info. [racer-aut [racer-autom om obile.exam obile.exam ple.com 517623ecdbd93cdffa000001]\>

Report a bug

7.2.2. Accessing a Specific Gear The rhc a pp ssh ssh command command opens a shell to the head gear of an application. application. T his proces s can be used to debug a gear problem in in a s caling applicati application. on. To access a different gear you must first determine a specific gear's ID and SSH URL: $ rhc app show hybrid --gears ID State State Cartridges Size SSH URL ----------------------------------------------- ------- ------------------------------------- ----- --------------------------------------------------------------------------------------------------------------------------------------------------51774b712587c83ddb00009d started php-5.3 haproxy-1.4 small [email protected] 519b0fd02587c84b860002d8 started php-5.3 haproxy-1.4 small 519b0fd02587c84b860002d8@519b0fd02587c84b860002d8-automobile.example.com 519b1018dbd93c851800 519b1018db d93c85180001fc 01fc start started ed php-5.3 php-5.3 haproxy-1.4 haproxy-1.4 small 519b1018dbd93c85180001fc@519b1018dbd93c85180001fc-automobile.example.com 519b06eb 519b 06ebdbd9 dbd93cd4 3cd43900 39000027 0027 start started ed postgresql-9.2 small 519b06ebdbd93cd439000027@519b06ebdbd93cd439000027-automobile.example.com

For example, in the output above the ID of the first scaling gear is 519b0fd02587c84b860002d8 519b0fd02587c84b860002d8 and and its SSH URL is 519b0fd02587c84b860002d8 519b0fd02587c84b860002d8@519b0fd02587c84b860002d8 @519b0fd02587c84b860002d8automobile.example.com .

52


Use the ssh command ssh command with the SSH URL to open a secure shell to the desired gear: $ ssh 519b0fd02587c84b860002d8@519b0fd02587c84b860002d8-automobile.example.com

Report a bug

7.2.3. Accessing a Database Cartridge T he integrity of a databas e can be verified by connecting to an application application us ing SSH SS H and running the shell for the database. A success ful connection connection to the database shell indicates that the database has been created correctly. T he shell for each database also offers a selection of comman commands ds that can be us ed to manage manage a database. See the selected database's documentation documentation for more information information on the database shell commands available.

Important Shell access access is quite powerful and it is poss ible to damage damage an application accidentall accidentally. y. Therefore it is recommended recommended to use s hell access access only when when necess ary.

Procedure Procedure 7 .1. To Manage a Da ta base in a Shell Environm Environment ent

1. Use the rhc ap p ssh ssh command command to access the des ired application application in a s hell environmen environment. t. The example below shows a connection to the application racer, which has a PostgreSQL database. After the shell access has been gained, run the help command help command at the shell prompt to see the shell commands available.

53


$ rhc app ssh racer Password: ********** Connectin Connecting g to 517623ecdbd93cdffa000001@ 51 7623ecdbd93cdffa000001@ racer-aut racer-autom omobile.exa obile.exam m ple.com ... ...

****************************************************************** *** You are accessing a service servi ce tha that t is for use use only by aut authoriz horized ed users. users. If you yo u do not have have auth authori orization, zation, discontinu di scontinue e use use at once. Any use use of the the services servi ces is subject subject to the the applicable appli cable term term s of the the agreem agree m ent which can be found at: at: https://www.openshift.com/legal

****************************************************************** *** Welcom Welc om e to OpenShift shell shell This This shell shell will wi ll assist assist you in m anaging anaging OpenShift Ope nShift applications. appli cations. !!! !!! IMPORTANT IMPOR TANT !!! !!! IMPORTANT IMPOR TANT !!! !!! IMPORTANT IMPOR TANT !!! !!! Shell access is quite powerful powe rful and and it is possible for you to accidentally accidentally damage your application. Proceed Proc eed with care! If worse com es to worst, destroy your application with 'rhc 'rhc app delete' dele te' and and recreat recr eate e it !!! !!! IMPORTANT IMPOR TANT !!! !!! IMPORTANT IMPOR TANT !!! !!! IMPORTANT IMPOR TANT !!! !!! Type "help" for m ore info. [racer-aut [racer-autom omobile.exa obile.exam m ple.com 517623ecdbd93cdffa000001]\>

2. Access the interactive database shell by running the appropriate appropriate comman command d for the database: mysql: mysql : interactive MySql shell psql: psql : interactive PostgreSQL shell mongo: mongo : interactive MongoDB shell For example, to open the interactive PostgreSQL shell: [racer-aut [racer-autom omobile.exa obile.exam m ple.com 515e21acdbd93c051 515e21acdbd93c051d000022 d000022]\> ]\> psql psql (8.4.13) (8.4.13) Type "help" for help. racer=#

Report a bug

7.3. Environment Variables Environm Environment ent variables are named named values that change the way running process es behave in computing computing environments. They can be used to provide a variety of different environmental values: application names, names, commonly commonly access ed directory names, usernames, pass words, hostnames, and IP addresses . Your application application reads the environment environment variables and us es the information information to configure itself for the OpenShift environment.

54


The amount, values, and availability of variables can be different depending on which cartridges are enabled on your application. For example, the environment variables of a PostgreSQL database are different to a MySQL database. T here are two ways to view the environment environment variables for an application: application: 1. Add an export s export s tatement tatement to the App_Na App_Name me/.openshift/action_hooks/build /.openshift/action_hooks/build file, then run git push. push . The variables are listed in the Git output and s tart with remote: declare -x. -x . 2. Use SSH to gain gain shell access to your application application and run the env en v command at the shell prompt. Report a bug

7.3.1. 7.3. 1. Informat ional Environm Environment ent Variables T hese variables variables provide information information about your application. Table 7.2. Informational Environment Variables E nvir o nme nt Va r ia ble Na me

E xa mple

P u r p o se

OPENSHIFT_APP_DNS

App_NameDomain.example.com

T he application's fully-qualifi fully-qualified ed domain namespace

OPENS HIFT_APP_NAME HIFT_APP_NAME

App_Name

T he application's name

OPENS HIFT_APP_UUID HIFT_APP_UUID

0123456789abcdef0123456789 abcdef

The UUID of the application (32 hex characters)

OPENSHIFT OPENSHIFT _ _I _I P

127.0 .250 .1

T he IP addres s the application listens listens on

OPENSHIFT OPENSHIFT _ _P _P ORT

80 80

T he port the application receives requests from

OPENSHIFT_SECRET_TOKEN

A 128 character string unique to an application that may be used for authentication, and can be overridden with the rhc setenv en v command

Report a bug

7.3.2. 7.3. 2. Director Direct ory y Environm Environment ent Variables T hese variables r eturn the directories where your application application res ides. Note that the only directory directory that is guaranteed never to be deleted is OPENSHIFT_DATA_DIR OPENSHIFT_DATA_DIR..

55


Table 7.3. Directory Environment Variables E nvir o nme nt Va r ia ble Na me

E xa mple

P u r p o se

/var/lib/openshift/51774b763817 c83ddb00009d/

T he application's application's home home directory

OPENS HIFT_DATA_DIR HIFT_DATA_DIR

$OPENSHIFT_HOMEDIR/approot/data/

A persistent data directory

OPENSHIFT OPENSHIFT _ _L _L OG_DIR

$OPENSHIFT_HOMEDIR//logs/

Where cartridge-specific logs are stored

OPENSHIFT OPENSHIFT _ _DB _DB _LOG_DIR

$OPENSHIFT_HOMEDIR//logs/

Where database-s pecific pecific logs are stored

$OPENSHIFT_HOMEDIR/approot/runtime/repo/

Repository containing the currently deployed deployed vers ion of the application

/tmp/

A temporary directory you can use; SELinux protects data in this directory from other users

OPENSHIFT_HOMEDIR OPENSHIFT_HOMEDI R

OPENSHIFT_REPO_DIR

OPENSHIFT_TMP_DIR OPENSHIFT_TMP_DI R

Report a bug

7.3.3. Database Environment Variables T hese variables pertain to your database (if you have one) and are used to connect your application application to your database. T he exact variable names names depend on the databas e type; the value of is is MONGODB, MYSQL, or POSTGRESQL as appropriate. Note these connections are only available to your application internally; you cannot connect from an external source. OpenShift OpenShift Online does not currently s upport user changes to environment environment variables. This includes includes changing the default MySQL admin password (even outside of phpMyAdmin). If you change your pass word, ensure that the change takes effect correctly. Note that this res triction only only applies to the default administrative administrative user. You can add more more users as required, and specify a pas sword of your own choosing choosing for these us ers. Ta ble 7.4 . Data base Environm Environment ent Variables E nvir o nme nt Va r ia ble Na me

E xa mple

P u r p o se

OPENSHIFT OPENSHIFT _ _DB _DB _HOST _HOS T

127.0 .250 .1

T he hos tname or IP addres s used to connect to the database

OPENSHIFT OPENSHIFT _ _DB _DB _PORT _POR T

330 6

T he port the databas e s erver is listening on

OPENSHIFT OPENSHIFT _ _DB _DB _USERN _USE RNAME AME

admin

T he databas e adminis trative username

OPENSHIFT OPENSHIFT _ _DB _DB _PASSWOR D

8ddT ns t22X3Y

T he databas e adminis trative user's password

OPENSHIFT OPENSHIFT _ _DB _DB _SOCKET _SOC KET

$OPENSHIFT_HOMEDIR/mysql5.1/socket/mysql.sock

An AF socket for connecting to the database (for non-scaled apps only)

OPENSHIFT OPENSHIFT _ _DB _DB _URL

mysql://admin:8ddTnst22X3Y@1 27.0.250.1:3306/

Database connection URL

56


Report a bug

7.3.4. Jenkins Environment Variables If your application includes Jenkins, you have access to the following variables. Table 7.5. Jenkins Environment Variables E nvir o nme nt Va r ia ble Na me

E xa mple

P u r p o se

JENKINS_ JENKINS_USERN USERN AME

s ys tem_builder

Sys tem builder account on the Jenkins server

JENKINS_PASSWORD

RnmXQlavs b4 f

Pas s word for the s ys tem builder account on the Jenkins Jenkins server

JENKINS_URL

https://jenkinsdomain.example.com/

DNS name name for the ass ociated Jenkins Jenkins server where builds occur

Report a bug

7.3.5. 7.3. 5. Gear Gea r Env Environm ironment ent Variables T hese variables apply to scaling applications. applications. Ta ble 7.6. Ge ar Environm Environment ent Variables E nvir o nme nt Va r ia ble Na me

E xa mple

P u r p o se

OPENSHIFT_GEAR_DNS

gearnam gearname-dom e-domain. ain.exam example ple..com

T he gear's full fully-qua y-qualilified fied domain domain name

OPENSH IFT_GEAR_NAME IFT_GEAR_NAME

gearname

T he gear's name

OPENSH IFT_GEAR_UUID IFT_GEAR_UUID

0123456789abcdef0123456789 abcdef

The gear's UUID

Report a bug

7.3.6. 7.3. 6. JBoss Env Environm ironment ent Variables T he table below shows the environment variables variables pertaining to supported JBoss applications applications on OpenShift Online. Table 7.7. JBoss Environment Variables Env En viro ronm nment ent Vari Variabl able e Name Name

Purp Pu rpos ose e

JAVA_ JAVA_OPT OPT S

Controlled Controlled by the cartridge and used to s pecify additional additional arguments to the JVM where JBoss application will run.

JAVA JAVA_OPT _OPT S_EXT

Appended to the JAVA_OPTS environment variable before the JVM is invoked, and used to provide additional additional options to the JVM without rewriting the JAVA_OPTS environment envir onment variable. Th is allows a llows developers developers to better support their application application users .

JBoss environment environment variables are s tored in the App_Na /App_Name me/.openshift/config/standalone.xml /.openshift/config/standalone.xml file that is part of jbos sas -7. The example code code below shows the environment environment variables for a MySQL datasource connection URL in the form jdbc:mysql:// SERVER_NAME :PORT /DATABASE_NAME :

57


jdbc:mysql://${env.OPENSHIFT_MYSQL_DB_HOST}:${env.OPENSHIFT_MYSQL_DB_PORT}/${e nv.OPENSHIFT_APP_NAME}

T he environment environment variables variables can be saved on the s erver so that s ensitive information information does not have to be passed repeatedly to the command line. Procedure Procedure 7 .2. To Se t Environm Environment Variables on the Se rver

1. Open the App_Na file. App_Name me/.openshift/config/standalone.xml /.openshift/config/standalone.xml file. 2. Specify the required values for any of your environment environment variables , then save sa ve and close the file. 3. Commi Committ and push the changes to the server: $ git commi t -a -m " COMMIT MESSAGE " $ git push

Important Sensitive information information stored in your environment environment variables is visible if you use the rhc snapshot commands. snapshot commands.

Report a bug

7.3.7. 7.3. 7. Cust om Enviro Environm nment ent Variables OpenShift OpenShift Online enables you to s et cus tom environm environment ent variables for your applications. applications. Setting Custom Environment Variables

Use the following command to set one or more environment variables for an application. Set multiple variables by adding additional Variable=Value arguments Variable=Value arguments separated by spaces: $ rhc env set Variable=Value Variable2=Value2 Variable2=Value2 -a -a App_Name App_Name

Viewing Vi ewing Cust om Environm Environment ent Variables

View the custom environment variables set for an application using the following command: $ rhc env list -a App_Name

Viewing Vi ewing the Value of a C ustom Environm Environment ent Variable

Display the value of one or more custom environment variables using the following command: $ rhc env show Variable Variable2 -a Variable2 -a App_Name App_Name

Removing Remo ving Custom Environment Environment Variables

Remove a custom environment variable using the following command: $ rhc env unset Variable -a Variable -a App_Name App_Name

58


Report a bug

7.4. About Node.js Applications T his s ection provides provides the bas ic information information required for running Node.js Node.js applications on OpenShift Online. Report a bug

7.4.1. Repository Repositor y Layout When you create a new Node.js application on OpenShift Online, the application directory is populated with several s everal files . The following table dis plays this layout: Ta ble 7.8 . Node.js Node.js Repository Repository Layout File

Use

node_modules /

Node modules packaged with the application.

deplis t.txt

Deprecated lis t of npm modules to ins tall with the application.

npm_g pm_gllobal bal_modul dule_li _list

List of of gl global oballly in instal stalled and and av availabl able np npm modu odules. es.

s erver.js

OpenShift Online s ample Node application.

package.js on

Package des criptor for npm.

README

Information about us ing Node.js with OpenShift Online .

.opens hift/

Location for OpenShift Online s pecific files .

.openshift/action_hooks/pre_bui ld

Script Script that runs every git push, push , but before the build.

.open openshi shift ft/a /act ctiion_h on_hoo ook ks/bui s/builld

Scri cript that that runs runs ever every y git push during push during the build build process (on the CI system if available).

.openshi openshift/ ft/ac acti tion_ on_hoo hooks/d ks/depl eploy oy

Scrip Scriptt that that runs runs every every git push after push after the build, but before the application application is res tarted.

.openshift/action_hooks/post_d eploy

Script Script that runs every git push, push , but after the application is restarted.

You can create additional directories if needed, but do not delete the node_modules and node_modules and .openshift directories.

Note When you git push, push , everything in your remote repository directory is recreated. Place items that you want to persist between pushes , such as a databas e, in the ../data directory ../data directory on the gear where your OpenShift Online application app lication is running.

Report a bug

7.4.2. 7.4 .2. Inst Inst alli alling ng Node Modul Mo dules es If you want to install Node modules from the npm registry, registry , you can specify the modules in the package.json file. package.json file. Package.json describes Package.json describes how your package package is s tructured and is used by npm to install and manage your application. application. T he dependencies has h in the package.json file package.json file can be used to specify the Node modules (and optionally the version) to install alongside your application application (" locally") locally") on

59


the OpenShift Online environment when you git push your push your application. For more information, see https://npmjs.org/doc/json.html . Example package.json entry: package.json entry: "dependencies": { "coffee-script": "connect":

"1.3.3",

"*",

"optim ist": ist": "<=0.3. "<=0 .3.4", 4", "socket.io": "socket.io" : "" },

Node modules not included in the npm registry can registry can be installed by packaging them in the node_modules directory. node_modules directory. The npm_global_module_list file contains a list of globally installed modules. You can override a globally available module by specifying it in package.json or package.json or by packaging it in the node_modules directory. Node gives preference to the " locally" locally" ins talled version of that module. Report a bug

7.5. Scheduling Timed Jobs with Cron Use the OpenShift Online Online cron scheduler to set up timed jobs jobs for your applications. T his cons ists of adding the cron s cheduler cheduler cartridge to your application, application, adding the required cron jobs to the appropriate directories, directories, and then updating the remote Git repository. You can also us e the rhc cartridge comma command nd to enable or disable your cron s cripts. T he following following example example demonstrates how to create a new application and enable cron s upport. Note Note that if you s pecify a cartridge type with multipl multiple e vers ions, the client tools tools prompt prompt you to s pecify the version to use. Procedure Procedure 7.3. To Cre at e an Applic Applicat at ion and Enable Cron Support Support

1. Create a new application: $ rhc app create holy php

2. Add the cron scheduler sched uler cartridge to your new application: $ rhc cartridge cartridge add cron cron -a hol y

3. Add the cron cron jobs to your application's application's .openshift/cron/{minutely,hourly,weekly,daily,monthly}/ directories. For example: $ mkdir -p .openshift/cron/minutely .openshift/cron/minutely $ echo 'date >> $O PENSHIFT_REPO_DIR/php/dat PENSHIFT_REPO_DIR/php/date.tx e.txt' t' > .openshift/cron/minutely/date.sh

60


4 . Commit Commit your changes and pus h them to the remote remote repos itory. $ git add .openshift/cron/ .openshift/cron/ $ git commit -m "configuring cron jobs" $ gi t push push

T his example appends a new line of date information information to the $OPENSHIFT_REPO_DIR/php/date.txt file every minute. Use the curl command curl command to verify the operation of this script: $ curl http://hol http://hol y-roll er.examp er.example.com/date.t le.com/date.txt xt Thu Thu Feb Thu Thu Feb Thu Thu Feb

2 01:02:01 EST 2012 2 01:03:01 01:03 :01 EST 2012 2 01:04:01 01:04 :01 EST 2012

The scripts that you place in the /cron subdirectories /cron subdirectories are executed at the respective frequencies. Scripts in each subdirectory are executed sequentially, in alphabetical order. Scripts in the /cron/hourly directory /cron/hourly directory are executed on the firs t minute of every hour. You You can us e the rhc cartridge command cartridge command to enable or disable your cron scripts. For example, to disable all of your scripts: $ rhc cartridge cartridge stop cron -a hol y

To enable all of your scripts: $ rhc cartridge cartridge start start cron -a hol y

Note T he cron commands commands affect all cron jobs. You cannot disable or enable individual individual cron jobs. Report a bug

7.6. Available Ports for Binding Applications All ports ports less than 1024 are res erved for OpenShift Online Online operations. Developers Developers will not be able to bind to these ports. However, However, ports greater than 10 24 are available for binding. binding. The following following table displays the commonly commonly used ports for binding.

Important While While the following following ports are suggestions for available available applications applications or gears , ports ports 2303-230 8 are reserved for OpenShift SNI SNI Im Implementation, plementation, and port 10 050 is res erved for the OpenShift OpenShift OpenShift Online Z abbix agent. You will will not be able to bind to these ports.

61


Ta ble 7 .9. Comm Common Ports a nd The ir Usage Usage Applica t ion Na me

P o r t Numb e r

D e sc r ip t io n

Kerberos

4444

Kerberos is us ed for us er authentication identifying with a node.

Git

94 18

Git is us ed for vers ion control.

MySQLd

330 6, 63132-63164

My Structured Query Language (MySQL (MySQL)) acts as a server s erver providing access to databases.

Mongod

270 17

MongoDB acts as a s erver providing access to databases.

Pos tgreSQL

54 32

Pos tgreSQL acts as a s erver providing access to databases.

MS SQL

14 33-14 34

MS SQL acts as a s erver providing access to databases.

Oracle

1521, 24 83, 24 84

Oracle acts as a s erver providing access to databases.

HT T P/HT T PS

80 0 8, 80 0 9, 84 4 3

Hypertext T rans fer Protocol Secure (HTTPS) is used for secure communication over a server.

HT T P cache

80 80 , 8118, 8123, 10 0 0 110010

HTT P cache cache is is used for the temporary temporary s torage of documents.

memcache

11211

memcache is a memory caching system.

jacORB

3528, 3529

JacORB is a Java reques t broker.

JBos s Debug

8787

A debug program for JBos s applications.

JBos s Management

4 712, 4 4 4 7, 760 0 , 9123, 9990 , 9999, 18001

A management management program pr ogram for JBoss applications.

AMQP

5671-5672

Advanced Mes s age Queuing Protocol (AMQP) is used to transfer messages between applications.

Puls eAudio

4 713

Puls eAudio is a s erver that manages the use of audio devices.

Flas h

1935

Flas h is a multimedia platform.

Munin

4 94 9

Munin is a network monitoring application.

Virt Migration

4 9152-4 9216

Virt migration is the copying of one machine's data and moving it to another.

OCSP

90 80

Online Certificate Service Protocol (OCSP) is a protocol used for obtaining the status of

62


a certificate. You can also bind to the internal IP IP through ports 150 00 -35530, which are not externally externally address able. You can also bind to $ OPENSHIFT_CartridgeShortName OPENSHIFT_CartridgeShortName _PORT _POR T (80 80) for http connectivity, connectivity, which will will reroute externally through through port 80 . Report a bug

7.6.1. 7.6. 1. WebSocket WebSocket Port Confi Configu gurat rat ion In its current form on OpenShift Online, WebSocket can be used by connecting to specific ports on an application, as the main routing layer is still Apache-based. WebSocket connections are supported with browser-based applications on OpenShift Online, allowing bi-directional communication without requiring multipl multiple, e, open HTT P connections. connections. The T CP-based protocol uses HT T P as an initiation initiation handshake, which is treated t reated as an upgrade upgrad e reques t. IfIf succes s uccess s ful, the connection remains open and s witches to the WebSocket protocol. For plain WebSocket connections ( ws://), ws://), requests should be directed to port 80 00 , while while WebSocke WebSockett Secure connections connections ( wss://) wss://) s hould use port 84 43. For example: example: http://example.example.com:8000 https://example.example.com:8443 Report a bug

7.6.2. Email Port Configuration OpenShift Online provides support for connecting to externally hosted email services (POP, IMAP, and SMTP). For developers, this means that you can establish a connection from your application to your own email server, or to one of the popular public email services, such as Gmail or YahooMail. If you are deploying popular blogging or wiki software on OpenShift Online, such as Drupal, Joomla, MediaWiki, or WordPress WordPress , you can also also take advantage of this feature by altering the email email settings of the s oftware to point to the appropriate email service. T he following following ports are the s uggested options for email support: SMTP/submission: 25, 465, 587 IMAP: 143, 220, 993 POP: 109, 110, 995 Communication occurs at a limited rate. Port 587 (submission) is restricted to a maximum rate of 256 Kbps. Ports 25 (SMTP) and 465 (SMT (SMT PS PS)) are restricted to a maxim maximum rate of 24 Kbps. Both Both will consume an extremely extremely small share of the available available bandwidth if congestion exists .

Important Be aware that access to email servers from cloud cloud providers may be blocked by Realtime Blackhole Lists (RBLs) . This may affect your ability to connect to some email servers. If you are unable to make a connection to one of these services, make sure that your email provider allows authenticated connections from Amazon AWS EC2 hosts.

Report a bug

63


Chapter 8. Authentication and SSH Keys OpenShift Online uses the Secure Shell (SSH) network protocol to authenticate account credentials to the OpenShift Online servers for secure communication, and supports both RSA and DSA keys for SSH authentication. authentication. This section des cribes how OpenShift OpenShift Online authentication authentication works, and provides information on how to manage SSH keys for OpenShift Online user accounts. For successful authentication, the public SSH key on your computer must match the public key that has been uploaded to the OpenShift Online server. When you perform the initial configuration of the OpenShift OpenShift Online client client tools, the interactive setup wizard generates a new pair of SSH keys in the default .ssh folder .ssh folder of your home directory. The SSH key pair consists of the public key, id_rsa.pub, id_rsa.pub , and the private key, id_rsa. id_rsa . As part of the initial configuration, you have the option of automatically uploading the public key, id_rsa.pub, id_rsa.pub , to the OpenShift Online server. See the Client Tools Installation Guide for more information about client tools configuration. Management Conso Console le

Click the Settings tab Settings tab in the Management Console to view SSH key management options. From there, you can add or revoke authorization tokens. Report a bug

8.1. Viewing All Public Keys The rhc sshkey sshkey list command list command displays all public keys that have been added to the OpenShift Online server for your user account: $ rhc sshkey sshkey li st libra (type: ssh-rsa) --------------------Fingerprint: Fingerp rint: 43:f5:29:a 43 :f5:29:ad:9f:b8 d:9f:b8:b3:a6:e7:88:c9:7f :b3:a6:e7:88:c9:7f:4c:a9:0c:ad :4c:a9:0c:ad winKey (type: ssh-rsa) ---------------------Fingerprint: Fingerp rint: 0c:16:81:e3 0c :16:81:e3:51:eb:12:90:f6:03 :51:eb:12:90:f6:03:80:g2:a :80:g2:a2: 2:10:78 10:78:14 :14 default (type: ssh-rsa) ----------------------Fingerprint: Fingerp rint: 43:f8:93:re 43 :f8:93:re:9f:a3:a :9f:a3:a8:f4:f3 8:f4:f3:34:g8:3d :34:g8:3d:1g:d8:3c :1g:d8:3c:a :as s Available: Avail able: true You have 3 SSH keys associated with your account.

Report a bug

8.2. Viewing a Specific Public Key The rhc sshkey and displays details of the key specified: sshkey show comm show command $ rhc sshkey show KeyName KeyName (type: ssh-rsa) ----------------------Fingerprint: Fingerp rint: d2:0f:1b:8d:3e:07:0b d2:0f:1b:8d :3e:07:0b:5a: :5a:14:df 14:df:2 :2a: a:44 44:15:f0:e7 :15:f0:e7:fc :fc

Report a bug

64

Chapter 8. Authentication and SSH Keys

8.3. Generatin Generat ing g Keys Ke ys Manu Manually ally The ssh-keygen command ssh-keygen command generates a new pair of RSA or DSA keys as specified. Procedure Procedure 8.1. G enera ting SSH Keys Keys Manually

1. Run the ssh-keygen command, ssh-keygen command, replacing KeyType with KeyType with the type of key you want to generate, either dsa or dsa or rsa: rsa: $ ssh-keygen -t KeyType

2. When prompted for the file in in which to save the key, pres s Enter to Enter to s ave the key in the default location (/home/username/.ssh/) with the default name: ... ... Generating Generating public/pri public /privat vate e rsa r sa key pair. Enter file in which to save the key (/home/username/.ssh/id_rsa): /home/username/.ssh/id_rsa

Note It is recommended to save all SSH keys in the default location. If id_rsa exists id_rsa exists , rename rename the new SSH key to avoid overwriting existing keys. For example: Enter file in which to save the key (/home/username/.ssh/id_rsa): /home/username/.ssh/ My_rsa

3. When prompt prompted ed for a passphras e, enter a passphras e or leave leave blank blank for no pass pass phrase then press Enter: Enter : Enter passphrase (empty for no passphrase): Enter same passphrase again: Your identification has been saved in /home/ username/.ssh/id_rsa Your Your public p ublic key has has been saved saved in /home/ /hom e/ username/.ssh/id_rsa.pub. ... ...

Report a bug

8.4. Adding a Key The rhc sshkey sshkey add command uploads the specified public key to the OpenShift Online server. Replace KeyName and KeyName and KeyPath with KeyPath with the name and path of the key you want to upload: $ rhc sshkey add KeyName KeyPath

Report a bug

8.4.1. Creating a Specific SSH Key Type Use the --type and --type and --content options --content options to create a specific type of SSH SSH key. T his allows you to

65


specify more information about the SSH key directly, rather than uploading the key file. $ rhc sshkey add KeyName KeyPath --type KeyPath --type KeyType --content KeyType --content KeyContent

Report a bug

8.4.2. 8.4 .2. Removin Removing g a Key The rhc sshkey sshkey remo ve command ve command deletes an existing public key for your account from the OpenShift Online server: $ rhc sshkey remove KeyName

Report a bug

8.5. Resolving Authentication Issues Occasionally your local public key may not match the public key for your account on the OpenShift Online server, or your key may not be found on the local file file sys tem. tem. This can cause connection iss ues, or the SSH key authentication process can fail, in which case a new pair of SSH keys must be generated. If you are having problems authenticating, there are two ways you can generate a new pair of SSH keys: Use the interactive setup wizard (recommended) (recommended) Manually generate and add SSH keys Report a bug

8.5.1. Resolving Issues with Interactive Setup Wizard T he recomme recommended nded method method of res olving olving authentication authentication iss ues is to us e the interactive setup wizard to generate a new pair of SS SSH H keys. T he interactive setup wizard also provides the option of automatically automatically uploading your new public key to the OpenShift Online server. Use the rhc setup setup command command to launch the setup wizard, then follow follow the onscreen instructions. See the Client Tools Installation Guide for more information about the OpenShift Online client tools interactive interactive setup s etup wizard. Report a bug

66

Chapter 9. Monitoring Monitoring a nd Troub leshooting

Chaptt er 9. Monit Chap Monitoring oring and and Troubleshoot ing 9.1. Monit Monit orin oring g Appli App licat cation ion Resources As described des cribed in Section 6.1.1, 6.1.1, “About Scaled Applications ” , scaled applications are automatically allocated allocated additional resources based on demand. T he amount of resources consumed by an application application can be monitored and viewed from the OpenShift Online Management Console. Follow the instructions below to monitor monitor and view applicatio application n resources. res ources. T he instructions below assume that a s caled application application has already been created. Procedure 9 .1. To Monitor Applic Applicat at ion Resources Resources

1. Access the th e OpenShift Online Management Management Console. 2. Click on the My Appli Appli cations tab cations tab to view all of your applications and click on the name of the scaled application you want to examine. 3. T he OpenShift OpenShift Online Managem Management ent Console displays the number number of gears , along along with the siz e of the gears , used by the selected application. application. 4. Hover over the gear size information information with your your mouse to display a popup mess mess age with more more detailed information. 5. Scaling is performed by the HAProxy HAProxy cartridge. Click Click See HAProxy HAPro xy statu status s page to get information about testing the scaling function of your application.

Note At the time of this writing, the scaling function cannot be disabled from an application. The only way to disable scaling is to remove the scaled application, and create a new application without the scaling option.

Report a bug

9.2. MongoDB Monitoring Monitoring Service (MMS) The MongoDB Monitoring Service (MMS) is a cloud-based monitoring service, designed by 10gen 10gen,, to monitor the health of MongoDB deployments. MMS provides an agent that runs on MongoDB servers, and this agent reports information information such as opcounters, memo memory ry information, information, number number of connections, connections, network I/O, database storage size, and more. All of this information is available in customizable charts that are displayed in your web browser. OpenShift Online provides built-in support for MMS; you can add the MMS agent to your application using the s ame ame comman commands ds as for other cartridges. T he only prerequisite for us ing MMS MMS is that you have an account with 10gen; you can sign up for a free MMS account at https://mms.10gen.com/ https://mms.10gen.com/.. Report a bug

9.2.1. Configuring an Application with MMS T he following following procedure des cribes how to configure your application application to take advantage of the s ervices provided by MMS MMS.. This procedure ass umes umes that you have s uccess fully created an application application and added the MongoDB cartridge. Procedure 9 .2. How How to set up your application to use MMS

67


1. Download the agent from https://mms.10gen.com/ https://mms.10gen.com/.. When you log into MMS, MMS, you will see a Download the Monitoring Agent link Agent link on the Hosts page. Click this link to download an agent preconfigured with your group credentials. 2. Create a directory named m m s in your application's .openshift directory .openshift directory with the following command, command, r eplacing app_directory with app_directory with the root directory for your application: $ mkdir ~/app_directory/. ~/app_directory/.openshift/mms openshift/mms

3. Add the settings.py file settings.py file to the m m s directory: $ cp ~/mms-agent/settings.py ~/app_directory/.openshift/mms/

Important The settings.py file settings.py file contains the MMS agent settings that contain the API keys for connecting to your MMS account and updating the monitoring metrics. The MMS agent will not function without this file.

4 . Use Git to add and comm commit it the m m s directory to your local repository, then push it to your remote repository: $ $ $ $

cd app_directory/ git add .openshift/mms/ git commi t -m "mms settings" settings" -a git push

5. Use the following command command to add the agent to your application: $ rhc cartridge add 10gen-mms-agent-0 -a App_Name

After succes sfully completing completing this procedure, navigate navigate to the https://mms.10gen.com/ https://mms.10gen.com/ page, page, enter your host's details and s tart monitoring monitoring your application. application. Report a bug

9.2.2. Monitoring Monito ring Appl Applic icat at ions with MMS Report a bug 9.2 .2.1. Adding Hosts Hosts t o MMS

After you have created an application and added the MMS agent, you can add the host to the Hosts page on https://mms.10gen.com/. https://mms.10gen.com/. To To add a new host, you need the hostname, port number, and login credentials that were provided when you added MongoDB to your application. If you no longer have this information, you can retrieve it directly from your application, as follows: 1. Use SSH to connect to your application: $ ssh UUID@ UUID@ App_Name-D App_Name-D omain .example.com

where UUID is UUID is the UUID of your application. You can retrieve this using the rhc apps command. apps command. Replace App_Na App_Name me and and Domain with Domain with your application name and domain, respectively.

68


2. Run the following following command command to retrieve all the necess neces s ary connection and credential information for your application: > echo echo $O PENSHIFT_MONGO PENSHIFT_MONGO DB_DB_URL DB_DB_URL

Procedure 9.3. How How to add hosts t o MMS

1. Navigate to https://mms.10gen.com/ https://mms.10gen.com/ and and login to your account. 2. Click the Hosts Ho sts + button at the top of the page to display the New Host dialog Host dialog box. 3. Enter the required details and then click Add. which Add . This adds the host details to the agent, which immediately starts collecting and storing data. Report a bug 9.2 .2.2. MMS Monitoring Monitoring with a Browser

After adding the MMS agent to your application and your host details to MMS, use the web interface to monitor your application's performance. Procedure 9.4 . How How to monitor monitor your a pplicat pplicat ions with with MMS

1. Navigate to https://mms.10gen.com/ https://mms.10gen.com/,, login to your account, and click the Hosts tab. Hosts tab. 2. Click the name of the host that you want to monitor monitor to view the available data collection str eams. You can customize this page to s uit your own requirements. requirements. See the 10 gen documentation documentation for full details. Report a bug

9.3. Troubleshooting JBoss Applications OpenShift OpenShift Online provides provides some basic tools to help you troubleshoot your JBoss applications applications s hould problems problems arise. This includes includes the ability ability to inspect the log files and also to tr igger a thread dump dump for JBoss applications. Report a bug

9.3.1. Debugging with Thread Dumps T hread dumps dumps are a us eful debugging tool. tool. IfIf an application application appears to have stalled or is running out of resources , a thread dump can help to reveal the s tate of the s erver, to identify identify what might might be causing any iss ues and ultimately ultimately to resolve the problem. problem. You You can us e the rhc threaddum threaddum p command to trigger a thread dump for a JBoss application. application. T he following following example example demonstrates the us e of this comma command: nd:

Note T his example ass umes umes that you have a valid account and have already created a domain and JBoss application application called called "myJBoss "myJBoss ".

69


$ rhc threaddump myJBoss Password: ********** Application event 'thread-dump' successful Success The thread dump file will be available via: rhc tail myJBoss -f /tmp/jbossas.log -o '-n 250'

Now use the rhc tail command tail command to inspect the resultant thread dump: tail myJBoss -f /tmp/jbossas.log /tmp/jbossas.log -o '-n 250' 250' $ rhc tail Password: ********** Heap def new generation generation total total 18240K, used used 4240K [0xdd580 [0xd d580000, 000, 0xde9400 0xde 940000, 00, 0xe2ad0000) eden space space 16256K, 24% used used [0xdd580000, [0xdd5800 00, 0xdd956930, 0xdd956930 , 0xde560000) 0xde56000 0) from space space 1984K, 15% used used [0xde750000, [0xde75000 0, 0xde79d9a0, 0xde940000) 0xde940000 )

Report a bug

9.3.2. Inspecting Server, Boot and Other Log Files The rhc tail command tail command inspects other JBoss application log files. By including the application name as the only argument, this command tails the contents of all the files in the cartridge/logs/ cartridge/logs/ directory. directory. The example below shows abbreviated output from this command. $ rhc tail tail myJBo myJBo ss Password: ********** ==> jbosseap-6/logs/server.log <== 2013/01/02 2013/01/ 02 02:06:37,14 02:06:37,144 4 INFO INFO [org.j [org .jboss. boss.as as.os .osgi] gi] (MSC service thread thread 1-1) JBAS011907: JBAS011907 : Register Register m odule: Module Module "deploym "d eploym ent.ROOT ent.ROOT.wa .war:main r:main" " from fro m Service Module Loader ==> jbosseap-6/logs/boot.log <== user.name = 1ca72484953b4701a4d32be920bcefc1 user.t user.tim im ezone = America/New_York Am erica/New_York 02:06:29,566 DEBUG [org.jboss.as.config] VM Arguments: -D[Standalone] -Xmx256m XX:MaxPermSize=128m -XX:+AggressiveOpts -Dorg.apache.tomcat.util.LOW_MEMORY=true Dorg.jboss.resolver.warning=true

The rhc tail command tail command provides the same output as if you directly log into an application instance and run the rhc tail_all comm tail_all command. and. ItIt s hows the services running on the application's application's behalf in real time. Tailing Specific Gears

Inspecting application application log files files on specific gears is helpful for diagnosing problems problems on secondary gears ; for example in scaled applications.

70


In order to inspect the application logs on a specific gear, first determine the gear's ID. See Section 7.2.2, “Accessing a Speci Specific fic Gear” for Gear” for details on how to find a specific gear's ID. Run the following command to tail the logs of the specified gear: $ rhc tail tail App-Name -g gear_ID

T he log displays on the comm command s creen, and updates every few s econds. Report a bug

9.4. Performing Application Maintenance from Workstation 9.4.1. Port Forwardi Forwarding ng Ports on a remote remote server s erver can be forwarded to your workstation, making making it easy to manage services s uch as MySQL. The rhc por t-forward t-forward command provides a wrapper for the ssh command, ssh command, and determines determines which remote ports to forward to your workstation.

Note Ensure that your application application is running before attempting attempting to configure port forwarding.

T he example example below shows remote remote ports for the App_Na App_Name me application application being forwarded locally: $ rhc port-forward port-forward App_Name Checking available ports ... done Forwarding ports ... Address already in use - bind(2) while forwarding port 8080. Trying local port 8081 Address already in use - bind(2) while forwarding port 8080. Trying local port 8081 Address already in use - bind(2) while forwarding port 8081. Trying local port 8082 To connect to a service running on OpenShift, use the Local address Service Serv ice ----------haprox haproxy y haprox haproxy y httpd httpd m ysql

Local OpenShift ----------------------------- ---- ------------------------------------------------------------------------------------------------127.0.0.1:8080 127.0.0.1:8080 127.0.0.1:8081 127.0.0.1:8081 127.0.0.1:8082 127.0.0.1:502 127.0.0.1:50226 26

=> => => =>

127. 1 27.9.159.130:8080 9.159.130:8080 127. 1 27.9.159.131:8080 9.159.131:8080 127.9.159.129:8080 127.9.159 .129:8080 52347a1d2587c866951 52347a1d2587c86 69511169 11697-m 7-m ydom ain.rh ain.rhcloud.com cloud.com :50226 :50226

Press CTRL-C to terminate port forwarding

In this example, you could now open a browser and connect to your remote application using the local ports. The current implementation of the rhc por t-forward t-forward command command forwards all open ports on a running application to your local workstation. If an application contains multiple cartridges, the command output

71


shows which remote remote services are being bound to local ports. For forwarding forwarding s pecific pecific ports, us e the ssh comm ssh command and with the th e -L option. -L option. T his s pecifies pecifies the local port you wish to t o forward to the remote r emote port. For example: example: $ ssh -L 8080:localho st:8080 st:8080

T his command command allocates allocates a socket s ocket to listen to the local port host 8080 (the 8080 (the first number). When a connection connection to this port is made, a secure channel forwards the connection to the remote remote host port 8080 (the s econd number). number). Port Forwarding Specific Gears

Port forwarding specific gears to diagnose problems problems on secondary s econdary gears makes makes examining examining problems problems with scaled s caled applications easier. eas ier. In order to port forward specific gears, first determine the gear's ID. See Section 7.2.2, “Accessing a Specific Gear” for Gear” for details on how to determine a specific gear's ID. Run the following command to port forward a specific gear, replacing App_Name with App_Name with the name of your application, and gear_ID with the gear's ID: $ rhc port-forward App_Name -g gear_ID

Example 9.1. Port Forwarding a Specific Gear $ rhc port-forward App_Name port-forward App_Name -g 522d5974 5973caccab0000c1 5973caccab0000c1 Checking available ports ... done Forwarding ports ... To connect to a service running on OpenShift, use the Local address Service Serv ice Local OpenShift ------- -------------- ---- ------------------------------------httpd httpd 127.0.0.1:8080 => 127.12.166.129:8080 127.12.166.129:808 0 Press CTRL-C to terminate port forwarding

Report a bug 9.4 .1.1. Port Forwarding Forwarding on on Mac OS X

Currently, out of the box, Mac OS X only provides the following interfaces for loopback addresses: localhost 127.0.0.1 T herefore, you you may experience experience error mess ages similar similar to thos e s hown below when attempting attempting to configure port forwarding using the IP address for your OpenShift OpenShift Online application. application. $ rhc port-forward App_Name Checking available ports... Error Erro r trying to forward f orward ports. You You can try try to forward forw ard m anua anually lly by runnin running: g: ssh ssh -N 70277280b8534c8 70277280b8534c8a a9fc76d2734393dfa@app01-dom ain. ain.example.com

72


T he current workaround to enable port forwarding on Mac OS X is to configure an alias manually manually using us ing the ifconfig command ifconfig command for each IP address used by your application, using the command as shown below: $ sudo sudo i fconfig fconfig lo 0 alias application_IP_address

For example, if the IP address used by your application is 127.10.51.129, run the command as shown below: $ sudo i fconfig l o0 al ias 127.10.51.1 127.10.51.129 29

If your application uses multiple IP addresses, as shown in the example above, you must configure an alias for each IP address. For example, suppose you have a PHP application with both MySQL and phpMyAdm phpMyAdmin in cartridges added, and it uses the IP addresses 127.11.25.1 and 127.11.25.2. To correctly enable port forwarding, you must configure an alias for each IP address, as shown in the example below. $ sudo ifconfi g lo 0 alias 127.11.25.1 127.11.25.1 $ sudo ifconfi g lo 0 alias 127.11.25.2 127.11.25.2

Note The ifconfig command on Mac OS X requires root/administrative privileges to execute.

You can now use the rhc por t-forward t-forward command to enable port forwarding.

Important T he IP address alias you configure for your OpenShift OpenShift Online application application is not pers istent through sys tem reboots. IfIf you reboot your computer, computer, you you must repeat these steps to correctly enable port forwarding on Mac OS X.

Report a bug

73


Chapter 10. Backing Up and Restoring Application Data Use the rhc sna pshot save save command to create backups of your OpenShift Online applications, and also to res tore those backups to the s erver. As As a back-up tool, this command command creates a tar.gz file tar.gz file not only of your application but also of any locally-created log and other files, which is then downloaded to your local machine. machine. T he directory structure that exists on the s erver is maintained aintained in the tar file.

Important OpenShift OpenShift Online does not maintain maintain backups of your applications applications or user data on the OpenShift Online servers. T he files created by this process are always downloaded to your local machine. machine. Report a bug

10.1. Creating Application Snapshots Use the rhc sna pshot save save command to create a snapshot. The command will prompt for any miss miss ing information, information, such as your rhlogin and rhlogin and passwo password rd . The default filename filename for the s napshot is $App_Name.tar.gz $App_Name.tar.gz.. You can override this path and filename with the --filepath option. $ rhc snapshot save App_Name Pulling down a snapshot to App_Name .tar.gz... Creating and sending tar.gz RESULT: Success

Report a bug

10.2. Restoring Application Snapshots Use the rhc snapshot restore restore command to restore snapshots to the server. This restores the Git repository, the application data directories and the log files found in the specified archive. When the restoration is complete, complete, OpenShift OpenShift Online runs the deployment deployment s cript on the newly-restored repos itory, which completes th e deployment proces s in the s ame way as if yo u had run ru n git push. push .

Warning The rhc snapshot restore restore command overwrites the remote Git repository. Any changes you may have made since taking the snapshot will be lost. Importing snapshot data into a local environment may delete local content, for example a user table in your database. If you are unsure what effect a s napshot import may may have on your local data, use SS SSH H to access your application and make the backup directly.

74

Chapter 10. 10. Backing Up a nd Restoring Restoring Applica tion Da ta

$ rhc snapshot restore App_Name Restoring from snapshot App_Name.tar.gz... Rem oving old git repo: ~/git/App_Nam ~/git/App_Nam e.git/ e.git/ Removing old data dir: ~/app-root/data/* Restoring ~/git/App_Name.git and ~/app-root/data Activation status: success RESULT: Success

If you us ed the override process to s ave your application application under a different filename filename,, as outlined in Section 10.1, “Creating Application Snapshots” , you can restore this snapshot version of your application. The following command shows how to restore an application named App named App_Na _Name me,, but saved under the filepath Renamed_App: Renamed_App: $ rhc snapshot restore App_Name --filepath Renamed_App

Report a bug

10.3. Migrating an Application to Another Gear An application can be migrated to another gear with the OpenShift Online client tools. One scenario where this may be necess neces s ary is when a free fre e plan is upgraded to a paid plan. p lan. In In this case, cas e, an application created with the free plan exists on a small gear, but with an upgraded plan that application can be migrated to a medium gear. Procedure Procedure 1 0.1. Migrat Migrat e a n Appli Application cation to Another Another Ge ar

1. Create a snapshot of your existing application. application. $ rhc snapshot save App_Name

The rhc sna pshot save save command saves the App_Na App_Name me.tar.gz .tar.gz file file in the current working directory. Verify that your application application snaps hot has been s aved. 2. After confirming your application snaps hot is saved, delete the existing application. $ rhc app delete App_Name delete App_Name

3. Create a new application of the same type with with the correct gear s ize, and add any additional cartridges that existed in the original application. Use the following example to create an application on a medium gear, with no additional cartridges because the original application did not have any. $ rhc app create App_Name php-5.3 -g medium

However, if the original application cont ained, for example, the MySQL MySQL and phpMyAdmin phpMyAdmin cartridges cartr idges,, run the following command: $ rhc app create App_Name php-5.3 mysql-5 phpmyadmin-3 -g medium

4 . Finally, restore res tore the earlier saved application snaps hot to the newly created application. Be sure to specify the correct path to the s aved application application snaps hot.

75


$ rhc snapshot restore App_Name -f App_Name -f App_Name .tar.gz

Report a bug

76

Revision Re vision Hist History ory

Revision History Re vision 1 .0 .36 - 0 .4 0 5 Rebuild with Publican 4.0.0

T h u Nov 2 8 2 0 1 3

Re vision 1 .0 .36 - 0 T u e Nov 2 6 2 0 1 3 Added information information on s pecifying pecifying the s ize of cartridges. Added information to clarify action_hooks.

Rüdig e r La n dma nn

B ilha r Aula kh

Re vision 1 .0 .35 - 0 T h u Nov 7 2 0 1 3 B ilha r Aula kh Added two new topics topics about action hooks for cartridges and during the build process . Added information on configuring application deployment. Added information on adding specific SSH key types. Added information on managing domain membership with client tools. Added information on disabling local gears with multiple HA proxies. Added information on making deployment and rollback changes to applications. Updated port information for binding applications. Re vision 1 .0 .34 - 0 T u e O ct 1 5 2 0 1 3 Added information on configuring application deployment. Added support for PostgreSQL 9.2 from SCL. Added SECRET_TOKEN environment variable. Added Members section for domain membership. Added support for multiple domains. Added table and information about ports available for binding.

B ilha r Aula kh

Re vision 1 .0 .33- 0 We d S e p 1 8 2 0 1 3 Added information on port forwarding with individual gears. Updated cartridge version numbers. Added Custom Environment Variables section.

B ilha r Aula kh

77

OpenShift Online 2.0 User Guide en US

Recommend Documents