OpenShift Online 2.0 User Guide en US

OpenShift Online All Versions User Guide
Managing Applications in the Cloud with OpenShift Online Edition 1.0
Red Hat OpenShift Documentation Team
Managing Applications in the Cloud with OpenShift Online Edition 1.0
Red Hat OpenShift Do cumentatio n Team
Legal Notice Copyright 2013 Red Hat. T his document 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 Hat, Inc. and provide a link to the original. If the document is modified, all Red Hat trademarks 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 Enterprise Linux, the Shadowman logo, JBoss, MetaMatrix, Fedora, OpenShift, the Infinity Logo, and RHCE are trademarks of Red Hat, Inc., registered in the United States and other countries. Linux is the registered trademark of Linus T orvalds in the United States and other countries. Java is a registered trademark of 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 trademarks are the property of their respective owners. Abstract T his guide provides an introduction to OpenShift Online and documents its application management functions.
Table of Contents
Table of Contents
Preface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .5. . . . . . . . . . 1. Document Conventions 5 1.1. T ypographic Conventions 5 1.2. Pull-quote Conventions 6 1.3. Notes and Warnings 7 2. Getting Help 7 2.1. Do You Need Help? 7 2.2. We Need Feedback! 8 Chapter . . . . . . . . . 1. . . .Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .9. . . . . . . . . . 1.1. Product Introduction 9 1.2. Platform Overview 9 Chapter . . . . . . . . . 2. . . .Getting . . . . . . . . Started . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11 ............ 2.1. User Interfaces 11 2.1.1. Management Console 11 2.1.2. Client T ools 12 2.2. Basic Administration 12 2.2.1. Management Console 12 2.2.2. Client T ools 13 Chapter . . . . . . . . . 3. . . .Authorization . . . . . . . . . . . . . .T . .okens . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15 ............ 3.1. Authorization T okens 15 3.2. Creating Authorization T okens 15 3.3. Viewing Authorization T okens 16 3.4. Deleting Authorization T okens 16 Chapter . ........4 . ...Domains . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18 ............ 4.1. About Domains 18 4.2. Creating a Domain 18 4.3. Listing Available Domains 18 4.4. Viewing a Domain 19 4.5. Renaming a Domain 19 4.6. Deleting a Domain 20 4.7. Custom Domains and SSL Certificates 21 4.7.1. Using Custom Domain Names 21 4.7.2. Using Custom SSL Certificates 22 Chapter . . . . . . . . . 5. . . .Members ............................................................................... 23 ........... 5.1. 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. About Non-Scaled Applications 26 6.1.3. Viewing Accessible Applications 26 6.2. About Cartridges 27 6.2.1. Web Cartridges 27 6.2.2. Add-on Cartridges 27
6.2.3. Downloadable Cartridges 6.3. Creating an Application 6.3.1. Creating Scaled Applications 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 6.4.2. Managing Cartridges 6.4.2.1. Cartridge Action Hooks 6.5. Deployment 6.5.1. Build and Deployment Action Hooks 6.5.2. Preparing an Application for Deployment 6.5.3. Deploying an Application 6.5.4. Configuring Application Deployment 6.5.4.1. Deploying an Application From a Snapshot 6.5.5. About Hot Deployment 6.5.5.1. Hot Deployment Build Details 6.5.5.2. Enabling and Disabling Hot Deployment 6.5.6. JBoss Application Deployment 6.5.6.1. Deploying on Java 6 or Java 7 6.5.6.2. Automatic Deployment 6.5.6.3. T ypes of Marker Files 6.5.6.4. Example JBoss Application Deployment Workflows 6.6. About Jenkins Online Build System 6.6.1. Configuring Jenkins 6.6.1.1. Resource Requirements for Jenkins 6.6.2. Creating Jenkins-enabled Applications 6.6.2.1. Creating a Scaled Jenkins-Enabled Application 6.6.2.2. Creating a Single-Instance Jenkins-Enabled Application 6.6.2.3. Confirming that a Jenkins-Enabled Application is Created 6.6.3. Building Applications with Jenkins 6.6.3.1. Building Custom Applications 6.7. Deleting an 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. Removing Gear Storage 6.8.5. Managing Application Disk Space 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. Accessing an Application 51 7.2.2. Accessing a Specific Gear 52 7.2.3. Accessing a Database Cartridge 53 7.3. Environment Variables 54 7.3.1. Informational Environment Variables 55 7.3.2. Directory Environment Variables 55 7.3.3. Database Environment Variables 56 7.3.4. Jenkins Environment Variables 57 7.3.5. Gear Environment Variables 57 7.3.6. JBoss Environment Variables 57 7.3.7. Custom Environment Variables 58
Table of Contents
7.4. About Node.js Applications 7.4.1. Repository Layout 7.4.2. Installing Node Modules 7.5. Scheduling T imed Jobs with Cron 7.6. Available Ports for Binding Applications 7.6.1. WebSocket Port Configuration 7.6.2. Email Port Configuration
59 59 59 60 61 63 63
Chapter . . . . . . . . . 8. . . .Authentication . . . . . . . . . . . . . . . .and . . . . SSH . . . . .Keys . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 64 ............ 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 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 . . . . .T . roubleshooting . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 67 ............ 9.1. Monitoring Application Resources 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. T roubleshooting JBoss Applications 69 9.3.1. Debugging with T hread Dumps 69 9.3.2. Inspecting Server, Boot and Other Log Files 70 9.4. Performing Application Maintenance from Workstation 71 9.4.1. Port Forwarding 71 9.4.1.1. Port Forwarding on Mac OS X 72 Chapter . . . . . . . . . 10. . . . . Backing . . . . . . . . .Up . . . and . . . . .Restoring . . . . . . . . . . Application . . . . . . . . . . . . Data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 74 ............ 10.1. Creating Application Snapshots 74 10.2. Restoring Application Snapshots 74 10.3. Migrating an Application to Another Gear 75 . . . . . . . . . .History Revision . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 77 ............
Preface
Preface
1. Document Conventions
T his manual uses several conventions to highlight certain words and phrases and draw attention to specific pieces of information. In PDF and paper editions, this manual uses typefaces drawn from the Liberation Fonts set. T he Liberation Fonts set is also used in HT ML editions if the set is installed on your system. If not, 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 conventions are used to call attention to specific words and phrases. T hese conventions, and the circumstances they apply to, are as follows. 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: T o see the contents of the file m y_next_bestselling_novel in your current working directory, enter the cat m y_next_bestselling_novel command at the shell prompt and press Enter to execute the command. T he above includes a file name, a shell command and a key, all presented in mono-spaced bold and all distinguishable thanks to context. Key combinations can be distinguished from an individual key by the plus sign that connects each part of a key combination. For example: Press Enter to execute the command. Press Ctrl + Alt+ F2 to switch to a virtual terminal. T he first example highlights a particular key to press. T he second example highlights a key combination: a set of three keys pressed simultaneously. If source code is discussed, class names, methods, functions, variable names and returned values mentioned within a paragraph will be presented as above, in m ono-spaced bold . For example: File-related classes include filesystem for file systems, file for files, and dir for directories. Each class has its own associated set of permissions. Proportional Bold T his denotes words or phrases encountered on a system, including application names; dialog-box 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, select the Left-handed m ouse check box and click 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 special character into a gedit file, choose Applications Accessories
Character Map from the main menu bar. Next, choose Search Find from the Character Map menu bar, type the name of the character in the Search field and click Next. T he character you sought will be highlighted in the Character T able . Double-click this highlighted character to place it in the T ext to copy field and then click the Copy button. Now switch back to your document and choose Edit Paste from the gedit menu bar. T he 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-spaced Bold Italic 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 using ssh, type ssh username@ domain.name at a shell prompt. If the remote machine is exam ple.com and your username on that machine is john, type ssh john@ exam ple.com . T he m ount -o rem ount file-system command remounts the named file system. For example, to remount the /hom e file system, the command is m ount -o rem ount /hom e . T o see the version of a currently installed package, use the rpm -q package command. It will return a result as follows: package-version-release. 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 presenting the title of a work, italics denotes the first use of a new and important term. For example: Publican is a DocBook publishing system.
1.2. Pull-quote Conventions

T erminal output and source code listings are set off visually from the surrounding text. Output sent to a terminal is set in m ono-spaced rom an and presented thus:
books books_tests Desktop Desktop1 documentation downloads drafts images mss notes photos scripts stuff svgs svn
Source-code listings are also set in m ono-spaced rom an but add syntax highlighting as follows:
Preface
package org.jboss.book.jca.ex1; import javax.naming.InitialContext; public class ExClient { public static void main(String args[]) throws Exception { InitialContext iniCtx = new InitialContext(); Object ref = iniCtx.lookup("EchoBean"); EchoHome home = (EchoHome) ref; Echo echo = home.create(); System.out.println("Created Echo"); System.out.println("Echo.echo('Hello') = " + echo.echo("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 approaches to the task at hand. Ignoring a note should have no negative consequences, but you might miss out on a trick that makes your life easier.
Important
Important boxes detail things that are easily missed: configuration changes that only apply to the current session, or services that need restarting before an update will apply. Ignoring a box labeled Important will not cause data loss but may cause irritation and frustration.
Warning
Warnings should not be ignored. Ignoring warnings will most 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 where you can: search or browse through a knowledgebase of technical support articles about Red Hat products submit a support case to Red Hat Global Support Services (GSS) access other product documentation
You can also access the OpenShift web site at https://openshift.redhat.com/ to find blogs, FAQs, forums, and other sources of information. Red Hat also hosts a large number of electronic mailing lists for discussion of Red Hat software and technology. You can find a list of publicly available mailing lists at https://www.redhat.com/mailman/listinfo. Click the name of any mailing list to subscribe 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: 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 suggestion for improving the documentation, try to be as specific as possible 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.
Chapter 1. Introduction
Chapter 1. Introduction
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 ecosystem to provide a platform for mobile applications, database services, and more. OpenShift Online is built on Red Hat Enterprise Linux, which provides integrated application runtimes and libraries and a secure and scalable multi-tenant operating system for addressing the needs of enterprise-class applications. T his 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. Report a bug
1.2. Platform 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, OpenShift Online creates a file system layout that you can use as a template for building an application. OpenShift Online also generates a limited Domain NameSpace (DNS) so that your application is accessible online. T he two main functional units of OpenShift Online are the broker and cartridges. Broker T he broker is responsible for managing user logins, DNS, and application state. Users interact with the broker using the Management Console, command line interface tools, or a REST -based API. Cartridges Cartridges provide the functionality to run applications. Numerous cartridges are currently available to support languages such as Perl, PHP, and Ruby, as well as many database cartridges such as PostgreSQL and MySQL. System Resources and Application Containers T he system resources and security containers provided by the OpenShift Online platform are gears and nodes. Gears provide a resource-constrained container where you can run one or more cartridges. T hey determine the amount of RAM and disk space available to a cartridge. OpenShift Online currently provides three gear sizes: 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
Large gears provide 2GB of RAM, 100MB of swap space, and 1GB of disk space By default, you can use up to three small gears (a total of 1.5GB of RAM and 3GB of disk space). OpenShift Online can assign these three gears to a single application and its cartridges (Cron, MySQL, etc.), use each gear for a separate application, or use the gears for scaling an application. Nodes enable resource sharing so that multiple gears can run on a single physical or virtual machine. T his machine is referred to as a node host. Report a bug
10
Chapter 2. Getting Started

2.1. User Interfaces
2.1.1. Management Console
T he OpenShift Online Management Console is a graphical interface accessed with a web browser at https://www.openshift.com/. T he management console is best suited for: T he Management Console is best suited for: Setting up, administering and managing accounts Launching new applications Managing and monitoring applications T he following screenshot shows the home page of the Management 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 a brief description of the different pages and settings available in the Management Console. Page Applications Settings Help Description View and manage your applications and cartridges. If you do not have any applications, you can create new applications from this page. View and manage SSH keys, domains, and account authorizations. Access to KBase articles, community forums, tutorials, and other community resources. A wide variety of resources are available for diagnosing and resolving issues with your account or your applications. View and manage account information, including account upgrades. T his page shows your account details, subscription plan, and your account
My Account
11
usage. Red Hat technical support is available from here if you are subscribed to the upgraded plan. Note that the Management Console currently provides limited functionality. T herefore, most of the instructions in this guide are for the client tools. 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. T his guide assumes a user account is already set up and configured. Report a bug
2.1.2. Client Tools

T he 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 Management Console. T he client tools are best suited 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 using the client tools. T his guide assumes the client tools are already installed and configured. See the OpenShift Online Client Tools Installation Guide for instructions on how to install and configure the client tools. For a full list of client tool commands, run rhc --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 Management Console is used for most account administrative tasks, with some of the more common tasks described below. Changing a Password Navigate to the My Account page, and click Change your settings to change your password. Managing Subscription Plans Navigate to the My Account page, and click Plan Details to view your current plan, and to view the available upgrade and downgrade options. Account Help and T echnical Support T here are two types of help and support available based on the type of subscription plan.
12
Silver Plan Navigate to the My Account page, and click Account Help to access the help page. If the problem is not addressed in the frequently asked questions list, submit your account-related questions using the Subm it a question regarding your 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 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 accessing Red Hat Customer Portal for the first time.
Free Plan Click Help to access the help page. T his page gives out information about how to get started with OpenShift Online, explore the OpenShift Online platform, basic troubleshooting, and getting involved with the OpenShift Online community. T ype in a keyword in the Search the forum s box to access the Knowledge Base for known issues and general questions. You can also go to the OpenShift 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. Client Tools

Although using the OpenShift Online Management Console for account administration is recommended, the following tasks can be performed using the client tools. Viewing Account Details Use the rhc account command to get an overview of the currently logged in user and their capabilities:
$ rhc account Server: Login: Gears Used: Gears Allowed: Allowed Gear Sizes: SSL Certificates Supported: broker.example.com demo 1 100 small no
You can also view account details in the Management Console by navigating to the My Account page.
13
Note
T he 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. T his leads to updated features being temporarily only available in the Ruby gem version. T o ensure you have the latest version and all available features, see the OpenShift Online Client Tools Installation Guide for the Ruby gem installation method. Ending the Current Session Use the rhc logout command to end the current session with the OpenShift Online server and remove all local session files:
$ rhc logout Ending session on server ... deleted All local sessions removed.
Report a bug
14
Chapter 3. Authorization Tokens

3.1. Authorization Tokens
An authorization token is a secret value that is used with an OpenShift Online account without entering login information. A token is also used to grant another user full or partial access to your account depending on the token's scope. T he table below describes the different types of scopes available with authorization tokens. T able 3.1. Authorization T oken Scopes Scope session read userinfo Description Access to all API functions against an account. Read-only access to account resources, but cannot view authorization tokens. Access to login name, unique id, and user capabilities. Validity 1 day 1 month 1 month
When the client tools are installed and the rhc setup command is initially run to configure the client tools, the setup wizard prompts you to create an authorization token. If you answer YES , the wizard creates a session token in the ~/.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 tools installation process, use the rhc setup command to run the setup wizard again to create one. If an existing authorization token is no longer required and you do not wish to be prompted for token renewal, run the rhc logout command to delete the token. Management Console Authorization tokens can be managed in the Management Console. Click Settings in the navigation bar to view a list of current authorization tokens for your account. 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 add command to create a new token. Specify the scope for the token with the --scopes option, and a name for the token with the --note option:
15
$ rhc authorization add --scopes session --note My_token Adding authorization ... done My_token -------Token: Scopes: Created: Expires In:
787a57211d42f251204136b05d490038830d9b7057f54f816c2a9fcd0c8333b8 session 4:40 PM about 1 day
After creating a new authorization token, use the --token token_string global option to run rhc commands as the user associated with the authorization token you provide. Report a bug
3.3. Viewing Authorization Tokens

View the tokens associated with your account using the rhc authorization command:
$ rhc authorization My_token -------Token: Scopes: Created: Expires In:
787a57211d42f251204136b05d490038830d9b7057f54f816c2a9fcd0c8333b8 session 4:40 PM about 23 hours
RHC/1.8.0 (from laptop.example.com on x86_64-linux) --------------------------------------------------Token: 28f6e375dc7ea57b0dcabb3850d08ee9bc023f7df5dbfa4958afe7ad71d33e37 Scopes: session Created: 12:58 PM Expires In: about 19 hours
Report a bug
3.4. Deleting Authorization Tokens

Follow the instructions below to delete authorization tokens when they are no longer required, or when you no longer wish to grant access to your account to other users. Delete Specific Authorization T okens Run the rhc authorization delete command to delete one or multiple tokens:
$ rhc authorization delete token_1, token_2 Deleting authorization ... done
Delete All Authorization T okens Run the rhc authorization delete-all command to delete all the tokens associated with your account:
16
$ rhc authorization 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 URL and is unique to your account. T he syntax for an application URL is application-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 Online uses a blacklist to restrict the domains available to you. T he blacklist is maintained on the server. A message warns you that you have chosen a blacklisted name and asks you to choose a different domain if you try to create or alter a domain using a blacklisted name. Domains consist of a maximum of 16 alphanumeric characters and cannot have spaces or symbols. Management Console Click 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 to create a new domain:
$ rhc domain create automobile Creating domain 'automobile' You may now create an application using the 'rhc app create' command
T his command will create the domain autom obile .
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 to go beyond the allowed limitations of your account. Report a bug
4.3. Listing Available Domains

Run the rhc dom ain list command to see all available domains.
18
Chapter 4. D omains
$ rhc domain list Domain automobile --------------Created: Oct 01 7:28 PM Allowed Gear Sizes: small, medium Domain automobile2 ----------------Created: Oct 01 7:46 PM Allowed Gear Sizes: small, medium
Alternatively, run the rhc dom ains command to list all available domains. Report a bug
4.4. Viewing a Domain

Run the rhc dom ain show command to view information about a domain.
$ rhc domain show Domain automobile --------------Created: Oct 01 7:28 PM Allowed Gear Sizes: small, medium racer @ http://racer-automobile.example.com/ (uuid: 926056f8845b4e388b37f6735c89d0eb) ----------------------------------------------------------------------------Domain: automobile Created: Oct 01 7:28 PM Gears: 2 (defaults to small) Git URL: ssh://926056f8845b4e388b37f6735c89d0eb@racerautomobile.example.com/~/git/racer.git/ SSH: 926056f8845b4e388b37f6735c89d0eb@racer-automobile.example.com php-5.3 (PHP 5.3) ----------------Scaling: x2 (minimum: 2, maximum: 2) on small gears You have 1 application in your domain.
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 dom ain renam e command to alter it.
19
Procedure 4 .1. T o Rename a Domain 1. Ensure the domain does not contain any applications.
$ rhc apps No applications. Use 'rhc app create'.
If any applications are listed, use the rhc app delete command to remove them.
$ rhc app 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 renam e 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 command to delete it. Before you can delete a domain, you need to ensure it does not contain any applications. Procedure 4 .2. T o Delete a Domain 1. Ensure the domain does not contain any applications.
$ rhc domain show Domain_Name
If any applications are listed, use the rhc app delete command to remove them.
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 to delete the domain.
20
Chapter 4. D omains
$ 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 Online enables you to designate custom domain aliases for applications to use your own DNS entries instead of using the domain generated for you by the system. 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 are only available to users with upgraded OpenShift Online accounts. Management Console Click on an application name in the My Applications tab in the Management Console to view custom domain name and SSL certificate management options for the selected application. Report a bug
4.7.1. Using Custom Domain Names

Adding a Custom Domain Name Add domain name aliases to applications using the rhc alias add App_Name Alias command:
$ rhc alias add racer fast.cars.com RESULT: Alias 'fast.cars.com' has been added.
Viewing Custom Domain Names View domain name aliases and SSL Certificate status using the rhc alias list App_Name command:
$ rhc alias list racer Alias Has Certificate? Certificate Added ------------- ---------------- ----------------fast.cars.com yes 2013-08-05 quick.cars.com no -
Removing a Custom Domain Name Remove domain name aliases from applications using the rhc alias rem ove App_Name Alias 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 a Custom SSL Certificate Add a custom SSL certificate to an alias using the rhc alias update-cert command. If the private key is encrypted, specify the passphrase with the --passphrase option.
$ rhc alias update-cert racer fast.cars.com --certificate Cert_File --privatekey Key_File RESULT: SSL certificate successfully added.
Viewing Custom SSL Certificate Status View domain name aliases and SSL Certificate status using the rhc alias list App_Name command:
$ rhc alias list racer Alias Has Certificate? Certificate Added ------------- ---------------- ----------------fast.cars.com yes 2013-08-05 quick.cars.com no -
Removing a Custom SSL Certificate Remove a custom SSL certificate from an alias using the rhc alias delete-cert App_Name Alias command:
$ rhc alias 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
Chapter 5. Members
Chapter 5. Members
5.1. About Members
Developer teams can work collaboratively on applications with domain memberships. T here 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 any changes. Edit Member can create, update, and delete all applications in the domain, and has Git and SSH access. Administer Member has access to all features, but cannot change allowed gear sizes or edit the domain name.
Each member is given the edit role by default. Use the rhc m em ber add command with the --role option to change the role of a member, and specify the desired role to change to. Management Console Click the 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 m em ber add command to add a member to a domain, specifying the user login and domain name:
$ rhc member add loginname@example.com -n automobile Adding 1 editor to domain ... done
T he default role for the new member is edit. T o update the role of the member, run the command with the --role option, followed by either view, edit, or adm in depending on the desired role. Report a bug
5.3. Listing Members

Run the rhc m em ber list command to list the existing members of a domain. You can specify the desired domain name with the -n option, or the desired application with the -a option.
23
$ rhc member list automobile Login Role ------------------------ ------------login@example.com admin (owner) login2@example.com view login3@example.com edit login4@example.com admin
T he existing members and their roles are displayed. Report a bug
5.4. Removing a Member

Run the rhc m em ber rem ove command to remove an existing member from a domain.
$ rhc member remove -n automobile login4@example.com Removing 1 member from domain ... done
Use the rhc m em ber rem ove command with the --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. 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 of the application on small virtual servers, referred to as "gears". T he table below describes each component that makes up an OpenShift Online application. T able 6.1. Application Components Component Domain Description T he domain provides a unique group identifier for all the applications of a specific user. T he 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 T he name of the application is selected by a user. T he final URL to access the application is of the form http://[APP_NAME]-[DOMAIN].example.com DNS names can be provided for the application by registering an alias with OpenShift Online and pointing the DNS entry to the OpenShift Online servers. Used to modify application code locally. Once the code is applied, the git push command is run to deploy the revised code.
Application Name Alias
Git repository
OpenShift Online provides dedicated /var/tm p and /tm p directories for each user application. T he /var/tm p directory is a symbolic link to /tm p . Each /tm p directory is completely isolated from the /tm p directories of all other applications. OpenShift Online deletes files in these directories that are untouched for any 10-day period. Report a bug
6.1.1. About Scaled Applications

Application scaling enables the automatic allocation of resources based on demand. OpenShift Online monitors the resource requirements of scaled applications, and increases or decreases available resources accordingly. An application must be defined as scaled or non-scaled at the time of creation. A scaled application cannot be converted to a non-scaled application. Likewise, a non-scaled application cannot be converted to a scaled application. Report a bug 6.1.1.1. How Scaling Works Each application created on OpenShift Online always has the web cartridge associated with it. T he web cartridge can, for example, be a PHP cartridge. When an application is scaled, a second cartridge, called HAProxy, is added to the application. T he HAProxy cartridge listens to all incoming web page requests for an application and passes them on to the web cartridge, following defined 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 Online will then create a copy of the existing
25
web cartridge on a separate gear. In such a case, the web cartridge now has been scaled up two times. T his process is repeated as more web page requests are detected by the HAProxy cartridge, and each time a copy of the web cartridge is created on a separate gear, the 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 disabled to the web cartridges collocated on their gear. T his allows full gear resource usage for the HAProxy cartridges, which continue routing requests to other gears' web cartridges. If the ratio returns to two or below, routing to the 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 Applications

When a non-scaled application is created, it only consumes one of the default quota of gears assigned to users. T hat is, it 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 to display information about all the applications you have access to:
$ rhc apps racer @ http://racer-automobile.example.com/ (uuid: 926056f8845b4e388b37f6735c89d0eb) -----------------------------------------------------------------------------------Domain: automobile Created: Dec 19 10:20 PM Gears: 1 (defaults to small) Git URL: ssh://926056f8845b4e388b37f6735c89d0eb@racerautomobile.example.com/~/git/racer.git/ SSH: 926056f8845b4e388b37f6735c89d0eb@racer-automobile.example.com Deployment: auto (on git push) php-5.3 (PHP 5.3) ----------------Gears: 1 small
26
Report a bug
6.2. About Cartridges

Cartridges are the components of an OpenShift Online application. T hey include databases, 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 cartridges, run the rhc cartridge list command. Report a bug
6.2.1. Web Cartridges

Every OpenShift Online 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 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 (JBoss EWS) Non-Scalable Web Cartridges Z end 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 such as databases, scheduled jobs, or continuous integration. T he table below describes the functionality of the different types of add-on cartridges available with OpenShift Online.
27
T able 6.2. Add-on Cartridge Functions Function Database Database management Monitoring and Management Description Provide the application with one of several database back ends. Examples include MySQL and PostgreSQL. Provide functionality for managing the application's database using thirdparty software. Examples include HAProxy. 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 to view the current list of available add-on cartridges. Currently, the following add-on cartridges are available: Database Cartridges Scalable Database Cartridges MySQL database is a multi-user, multi-threaded SQL database server. MongoDB NoSQL database is a scalable, high-performance, open source NoSQL database. PostgreSQL 8 database is an advanced object-relational database management system. Management Cartridges Scalable Management Cartridges phpMyAdmin 3 is a web-based MySQL administration tool. HAProxy 1 is a high performance T CP/HT T P load balancer. Cron 1 is a daemon that runs specified programs at scheduled times. SwitchYard 0 is a lightweight service delivery framework providing full lifecycle support for developing, deploying, and managing service-oriented applications. Non-Scalable Management Cartridges RockMongo 1 is a web-based MongoDB administration tool. Jenkins Client 1 is a client for managing Jenkins-enabled applications. OpenShift Metrics 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. Downloadable cartridges can be custom 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 steps for downloadable 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, there are certain options to be considered. T hese options include whether you wish to enable scaling 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 is created. Management Console Click on the 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 command to copy the application's remote repository into a local working directory.
$ rhc git-clone App_Name Cloning into 'App_Name'... Your application Git repository has been cloned to '/home/apps/App_Name'
T he rhc git-clone command copies the template application files from the remote repository into the working directory. Edit the template application files to suit the application. Client T ools When creating applications with the client tools, the rhc app create command creates a new application by populating a remote Git repository with the selected cartridge and clones the repository to the current directory on the local machine. T he command also adds the host name and IP address of the application to the list of known hosts (~/.ssh/known_hosts). T he rhc app create command can be used with several optional parameters that customize the configuration of an application when it is created. Note that some of these options, such as ability to select larger gear sizes for the cartridges, are only available to users with upgraded plans. See rhc app create --help for a complete list of options. Prerequisites Application creation requires a reliable network connection. T he rhc app create command only makes a single attempt to create an application. OpenShift Online makes up to seven checks for the DNS entry to exist, and returns a failure message if not found. T he --tim eout option on the command line is used to override the default values when there are constant timeout issues. OpenShift Online uses two timeout parameters: a connection timeout, which determines how long the client tries to connect to the server before timing out; and a read timeout, which determines how long the client waits for a response from the server. T he default connection timeout value is 20 seconds. T he default read timeout value is 120 seconds. T he --tim eout option affects both timeout parameters, but it can only be used to increase values from the default. T he timeout value cannot be set to be less than the default. For example, if --tim eout 50 is used, it sets the connection timeout value to 50 seconds, but does not affect the read timeout value. Similarly, if --tim eout 150 is used, it sets both the connection and read 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 create command with the -s (or --scaling ) option to create a scaled application. See Section 6.1.1, About Scaled 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. T he following command will create a scaled application named hybrid .
$ rhc app create hybrid php-5.3 -s Application Options ------------------Namespace: automobile Cartridges: php-5.3 Gear 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 is cf:eb:77:cb:0b:fc:02:d7:72:7b:ab:80:c0:90:88:b7. Are you sure you want to continue connecting (yes/no)? yes Warning: Permanently added 'hybrid-automobile.example.com,21.20.161.211' (RSA) to the list of known hosts. Your application 'hybrid' is now available. URL: ssh://fjoe04cabdc4efa8f2513a21e2ed27d@hybridautomobile.example.com/~/git/hybrid.git/ SSH to: fjoe04cabdc4efa8f2513a21e2ed27d@hybrid-automobile.example.com Git remote: ssh://fjoe04cabdc4efa8f2513a21e2ed27d@hybridautomobile.example.com/~/git/hybrid.git/ Cloned to: /home/User/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 can be manually scaled to control the 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) option:
$ rhc app create hybrid php -n Domain_Name
Report a bug
6.3.2. Creating Single-Instance Applications

T he following example demonstrates the creation of a non-scaled PHP application called racer . Note that if a cartridge type is specified with multiple versions, the client tools prompts to specify the version to use.
30
$ rhc app create racer php-5.3 Application Options ------------------Domain automobile Cartridges: php-5.3 Gear Size: default Scaling: no Creating application 'racer' ... done Waiting for your DNS name to be available ... done Cloning into 'racer' ... The authenticity of host 'racer-automobile.example.com (21.26.220.40)' can't be established. RSA key fingerprint is bf:eb:77:cb:0b:fc:02:b7:72:7e:ab:80:c0:90:88:a7. Are you sure you want to continue connecting (yes/no)? yes Warning: Permanently added 'racer-automobile.example.com,21.26.220.40' (RSA) to the list of known hosts. Your application 'racer' is now available. URL: ssh://516cd60e4382ecb972000006@racerautomobile.example.com/~/git/racer.git/ SSH to: 516cd60e4382ecb972000006@racer-automobile.example.com Git remote: ssh://516cd60e4382ecb972000006@racerautomobile.example.com/~/git/racer.git/ Cloned to: /home/User/racer Run 'rhc show-app racer' for more details 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) 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 create hybrid php , for example, another application can be created in the domain autom obile . T he application 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 Online can be used to create applications of no specific type, for build or other testing purposes, using the DIY cartridge:
$ rhc app create [App_Name] diy
31
T he DIY cartridge creates an application that is not publicly available nor does it have anything running. Use git push and a .openshift/action_hooks/ script to start the application. Report a bug
6.3.3. Manually Scaling an Application

T he following are cases where a scaled application must be manually scaled: If a certain load is anticipated on an application and it must be scaled accordingly. T here are a fixed set of resources for an application. T he cost must be controlled manually. Procedure 6.1. T o Scale an Application Manually 1. Run rhc app 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) ---------------------------------------------------------------------------Domain: automobile Created: 11:48 AM Gears: 1 (defaults to small) Git URL: ssh://fjoe04cabdc4efa8f2513a21e2ed27d@hybridautomobile.example.com/~/git/hybrid.git/ SSH: fjoe04cabdc4efa8f2513a21e2ed27d@hybrid-automobile.example.com Deployment: auto (on git push) php-5.3 (PHP 5.3) ----------------Scaling: x1 (minimum: 1, maximum: available) on small gears haproxy-1.4 (OpenShift Web Balancer) -----------------------------------Gears: Located with php-5.3
2. For each scaling cartridge, run rhc cartridge scale command to set the minimum and maximum gears the cartridge can use 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: x1 (minimum: 1, maximum: 10) on small gears
3. Set the minimum and maximum gears to 1 using the rhc cartridge 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: x1 (minimum: 1, maximum: 1) on small gears
Report a bug
6.4. Adding and Managing Cartridges

OpenShift Online supports a wide range of add-on cartridges. T he OpenShift Online Client T ools provide a range of commands for managing cartridges. View the cartridges associated with your applications by running the rhc apps command. Use the rhc app show AppName command to view information about an individual application. Installed cartridges are listed under the Cartridge heading.
Note
An error message is displayed if any rhc command is used and the usage exceeds the node's disk quota limit.
Warning gear #{uuid} is using #{usage pct} of disk quota Warning gear #{uuid} is using #{usage pct} of inodes allowed
Management Console Click on the 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. T he available add-on cartridges are displayed under your application. Report a bug
6.4.1. Adding Cartridges

Use the rhc cartridge list command to view the current list of available cartridges. T his command lists all available cartridges, provides a brief description of each cartridge, and labels each cartridge as a web cartridge or add-on cartridge. Most add-on cartridges can only be added after a prerequisite web cartridge is installed. Procedure 6.2. T o Add a Cartridge Using the CLI Run the following command, replacing Cart_Type and App_Name with the application name and the desired cartridge:
$ rhc cartridge add Cart_Type -a App_Name
Specifying Cartridge Gear Size Use the -g , or --gear-size option with sm all , m edium , or large when adding a cartridge to specify the gear size. Note that this option is not available to non-scaled applications, as these run the web
33
cartridge and any add-on cartridge on the same gear.

$ rhc cartridge add Cart_Name -a App_Name -g medium
T his 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 and large gears. Free plan users are limited to small gears. Use the My 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 can be performed with the rhc cartridge command using the following syntax:
$ rhc cartridge Action Cart_Type -a App_Name
T able 6.3. Cartridge Management Actions Action list add remove stop start restart status reload show storage scale Report a bug 6.4 .2.1. Cartridge Action Hooks Action hooks are used to modify certain processes during an application's lifecycle. Cartridge action hooks are specifically used to interact with cartridges. Each time OpenShift Online invokes one of these cartridge actions, the action hooks directory is checked for an executable file. Create a file in the [App_Name]/.openshift/action_hooks directory with the same name as the desired event to use cartridge action hooks. Use the following list for a reference to all possible action hooks associated with a cartridge control action. Details List supported cartridges. Add a cartridge. Remove a cartridge. Stop a cartridge. Start a cartridge. Restart a cartridge. Return the current status of a cartridge. Reload the configuration of a cartridge. Show information about a cartridge. View and manipulate storage on a cartridge. Set the scaling range of a cartridge.
34
T able 6.4 . Cartridge Action Hooks Action Start Stop Reload Description Start the software the cartridge controls. Stop the software the cartridge controls. T he cartridge and the package software will re-read the configuration information. Current cartridge process is stopped and started again. All unused resources are released. Event specific examples pre_start_Cart-Name, post_start_Cart-Name pre_stop_Cart-Name, post_stop_Cart-Name pre_reload_Cart-Name, post_reload_Cart-Name pre_restart_Cart-Name, post_restart_Cart-Name pre_tidy_Cart-Name, post_tidy_Cart-Name
Restart T idy
Cart_Name is a replaceable term used to represent the cartridge short-name. For example, for a JBossAS cartridge to be implemented during the pre-start process, create the file [App_Name]/.openshift/action_hooks/pre_start_jbossas and edit the file to contain the desired information. Report a bug
6.5. Deployment
T he application deployment process involves making any required changes to the application code base, committing those changes to the local repository, and then updating the remote repository. Application files are stored in the local Git repository that was cloned as part of the application creation process. T he deployment process uses the application space as part of the build and test process, and requires the currently running application be shut down to use its memory. T herefore, the application will be unavailable for the duration of the build and all associated tasks, which are described below: 1. Pre-receive - T his occurs when git push command is run, but before the push is fully committed. 2. Build - T his builds an application, downloads required dependencies, executes the .openshift/action_hooks/build script and prepares everything for deployment. 3. Deploy - T his performs any required tasks necessary to prepare the application for starting, including running the .openshift/action_hooks/deploy script. T his step occurs immediately before the application is issued a start command. 4. Post-deploy - T his step enables interaction with the running application, including running the .openshift/action_hooks/post_deploy script. T his step occurs immediately after the application is restarted. Report a bug
6.5.1. Build and Deployment Action Hooks

Action hooks are specific files created to modify the processes 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 deployment are:
35
pre-build build deploy post-deploy Create a new file in the [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 , and edit the file to contain the desired information. Example 6.1. Adding an Action Hook to the Build Process T o download a file from another site during your application's build phase, create an [App_Name]/.openshift/action_hooks/build file, then add the following to the file's contents:
echo Downloading my.zip... curl -o $OPENSHIFT_DATA_DIR/my.zip http://myserver/my.zip
T he file is downloaded during the git push process. Report a bug
6.5.2. Preparing an Application for Deployment

T he rhc app create command creates a starting point to create and develop 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 $_ENV['OPENSHIFT _APP_NAME']/php/ or other directories. Procedure 6.3. T o Prepare an Application for Deployment Using the Command Line 1. Use the following command to add each new file and directory to the Git index:
$ git add path/to/newfile
2. Use the following command to commit an application to the local repository:

$ git commit -m "commit 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 Application to the Cloud Using the 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 push command is run, the application data is sent to the remote repository and the application is deployed by default. However, using the rhc deploym ent commands to configure the deployment process provides more options during the application deployment stage. Use the rhc configure-app commands to configure your application's deployment. Configuring Auto-deploy Use the --no-auto-deploy option to configure your application to not deploy automatically when your data is added to the remote repository with git push .
$ rhc configure-app -a App_Name --no-auto-deploy
Note that in this case, when the git push 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 then both git push and git deploy must be run. Change back to deploying automatically using the -auto-deploy option. Keeping Deployment Metadata Use the --keep-deploym ent x option to set your application to record its deployments. T his will help in performing a rollback to a previous deployment. Replace x with any number to record that number of 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
Deploying From a Git Branch 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 master
T his example command deploys the master branch. Other Git references are supported, such as commit SHA, branch, or tag. Listing Previous Deployments 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 Previous Deployment Roll back to a previously deployed version of your application with the rhc deploym ents command to obtain the desired deployment's ID, then run the following command:
$ rhc activate-deployment deploy_ID -a App_Name
Report a bug
37
6.5.4 .1. Deploying an Application From a Snapshot OpenShift Online supports deploying an application from a binary artifact. Use the --deploym ent option when saving a snapshot of an application to build a deployable version of your application.
$ rhc save-snapshot App_Name --deployment
Note
See Chapter 10, Backing Up and Restoring Application Data for full information on saving shapshots. T his command saves a .tar.gz snapshot of your application. Next, configure your application to binary deployments:
$ rhc configure-app App_Name --deployment-type binary
T his command changes your application's deployment procedure and disables the git push command, but enables your application to deploy binary artifacts. T he rhc 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 deploy http://foo.com/path/to/file.tar.gz -a App_Name
Report a bug
6.5.5. About Hot Deployment

When the git push command is run to upload code modifications, OpenShift Online stops, builds, deploys and restarts an application. T his entire process takes time to complete and is unnecessary for many types of code changes. Hot deploying an application enables the changes to take effect without restarting the application cartridge, thus increasing deployment speed and minimizing application downtime. OpenShift Online provides support for hot deployment through a hot_deploy marker file. If the marker is present, supported application cartridges automatically hot deploy when the git push command is executed.
38
T able 6.5. Application T ypes T hat Can or Cannot Be Hot Deployed T ype of Application JBoss Application Server JBoss Enterprise Application Platform T omcat 6 (JBoss Enterprise Web Server 1.0) T omcat 7 (JBoss Enterprise Web Server 2.0) PHP Perl Ruby Python Node.js Z end Server Jenkins HAProxy DIY Report a bug 6.5.5.1. Hot Deployment Build Details JBoss AS, JBoss EAP, T omcat 6, and T omcat 7 When JBoss AS, JBoss EAP, T omcat 6, and T omcat 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, Z end Server, Perl, Python, and Node.js When PHP, Z end Server, Perl, Python, and Node.js applications are hot deployed, the application code is built (dependencies are processed and user build action_hooks are run) and deployed to the application server. T he server does not restart. T his is true for both Jenkins and non-Jenkins enabled applications. For Jenkins enabled applications, the build is performed on a Jenkins slave instance and then synced to the gear(s) where the application server is running. Ruby When a Ruby application is hot deployed, the Passenger restart.txt file is touched, causing the application server to serve the new code without the need for a full server restart. For further details on this process, see the Passenger Documentation. Report a bug 6.5.5.2. Enabling and Disabling Hot Deployment Procedure 6.5. T o Enable Hot Deployment Open a terminal and run the command applicable to the operating system from the application's root directory to create the hot_deploy marker file: Windows Hot Deploy Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes No No No
39
C:\app_directory> copy NUL > .openshift\markers\hot_deploy
Linux and Mac

[user@user app_directory]$ touch .openshift/markers/hot_deploy
Procedure 6.6. T o Disable Hot Deployment Hot deployment is disabled by deleting the hot_deploy marker file. T o delete this file, run the command applicable to the operating system from the application's root directory: Windows
C:\app_directory> del .openshift\markers\hot_deploy
Linux and Mac

[user@user app_directory]$ rm .openshift/markers/hot_deploy
Report a bug
6.5.6. JBoss Application Deployment

6.5.6.1. Deploying on Java 6 or Java 7 T he JBoss AS 7 and JBoss EAP 6.0 applications can be run on either Java 6 or Java 7. T he Java version is specified by a java7 marker file in the application's m arkers directory. By default, new JBoss applications have the java7 marker enabled. Applications without the java7 marker are deployed using Java 6. Procedure 6.7. T o 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 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 Mac

[user@user [user@user [user@user [user@user 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 6.8. T o Use Java 6 Java 6 is enabled by deleting the java7 marker file. Run the commands applicable to the operating system from the application's root directory to delete the java7 marker file and update the remote repository:
40
Windows
C:\app_directory> del .openshift\markers\java7 C:\app_directory> git commit -a -m "Remove Java 7 marker" C:\app_directory> git push
Linux and Mac

[user@user app_directory]$ rm .openshift/markers/java7 [user@user app_directory]$ git commit -a -m "Remove Java 7 marker" [user@user 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 , .ear , .jar , and .sar files, in the JBoss Application Server (AS) or JBoss Enterprise Application Platform (EAP) deploym ents/ directory. T he file system deployment scanner in JBoss AS 7 and JBoss EAP 6.0 relies on a system of marker files. Add or remove various marker files and the scanner deploys, withdraws, or redeploys content based on the type of marker file. T hese 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 exam ple.war file is to be deployed is named exam ple.war.dodeploy. Option 1: Uploading Content in a Maven src Structure Content can be uploaded in a Maven src structure similar to the example ROOT .war file. When a git push is performed, the application is built and deployed. T his is the typical deployment option, and requires that the pom .xm l be stored at the root repository, and that the system has a maven-warplugin similar to the one in the example file to move the output from the build to the deploym ents/ directory. By default, the warName is ROOT within the pom .xm l file. T his will render the webapp contents at http://app_name-domain.example.com. If the warName is changed in pom .xm l to app_nam e , then the base URL would become http://app_name-domain.example.com/app_name.
Important
While building locally, add any output .war and .ear files in the deploym ents/ directory from the build to the .gitignore file. Option 2: Uploading Prebuilt Content git push can be used to push prebuilt .war files (with the corresponding .dodeploy file for exploded .war files) into the deploym ents/ directory.
41
Important
While applying this method using the default repository, first run git rm -r src/ pom .xm l from the root directory of the repository. If the pom .xm l file still exists, the build will run again and replace any prebuilt content. Report a bug 6.5.6.3. T ypes of Marker Files Different marker file suffixes have different meanings. T he relevant marker file types are as follows: T able 6.6. Sample T able Marker File T ype .dodeploy .deploying Description Placed by the user to indicate that the given content is to be deployed into the runtime (or redeployed if already deployed in the runtime.) Placed by the deployment scanner service to indicate that it has detected a .dodeploy file and is in the process of deploying the content. T his marker file is deleted when the deployment process completes. Placed by the deployment scanner service to indicate that the given content has been deployed to the runtime. If this file is deleted, the content will be withdrawn. Placed by the deployment scanner service to indicate that the given content failed to deploy to the runtime. T he content of this file will include some information about the cause of the failure. Placed by the deployment scanner service to indicate that it has detected a .deployed file has been deleted and the content is being withdrawn. T his marker file is deleted when the withdrawal process completes. Placed by the deployment scanner service to indicate that the given content has been withdrawn from the runtime. Deleting this file has no impact.
.deployed .faileddeploy
.undeploying
.undeployed
Report a bug 6.5.6.4 . Example JBoss Application Deployment Workflows T his section describes the basic workflows involved in deploying, withdrawing, and redeploying JBoss prebuilt applications to OpenShift Online. After running the desired commands, run git com m it and git push to deploy the changes to the application. T o Add New Z ipped Content and Deploy It Run the following command:
$ cp target/example.war deployments/
T o Add New Unzipped Content and Deploy It Run the following commands:
42
$ cp -r target/example.war/ deployments/ $ touch deployments/example.war.dodeploy
T o Withdraw Deployed Content Run the following command:

$ git rm deployments/example.war.dodeploy deployments/example.war
T o Replace Deployed Z ipped Content with a New Version and Deploy It Run the following command:
$ cp target/example.war deployments/
T o Replace Deployed Unzipped Content with a New Version and Deploy It Run the following commands:
$ git rm -rf deployments/example.war/ $ cp -r target/example.war/ deployments/ $ touch deployments/example.war.dodeploy
Report a bug
6.6. About Jenkins Online Build System

Jenkins integrates with other OpenShift Online applications. T o start building with Jenkins, Jenkins Client must be added to an existing application. From then on, running a git push command initiates a build process inside a Jenkins builder instead of inside the normal application compute space. For custom applications, or applications that have no upstream repositories, the build process can be initiated directly from the Jenkins web interface, without having to run the git push command. Using the embedded Jenkins Client build system provides 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 memory and storage A large community of Jenkins plug-ins Report a bug
6.6.1. Configuring Jenkins

T his section describes how to set up Jenkins to rebuild an application automatically when changes are made to a local repository and then to push those changes to the remote repository. Report a bug 6.6.1.1. Resource Requirements for Jenkins T he 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 is created and MySQL database
43
is on the first gear, then Jenkins will be added to a separate gear. A third gear 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. Creating Jenkins-enabled Applications

Jenkins can be enabled with new applications, either scaled or non-scaled. Use the rhc app create 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. Creating a Scaled Jenkins-Enabled Application Use the rhc app create command with the -s (or --scaling) option to create a scaled application, and the --enable-jenkins option to add the Jenkins client to your application. If a cartridge type is specified with multiple versions, the client tools will prompt you to specify the version to use.
$ rhc app create App_Name php --enable-jenkins -s
Important
T ake note of the login credentials that this command outputs to the screen. T hese credentials will be required to log in to the Jenkins home page. Report a bug 6.6.2.2. Creating a Single-Instance Jenkins-Enabled Application Use the rhc app create 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 to specify the version to use. T ake note of the login credentials that this command outputs to the screen. 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 confirm that the Jenkins-enabled application has been created. T his can also be verified by navigating to the public URL returned by the rhc app create command to view the Jenkins home page.
44
Report a bug
6.6.3. Building Applications with Jenkins

Building applications with Jenkins uses dedicated application space, which can be larger than the application runtime space. T he Jenkins online build system monitors applications that have an embedded Jenkins Client, and automatically rebuilds and deploys those applications whenever changes to the Git repository are pushed to the remote server. No further interaction is required by the user. T he existing application is not affected until a new, successful build has been created. Should the build fail, the existing application continues to run, although a failure in the deployment process (deploy - start post_deploy) may leave the application partially deployed or inaccessible. T he actual build and deployment process that Jenkins executes involves numerous steps, as described below. 1. T he user issues a git push command, and Jenkins is notified that a new push is ready. 2. A dedicated Jenkins slave (a builder) is created. T he rhc apps command can be used to display this slave information. T he application name is the same as that of the originating application, but with a "bldr" suffix.
Important
T he first 28 characters of the application name must be unique, or builders will be shared across applications. T his can lead to build issues. 3. Jenkins runs the build. 4. Content from the originating application is downloaded to the builder application using git (for source code) and rsync (for existing libraries). 5. ci_build.sh is called from the Jenkins shell. T his sets up the builder application for the Jenkins environment and performs some built-in bundling steps (PHP pear processing, Python virtual environment, etc). 6. .openshift/action_hooks/build is executed on the Jenkins builder. 7. Any additional desired steps are executed from the Jenkins shell (Maven build, Gem install, test cases, etc). 8. Jenkins stops the currently running application, and runs rsync to synchronize all new content over to the originating application. 9. .openshift/action_hooks/deploy is executed on the originating application. 10. Jenkins starts the originating application, and .openshift/action_hooks/post_deploy is executed on this application. 11. Jenkins archives all build artifacts for later reference. 12. After 15 minutes of idle time, the "build app" will be destroyed and will no longer appear in the output of the rhc apps command. T he build artifacts, however, will still exist in Jenkins and can be viewed there. T he build job can be monitored using the Jenkins interface. T he 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. T he following is an example build history of an 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. Replace jenkins with the Jenkins application name in the following, if different:
$ rhc 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
Report a bug 6.6.3.1. Building Custom Applications Build custom applications, or applications that have no upstream repositories, directly from the Jenkins web interface instead of using the git push command. T o build an application from the Jenkins web interface, click on the located on the right side of the interface. icon for the application to build,
T he status of the build process can be viewed in the web interface under the section labeled Build Executor 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 Console Click on the Applications tab in the Management Console, then click on the desired application to delete it. Click on the Delete this application button and follow the instructions on the screen. Client T ools Run the following command to delete all the remote data for your application, typing yes when prompted:
T his 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 procedure deletes the selected directory and all the files it contains. Enter the correct directory and ensure the files it contains are no longer needed before running this command. Procedure 6.9. T o Delete Local Application Data Open a terminal and use the following command to delete the application data stored on the local machine:
$ rm -rf ~/path/to/app_directory/
Report a bug
6.8. Gears and Storage Management

As an application is developed and the changes are pushed to the Git repository, the amount of disk space that is available to run the application is slowly reduced. T his is because Git stores all repository information, whether it is still required or not. Other aspects of developing and running applications also result in wasted disk space, such as old log files and unused application libraries. In such cases either additional storage is required, or the existing disk space is optimized to achieve the best possible performance of the applications. . T his section describes how to use the OpenShift Online client tools to add additional gear storage, and to manage the existing disk space to optimize application performance. Refer to rhc cartridge storage --help for a list of all available command options.
Note
Free plan users must upgrade their OpenShift Online subscription for additional gear storage. Log onto the Management Console, and click My Account to view upgrade options before attempting to increase the gear storage. Management Console Click the Applications tab in the Management Console, then click on the desired application to manage its gear storage. Click on the current gear storage of the cartridge you wish to alter, then choose the new desired amount. Click Save to commit your changes. Report a bug
6.8.1. Viewing Gear Storage

Use the rhc cartridge storage command with the --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 Gear Storage: 1GB Additional Gear Storage: 3GB OpenShift Web Balancer ---------------------Base Gear Storage: 1GB Additional Gear Storage: None PHP 5.3 ------Base Gear Storage: 1GB Additional Gear Storage: None
Use the rhc cartridge storage command with the -c option to view gear storage for a specific cartridge that exists in an application, as shown in the example below.
$ rhc cartridge storage --show -a App_Name -c php-5 RESULT: PHP 5.3 ------Base Gear Storage: 1GB Additional Gear Storage: None
Report a bug
6.8.2. Adding Gear Storage

Use the rhc cartridge storage command with the --add option to add a specified amount of gear storage to your application.
$ rhc cartridge storage php-5.3 -a App_Name --add 3gb Set storage on cartridge ... set to 3GB Storage Info -----------Base Gear Storage: 1GB Additional 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 with the rhc cartridge storage command to set the amount of gear storage of an application. T his is different from the --add option in that you are specifying the amount of gear storage rather than adding more.
48
$ rhc cartridge storage php-5 -a App_Name --set 5gb Set storage on cartridge ... set to 5GB Storage Info -----------Base Gear Storage: 1GB Additional Gear Storage: 5GB
Report a bug
6.8.4. Removing Gear Storage

Use the rhc cartridge storage command with the --rem ove option to remove a specified amount of gear storage.
$ rhc cartridge storage php-5 -a App_Name --remove 3gb Set storage on cartridge ... 2GB Storage Info -----------Base Gear Storage: 1GB Additional Gear Storage: 2GB
Report a bug
6.8.5. Managing Application Disk Space

OpenShift provides tools to optimize the disk space to help achieve the best possible performance of the applications. Report a bug 6.8.5.1. Disk Space Cleanup T ool T he Disk Space Cleanup Tool can help manage an application disk space. T his tool is part of the rhc app command suite, and performs the following functions: Runs the git gc command on the application's Git repository on the server Clears the application's /tm p and log file directories. T hese are specified by the application's OPENSHIFT _<cartridge>_LOG_DIR and OPENSHIFT _T MP_DIR environment variables.
Important
OpenShift Online does not automatically back up or rotate log files. T he Disk Space Cleanup T ool runs the rm -rf command to clear the contents of these directories. T o save their contents, use the rhc snapshot save command first to create a snapshot of the system. Clears unused application libraries. T his means that any library files previously installed by a git push command are removed. T he Disk Space Cleanup T ool uses the following syntax:
$ rhc app tidy App_Name
Report a bug
49
50
Chapter 7. Application Management

7.1. Application Management Commands
Use the rhc app command to manage your applications, view application status, and start, stop, restart, reload and delete applications. Run rhc app --help for more information and a full list of the available options.
$ rhc app action App_Name [Optional Arguments]
T he following table describes the application management command options that you can use to manage an existing application in the cloud. T able 7.1. Application Management Command Argument Options Option start stop force-stop restart reload status show tidy create git-clone delete Report a bug Details Start an application. Stop an application. Stops all application processes. Restart an application. Reload an application. Display the current status of an application. Show information about an application. Clean out the application's logs and tmp directories and tidy up the Git repo on the server. Create an application and add it to a domain. Clone and configure an application's repository locally. Remove an application.
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. T he shell access provides specialized tools for managing your applications. Using the shell environment to access your OpenShift Online applications is protected and restricted with Security-Enhanced Linux (SELinux) policies.
Important
Shell access is quite powerful and it is possible to accidentally damage an application. T herefore it is recommended you only use shell access when necessary. Report a bug
7.2.1. Accessing an Application

Use the rhc app ssh command to access an application in a secure shell environment. After you have
51
gained shell access, you can run the 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. T he following example below shows a connection to the application racer .
$ rhc app ssh racer Connecting to 517623ecdbd93cdffa000001@racer-automobile.example.com ...
********************************************************************* You are accessing a service that is for use only by authorized users. If you do not have authorization, discontinue use at once. Any use of the services is subject to the applicable terms of the agreement which can be found at: https://www.openshift.com/legal
********************************************************************* Welcome to OpenShift shell This shell will assist you in managing OpenShift applications. !!! IMPORTANT !!! IMPORTANT !!! IMPORTANT !!! Shell access is quite powerful and it is possible for you to accidentally damage your application. Proceed with care! If worse comes to worst, destroy your application with 'rhc app delete' and recreate it !!! IMPORTANT !!! IMPORTANT !!! IMPORTANT !!! Type "help" for more info. [racer-automobile.example.com 517623ecdbd93cdffa000001]\>
Report a bug
7.2.2. Accessing a Specific Gear

T he rhc app ssh command opens a shell to the head gear of an application. T his process can be used to debug a gear problem in a scaling application. T o access a different gear you must first determine a specific gear's ID and SSH URL:
$ rhc app show hybrid --gears ID State Cartridges Size SSH URL ------------------------ ------- ------------------- ----- --------------------------------------------------------------------------51774b712587c83ddb00009d started php-5.3 haproxy-1.4 small 51774b712587c83ddb00009d@hybrid-automobile.example.com 519b0fd02587c84b860002d8 started php-5.3 haproxy-1.4 small 519b0fd02587c84b860002d8@519b0fd02587c84b860002d8-automobile.example.com 519b1018dbd93c85180001fc started php-5.3 haproxy-1.4 small 519b1018dbd93c85180001fc@519b1018dbd93c85180001fc-automobile.example.com 519b06ebdbd93cd439000027 started postgresql-9.2 small 519b06ebdbd93cd439000027@519b06ebdbd93cd439000027-automobile.example.com
For example, in the output above the ID of the first scaling gear is 519b0fd02587c84 b860002d8 and its SSH URL is 519b0fd02587c84 b860002d8@ 519b0fd02587c84 b860002d8autom obile.exam ple.com .
52
Use the 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 database can be verified by connecting to an application using SSH and running the shell for the database. A successful connection to the database shell indicates that the database has been created correctly. T he shell for each database also offers a selection of commands that can be used to manage a database. See the selected database's documentation for more information on the database shell commands available.
Important
Shell access is quite powerful and it is possible to damage an application accidentally. T herefore it is recommended to use shell access only when necessary. Procedure 7.1. T o Manage a Database in a Shell Environment 1. Use the rhc app ssh command to access the desired application in a shell environment. T he 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 at the shell prompt to see the shell commands available.
53
$ rhc app ssh racer Password: ********** Connecting to 517623ecdbd93cdffa000001@racer-automobile.example.com ...
****************************************************************** *** You are accessing a service that is for use only by authorized users. If you do not have authorization, discontinue use at once. Any use of the services is subject to the applicable terms of the agreement which can be found at: https://www.openshift.com/legal
****************************************************************** *** Welcome to OpenShift shell This shell will assist you in managing OpenShift applications. !!! IMPORTANT !!! IMPORTANT !!! IMPORTANT !!! Shell access is quite powerful and it is possible for you to accidentally damage your application. Proceed with care! If worse comes to worst, destroy your application with 'rhc app delete' and recreate it !!! IMPORTANT !!! IMPORTANT !!! IMPORTANT !!! Type "help" for more info. [racer-automobile.example.com 517623ecdbd93cdffa000001]\>
2. Access the interactive database shell by running the appropriate command for the database: m ysql : interactive MySql shell psql : interactive PostgreSQL shell m ongo : interactive MongoDB shell For example, to open the interactive PostgreSQL shell:
[racer-automobile.example.com 515e21acdbd93c051d000022]\> psql psql (8.4.13) Type "help" for help. racer=#
Report a bug
7.3. Environment Variables

Environment variables are named values that change the way running processes behave in computing environments. T hey can be used to provide a variety of different environmental values: application names, commonly accessed directory names, usernames, passwords, hostnames, and IP addresses. Your application reads the environment variables and uses the information to configure itself for the OpenShift environment.
54
T he 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 variables for an application: 1. Add an export statement to the App_Name/.openshift/action_hooks/build file, then run git push . T he variables are listed in the Git output and start with rem ote: declare -x. 2. Use SSH to gain shell access to your application and run the env command at the shell prompt. Report a bug
7.3.1. Informational Environment Variables

T hese variables provide information about your application. T able 7.2. Informational Environment Variables Environment Variable Name OPENSHIFT _APP_DNS OPENSHIFT _APP_NAME OPENSHIFT _APP_UUID OPENSHIFT _<cartridge>_I P OPENSHIFT _<cartridge>_P ORT OPENSHIFT _SECRET _T OKEN Example App_NameDomain.example.com App_Name 0123456789abcdef0123456789 abcdef 127.0.250.1 8080 Purpose T he application's fully-qualified domain namespace T he application's name T he UUID of the application (32 hex characters) T he IP address the application listens on T he port the application receives requests from A 128 character string unique to an application that may be used for authentication, and can be overridden with the rhc setenv command
Report a bug
7.3.2. Directory Environment Variables

T hese variables return the directories where your application resides. Note that the only directory that is guaranteed never to be deleted is OPENSHIFT _DAT A_DIR .
55
T able 7.3. Directory Environment Variables Environment Variable Name OPENSHIFT _HOMEDIR OPENSHIFT _DAT A_DIR OPENSHIFT _<cartridge>_L OG_DIR OPENSHIFT _<database>_DB _LOG_DIR OPENSHIFT _REPO_DIR Example /var/lib/openshift/51774b763817 c83ddb00009d/ $OPENSHIFT _HOMEDIR/approot/data/ $OPENSHIFT _HOMEDIR/<cartri dge>/logs/ $OPENSHIFT _HOMEDIR/<data base>/logs/ $OPENSHIFT _HOMEDIR/approot/runtime/repo/ /tmp/ Purpose T he application's home directory A persistent data directory Where cartridge-specific logs are stored Where database-specific logs are stored Repository containing the currently deployed version of the application A temporary directory you can use; SELinux protects data in this directory from other users
OPENSHIFT _T MP_DIR
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 to your database. T he exact variable names depend on the database type; the value of <database> is MONGODB, MYSQL, or POST GRESQL as appropriate. Note these connections are only available to your application internally; you cannot connect from an external source. OpenShift Online does not currently support user changes to environment variables. T his includes changing the default MySQL admin password (even outside of phpMyAdmin). If you change your password, ensure that the change takes effect correctly. Note that this restriction only applies to the default administrative user. You can add more users as required, and specify a password of your own choosing for these users. T able 7.4 . Database Environment Variables Environment Variable Name OPENSHIFT _<database>_DB _HOST OPENSHIFT _<database>_DB _PORT OPENSHIFT _<database>_DB _USERNAME OPENSHIFT _<database>_DB _PASSWORD OPENSHIFT _<database>_DB _SOCKET OPENSHIFT _<database>_DB _URL Example 127.0.250.1 3306 admin 8ddT nst22X3Y $OPENSHIFT _HOMEDIR/mysql5.1/socket/mysql.sock mysql://admin:8ddT nst22X3Y@1 27.0.250.1:3306/ Purpose T he hostname or IP address used to connect to the database T he port the database server is listening on T he database administrative username T he database administrative user's password An AF socket for connecting to the database (for non-scaled apps only) 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. T able 7.5. Jenkins Environment Variables Environment Variable Name JENKINS_USERNAME JENKINS_PASSWORD JENKINS_URL Example system_builder RnmXQlavsb4f https://jenkinsdomain.example.com/ Purpose System builder account on the Jenkins server Password for the system builder account on the Jenkins server DNS name for the associated Jenkins server where builds occur
Report a bug
7.3.5. Gear Environment Variables

T hese variables apply to scaling applications. T able 7.6. Gear Environment Variables Environment Variable Name OPENSHIFT _GEAR_DNS OPENSHIFT _GEAR_NAME OPENSHIFT _GEAR_UUID Example gearname-domain.example.com gearname 0123456789abcdef0123456789 abcdef Purpose T he gear's fully-qualified domain name T he gear's name T he gear's UUID
Report a bug
7.3.6. JBoss Environment Variables

T he table below shows the environment variables pertaining to supported JBoss applications on OpenShift Online. T able 7.7. JBoss Environment Variables Environment Variable Name JAVA_OPT S JAVA_OPT S_EXT Purpose Controlled by the cartridge and used to specify additional arguments to the JVM where JBoss application will run. Appended to the JAVA_OPT S environment variable before the JVM is invoked, and used to provide additional options to the JVM without rewriting the JAVA_OPT S environment variable. T his allows developers to better support their application users.
JBoss environment variables are stored in the /App_Name/.openshift/config/standalone.xm l file that is part of jbossas-7. T he example code below shows the environment variables for a MySQL datasource connection URL in the form jdbc:mysql://SERVER_NAME:PORT/DATABASE_NAME:
57
<connectionurl>jdbc:mysql://${env.OPENSHIFT_MYSQL_DB_HOST}:${env.OPENSHIFT_MYSQL_DB_PORT}/${e nv.OPENSHIFT_APP_NAME}</connection-url>
T he environment variables can be saved on the server so that sensitive information does not have to be passed repeatedly to the command line. Procedure 7.2. T o Set Environment Variables on the Server 1. Open the App_Name/.openshift/config/standalone.xm l file. 2. Specify the required values for any of your environment variables, then save and close the file. 3. Commit and push the changes to the server:
$ git commit -a -m " COMMIT MESSAGE" $ git push
Important
Sensitive information stored in your environment variables is visible if you use the rhc snapshot commands. Report a bug
7.3.7. Custom Environment Variables

OpenShift Online enables you to set custom environment variables for your 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 separated by spaces:
$ rhc env set Variable=Value Variable2=Value2 -a App_Name
Viewing Custom Environment Variables View the custom environment variables set for an application using the following command:
$ rhc env list -a App_Name
Viewing the Value of a Custom Environment Variable Display the value of one or more custom environment variables using the following command:
$ rhc env show Variable Variable2 -a App_Name
Removing Custom Environment Variables Remove a custom environment variable using the following command:
$ rhc env unset Variable -a App_Name
58
Report a bug
7.4. About Node.js Applications

T his section provides the basic information required for running Node.js applications on OpenShift Online. Report a bug
7.4.1. Repository Layout

When you create a new Node.js application on OpenShift Online, the application directory is populated with several files. T he following table displays this layout: T able 7.8. Node.js Repository Layout File node_modules/ deplist.txt npm_global_module_list server.js package.json README .openshift/ .openshift/action_hooks/pre_bui ld .openshift/action_hooks/build .openshift/action_hooks/deploy .openshift/action_hooks/post_d eploy Use Node modules packaged with the application. Deprecated list of npm modules to install with the application. List of globally installed and available npm modules. OpenShift Online sample Node application. Package descriptor for npm. Information about using Node.js with OpenShift Online . Location for OpenShift Online specific files. Script that runs every git push , but before the build. Script that runs every git push during the build process (on the CI system if available). Script that runs every git push after the build, but before the application is restarted. Script that runs every git push , but after the application is restarted.
You can create additional directories if needed, but do not delete the node_m odules and .openshift directories.
Note
When you git push , everything in your remote repository directory is recreated. Place items that you want to persist between pushes, such as a database, in the ../data directory on the gear where your OpenShift Online application is running. Report a bug
7.4.2. Installing Node Modules

If you want to install Node modules from the npm registry, you can specify the modules in the package.json file. Package.json describes how your package is structured and is used by npm to install and manage your application. T he dependencies hash in the package.json file can be used to specify the Node modules (and optionally the version) to install alongside your application ("locally") on
59
the OpenShift Online environment when you git push your application. For more information, see https://npmjs.org/doc/json.html. Example package.json entry:
"dependencies": { "coffee-script": "connect": "*", "1.3.3",
"optimist": "<=0.3.4", "socket.io": "" },
Node modules not included in the npm registry can be installed by packaging them in the node_m odules directory. T he npm _global_m odule_list file contains a list of globally installed modules. You can override a globally available module by specifying it in package.json or by packaging it in the node_m odules directory. Node gives preference to the "locally" installed version of that module. Report a bug
7.5. Scheduling Timed Jobs with Cron

Use the OpenShift Online cron scheduler to set up timed jobs for your applications. T his consists of adding the cron scheduler cartridge to your application, adding the required cron jobs to the appropriate directories, and then updating the remote Git repository. You can also use the rhc cartridge command to enable or disable your cron scripts. T he following example demonstrates how to create a new application and enable cron support. Note that if you specify a cartridge type with multiple versions, the client tools prompt you to specify the version to use. Procedure 7.3. T o Create an Application and Enable Cron Support 1. Create a new application:
$ rhc app create holy php
2. Add the cron scheduler cartridge to your new application:

$ rhc cartridge add cron -a holy
3. Add the cron jobs to your application's .openshift/cron/{m inutely,hourly,weekly,daily,m onthly}/ directories. For example:
$ mkdir -p .openshift/cron/minutely $ echo 'date >> $OPENSHIFT_REPO_DIR/php/date.txt' > .openshift/cron/minutely/date.sh
60
4. Commit your changes and push them to the remote repository.

$ git add .openshift/cron/ $ git commit -m "configuring cron jobs" $ git push
T his example appends a new line of date information to the $OPENSHIFT _REPO_DIR/php/date.txt file every minute. Use the curl command to verify the operation of this script:
$ curl http://holy-roller.example.com/date.txt Thu Feb Thu Feb Thu Feb 2 01:02:01 EST 2012 2 01:03:01 EST 2012 2 01:04:01 EST 2012
T he scripts that you place in the /cron subdirectories are executed at the respective frequencies. Scripts in each subdirectory are executed sequentially, in alphabetical order. Scripts in the /cron/hourly directory are executed on the first minute of every hour. You can use the rhc cartridge command to enable or disable your cron scripts. For example, to disable all of your scripts:
$ rhc cartridge stop cron -a holy
T o enable all of your scripts:

$ rhc cartridge start cron -a holy
Note
T he cron commands affect all cron jobs. You cannot disable or enable individual cron jobs. Report a bug
7.6. Available Ports for Binding Applications

All ports less than 1024 are reserved for OpenShift Online operations. Developers will not be able to bind to these ports. However, ports greater than 1024 are available for binding. T he following table displays the commonly used ports for binding.
Important
While the following ports are suggestions for available applications or gears, ports 2303-2308 are reserved for OpenShift SNI Implementation, and port 10050 is reserved for the OpenShift OpenShift Online Z abbix agent. You will not be able to bind to these ports.
61
T able 7.9. Common Ports and T heir Usage Application Name Kerberos Port Number 4444 Description Kerberos is used for user authentication identifying with a node. Git is used for version control. My Structured Query Language (MySQL) acts as a server providing access to databases. MongoDB acts as a server providing access to databases. PostgreSQL acts as a server providing access to databases. MS SQL acts as a server providing access to databases. Oracle acts as a server providing access to databases. Hypertext T ransfer Protocol Secure (HT T PS) is used for secure communication over a server. HT T P cache is used for the temporary storage of documents. memcache is a memory caching system. JacORB is a Java request broker. A debug program for JBoss applications. A management program for JBoss applications. Advanced Message Queuing Protocol (AMQP) is used to transfer messages between applications. PulseAudio is a server that manages the use of audio devices. Flash is a multimedia platform. Munin is a network monitoring application. Virt migration is the copying of one machine's data and moving it to another. Online Certificate Service Protocol (OCSP) is a protocol used for obtaining the status of
Git MySQLd
9418 3306, 63132-63164
Mongod PostgreSQL MS SQL Oracle HT T P/HT T PS
27017 5432 1433-1434 1521, 2483, 2484 8008, 8009, 8443
HT T P cache
8080, 8118, 8123, 1000110010 11211 3528, 3529 8787 4712, 4447, 7600, 9123, 9990, 9999, 18001 5671-5672
memcache jacORB JBoss Debug JBoss Management AMQP
PulseAudio
4713
Flash Munin Virt Migration
1935 4949 49152-49216
OCSP
9080
62
a certificate. You can also bind to the internal IP through ports 15000-35530, which are not externally addressable. You can also bind to $ OPENSHIFT _CartridgeShortName_PORT (8080) for http connectivity, which will reroute externally through port 80. Report a bug
7.6.1. WebSocket Port Configuration

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 multiple, open HT T P connections. T he T CP-based protocol uses HT T P as an initiation handshake, which is treated as an upgrade request. If successful, the connection remains open and switches to the WebSocket protocol. For plain WebSocket connections (ws://), requests should be directed to port 8000, while WebSocket Secure connections (wss://) should use port 8443. For 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 SMT P). 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, you can also take advantage of this feature by altering the email settings of the software to point to the appropriate email service. T he following ports are the suggested options for email support: SMT P/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 (SMT P) and 465 (SMT PS) are restricted to a maximum rate of 24 Kbps. Both will consume an extremely small share of the available bandwidth if congestion exists.
Important
Be aware that access to email servers from cloud providers may be blocked by Realtime Blackhole Lists (RBLs). T his 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. T his section describes how OpenShift Online 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 Online client tools, the interactive setup wizard generates a new pair of SSH keys in the default .ssh folder of your home directory. T he SSH key pair consists of the public key, id_rsa.pub , and the private key, id_rsa . As part of the initial configuration, you have the option of automatically uploading the public key, id_rsa.pub , to the OpenShift Online server. See the Client Tools Installation Guide for more information about client tools configuration. Management Console Click the 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

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

T he rhc sshkey show command displays details of the key specified:
$ rhc sshkey show KeyName KeyName (type: ssh-rsa) ----------------------Fingerprint: d2:0f:1b:8d:3e:07:0b:5a:14:df:2a:44:15:f0:e7:fc
Report a bug
64
Chapter 8. Authentication and SSH Keys
8.3. Generating Keys Manually

T he ssh-keygen command generates a new pair of RSA or DSA keys as specified. Procedure 8.1. Generating SSH Keys Manually 1. Run the ssh-keygen command, replacing KeyType with the type of key you want to generate, either dsa or rsa:
$ ssh-keygen -t KeyType
2. When prompted for the file in which to save the key, press Enter to save the key in the default location (/home/username/.ssh/) with the default name:
... Generating public/private rsa 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, 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 prompted for a passphrase, enter a passphrase or leave blank for no passphrase then press Enter :
Enter passphrase (empty for no passphrase): Enter same passphrase again: Your identification has been saved in /home/username/.ssh/id_rsa Your public key has been saved in /home/username/.ssh/id_rsa.pub. ...
Report a bug
8.4. Adding a Key

T he rhc sshkey add command uploads the specified public key to the OpenShift Online server. Replace KeyName and 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 --content options to create a specific type of 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 KeyType --content KeyContent
Report a bug
8.4.2. Removing a Key

T he rhc sshkey rem ove 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 system. T his can cause connection issues, 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) Manually generate and add SSH keys Report a bug
8.5.1. Resolving Issues with Interactive Setup Wizard

T he recommended method of resolving authentication issues is to use the interactive setup wizard to generate a new pair of SSH keys. T he interactive setup wizard also provides the option of automatically uploading your new public key to the OpenShift Online server. Use the rhc setup command to launch the setup wizard, then follow the onscreen instructions. See the Client Tools Installation Guide for more information about the OpenShift Online client tools interactive setup wizard. Report a bug
66
Chapter 9. Monitoring and Troubleshooting

9.1. Monitoring Application Resources
As described in Section 6.1.1, About Scaled Applications, scaled applications are automatically allocated additional resources based on demand. T he amount of resources consumed by an application can be monitored and viewed from the OpenShift Online Management Console. Follow the instructions below to monitor and view application resources. T he instructions below assume that a scaled application has already been created. Procedure 9.1. T o Monitor Application Resources 1. Access the OpenShift Online Management Console. 2. Click on the My Applications tab to view all of your applications and click on the name of the scaled application you want to examine. 3. T he OpenShift Online Management Console displays the number of gears, along with the size of the gears, used by the selected application. 4. Hover over the gear size information with your mouse to display a popup message with more detailed information. 5. Scaling is performed by the HAProxy cartridge. Click See HAProxy status 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. T he 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 Service (MMS)

T he MongoDB Monitoring Service (MMS) is a cloud-based monitoring service, designed by 10gen, to monitor the health of MongoDB deployments. MMS provides an agent that runs on MongoDB servers, and this agent reports information such as opcounters, memory information, number of 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 same commands as for other cartridges. T he only prerequisite for using MMS is that you have an account with 10gen; you can sign up for a free MMS account at https://mms.10gen.com/. Report a bug
9.2.1. Configuring an Application with MMS

T he following procedure describes how to configure your application to take advantage of the services provided by MMS. T his procedure assumes that you have successfully created an application and added the MongoDB cartridge. Procedure 9.2. How to set up your application to use MMS
67
1. Download the agent from https://mms.10gen.com/. When you log into MMS, you will see a Download the Monitoring 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 with the following command, replacing app_directory with the root directory for your application:
$ mkdir ~/app_directory/.openshift/mms
3. Add the settings.py file to the m m s directory:

$ cp ~/mms-agent/settings.py ~/app_directory/.openshift/mms/
Important
T he settings.py file contains the MMS agent settings that contain the API keys for connecting to your MMS account and updating the monitoring metrics. T he MMS agent will not function without this file. 4. Use Git to add and commit the m m s directory to your local repository, then push it to your remote repository:
$ $ $ $ cd app_directory/ git add .openshift/mms/ git commit -m "mms settings" -a git push
5. Use the following command to add the agent to your application:

$ rhc cartridge add 10gen-mms-agent-0 -a App_Name
After successfully completing this procedure, navigate to the https://mms.10gen.com/ page, enter your host's details and start monitoring your application. Report a bug
9.2.2. Monitoring Applications with MMS

Report a bug 9.2.2.1. Adding Hosts to 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/. T o 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@ App_Name-Domain.example.com
where UUID is the UUID of your application. You can retrieve this using the rhc apps command. Replace App_Name and Domain with your application name and domain, respectively.
68
2. Run the following command to retrieve all the necessary connection and credential information for your application:
> echo $OPENSHIFT_MONGODB_DB_URL
Procedure 9.3. How to add hosts to MMS 1. Navigate to https://mms.10gen.com/ and login to your account. 2. Click the Hosts + button at the top of the page to display the New Host dialog box. 3. Enter the required details and then click Add . T his adds the host details to the agent, which immediately starts collecting and storing data. Report a bug 9.2.2.2. MMS 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 to monitor your applications with MMS 1. Navigate to https://mms.10gen.com/, login to your account, and click the Hosts tab. 2. Click the name of the host that you want to monitor to view the available data collection streams. You can customize this page to suit your own requirements. See the 10gen documentation for full details. Report a bug
9.3. Troubleshooting JBoss Applications

OpenShift Online provides some basic tools to help you troubleshoot your JBoss applications should problems arise. T his includes the ability to inspect the log files and also to trigger a thread dump for JBoss applications. Report a bug
9.3.1. Debugging with Thread Dumps

T hread dumps are a useful debugging tool. If an application appears to have stalled or is running out of resources, a thread dump can help to reveal the state of the server, to identify what might be causing any issues and ultimately to resolve the problem. You can use the rhc threaddum p command to trigger a thread dump for a JBoss application. T he following example demonstrates the use of this command:
Note
T his example assumes that you have a valid account and have already created a domain and JBoss application called "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 to inspect the resultant thread dump:
$ rhc tail myJBoss -f /tmp/jbossas.log -o '-n 250' Password: ********** <sample output> Heap def new generation total 18240K, used 4240K [0xdd580000, 0xde940000, 0xe2ad0000) eden space 16256K, 24% used [0xdd580000, 0xdd956930, 0xde560000) from space 1984K, 15% used [0xde750000, 0xde79d9a0, 0xde940000) <output truncated>
Report a bug
9.3.2. Inspecting Server, Boot and Other Log Files

T he rhc 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/ directory. T he example below shows abbreviated output from this command.
$ rhc tail myJBoss Password: ********** ==> jbosseap-6/logs/server.log <== 2013/01/02 02:06:37,144 INFO [org.jboss.as.osgi] (MSC service thread 1-1) JBAS011907: Register module: Module "deployment.ROOT.war:main" from Service Module Loader ==> jbosseap-6/logs/boot.log <== user.name = 1ca72484953b4701a4d32be920bcefc1 user.timezone = America/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 <output truncated>
T he rhc tail command provides the same output as if you directly log into an application instance and run the rhc tail_all command. It shows the services running on the application's behalf in real time. T ailing Specific Gears Inspecting application log files on specific gears is helpful for diagnosing 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 Specific 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 App-Name -g gear_ID
T he log displays on the command screen, and updates every few seconds. Report a bug
9.4. Performing Application Maintenance from Workstation

9.4.1. Port Forwarding
Ports on a remote server can be forwarded to your workstation, making it easy to manage services such as MySQL. T he rhc port-forward command provides a wrapper for the ssh command, and determines which remote ports to forward to your workstation.
Note
Ensure that your application is running before attempting to configure port forwarding. T he example below shows remote ports for the App_Name application being forwarded locally:
$ rhc 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 ----------haproxy haproxy httpd mysql Local OpenShift --------------- ---- -------------------------------------------------127.0.0.1:8080 127.0.0.1:8081 127.0.0.1:8082 127.0.0.1:50226 => => => => 127.9.159.130:8080 127.9.159.131:8080 127.9.159.129:8080 52347a1d2587c86695111697-mydomain.rhcloud.com: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. T he current implementation of the rhc port-forward 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 services are being bound to local ports. For forwarding specific ports, use the ssh command with the -L option. T his specifies the local port you wish to forward to the remote port. For example:
$ ssh -L 8080:localhost:8080
T his command allocates a socket to listen to the local port host 8080 (the first number). When a connection to this port is made, a secure channel forwards the connection to the remote host port 8080 (the second number). Port Forwarding Specific Gears Port forwarding specific gears to diagnose problems on secondary gears makes examining problems with scaled applications easier. In order to port forward specific gears, first determine the gear's ID. See Section 7.2.2, Accessing a Specific Gear for details on how to determine a specific gear's ID. Run the following command to port forward a specific gear, replacing App_Nam e 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 -g 522d59745973caccab0000c1 Checking available ports ... done Forwarding ports ... To connect to a service running on OpenShift, use the Local address Service Local OpenShift ------- -------------- ---- ------------------httpd 127.0.0.1:8080 => 127.12.166.129:8080 Press CTRL-C to terminate port forwarding
Report a bug 9.4 .1.1. Port Forwarding 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 may experience error messages similar to those shown below when attempting to configure port forwarding using the IP address for your OpenShift Online application.
$ rhc port-forward App_Name Checking available ports... Error trying to forward ports. You can try to forward manually by running: ssh -N 70277280b8534c8a9fc76d2734393dfa@app01-domain.example.com
72
T he current workaround to enable port forwarding on Mac OS X is to configure an alias manually using the ifconfig command for each IP address used by your application, using the command as shown below:
$ sudo ifconfig lo0 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 ifconfig lo0 alias 127.10.51.129
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 phpMyAdmin cartridges added, and it uses the IP addresses 127.11.25.1 and 127.11.25.2. T o correctly enable port forwarding, you must configure an alias for each IP address, as shown in the example below.
$ sudo ifconfig lo0 alias 127.11.25.1 $ sudo ifconfig lo0 alias 127.11.25.2
Note
T he ifconfig command on Mac OS X requires root/administrative privileges to execute. You can now use the rhc port-forward command to enable port forwarding.
Important
T he IP address alias you configure for your OpenShift Online application is not persistent through system reboots. If you reboot your computer, 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 snapshot save command to create backups of your OpenShift Online applications, and also to restore those backups to the server. As a back-up tool, this command creates a 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. T he directory structure that exists on the server is maintained in the tar file.
Important
OpenShift Online does not maintain backups of your applications or user data on the OpenShift Online servers. T he files created by this process are always downloaded to your local machine. Report a bug
10.1. Creating Application Snapshots

Use the rhc snapshot save command to create a snapshot. T he command will prompt for any missing information, such as your rhlogin and password. T he default filename for the snapshot is $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 command to restore snapshots to the server. T his restores the Git repository, the application data directories and the log files found in the specified archive. When the restoration is complete, OpenShift Online runs the deployment script on the newly-restored repository, which completes the deployment process in the same way as if you had run git push .
Warning
T he rhc snapshot 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 snapshot import may have on your local data, use SSH to access your application and make the backup directly.
74
Chapter 10. Backing Up and Restoring Application D ata
$ rhc snapshot restore App_Name Restoring from snapshot App_Name.tar.gz... Removing old git repo: ~/git/App_Name.git/ Removing old data dir: ~/app-root/data/* Restoring ~/git/App_Name.git and ~/app-root/data Activation status: success RESULT: Success
If you used the override process to save your application under a different filename, as outlined in Section 10.1, Creating Application Snapshots, you can restore this snapshot version of your application. T he following command shows how to restore an application named App_Name, but saved under the filepath 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 necessary is when a free plan is upgraded to a paid plan. In this case, 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 10.1. Migrate an Application to Another Gear 1. Create a snapshot of your existing application.
$ rhc snapshot save App_Name
T he rhc snapshot save command saves the App_Name.tar.gz file in the current working directory. Verify that your application snapshot has been saved. 2. After confirming your application snapshot is saved, delete the existing application.
3. Create a new application of the same type with the correct gear size, 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 contained, for example, the MySQL and phpMyAdmin cartridges, run the following command:
$ rhc app create App_Name php-5.3 mysql-5 phpmyadmin-3 -g medium
4. Finally, restore the earlier saved application snapshot to the newly created application. Be sure to specify the correct path to the saved application snapshot.
75
$ rhc snapshot restore App_Name -f App_Name.tar.gz
Report a bug
76
Revision History
Revision History
Revision 1.0.36-0.4 05 Rebuild with Publican 4.0.0 T hu Nov 28 2013 Rdiger Landmann
Revision 1.0.36-0 T ue Nov 26 2013 Added information on specifying the size of cartridges. Added information to clarify action_hooks.
Bilhar Aulakh
Revision 1.0.35-0 T hu Nov 7 2013 Bilhar Aulakh Added two new 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. Revision 1.0.34 -0 T ue Oct 15 2013 Added information on configuring application deployment. Added support for PostgreSQL 9.2 from SCL. Added SECRET _T OKEN environment variable. Added Members section for domain membership. Added support for multiple domains. Added table and information about ports available for binding. Revision 1.0.33-0 Wed Sep 18 2013 Added information on port forwarding with individual gears. Updated cartridge version numbers. Added Custom Environment Variables section. Bilhar Aulakh
Bilhar Aulakh
77

OpenShift Online 2.0 User Guide en US

Uploaded by

Document Information

Copyright

Available Formats

Share this document

Share or Embed Document

Sharing Options

Did you find this document useful?

Is this content inappropriate?

Copyright:

Available Formats

OpenShift Online 2.0 User Guide en US

Uploaded by

Copyright:

Available Formats

OpenShift Online All Versions User Guide

Managing Applications in the Cloud with OpenShift Online Edition 1.0

Red Hat OpenShift Documentation Team

OpenShift Online All Versions User Guide

Managing Applications in the Cloud with OpenShift Online Edition 1.0

Red Hat OpenShift Do cumentatio n Team

OpenShift Online All Versions User Guide

OpenShift Online All Versions User Guide

1.1. Typographic Conventions

OpenShift Online All Versions User Guide

1.2. Pull-quote Conventions

1.3. Notes and Warnings

OpenShift Online All Versions User Guide

2.2. We Need Feedback!

1.2. Platform Overview

OpenShift Online All Versions User Guide

Chapter 2. Getting Started

Chapter 2. Getting Started

Figure 2.1. Management Console

OpenShift Online All Versions User Guide

2.1.2. Client Tools

2.2. Basic Administration

2.2.1. Management Console

Chapter 2. Getting Started

2.2.2. Client Tools

OpenShift Online All Versions User Guide

Chapter 3. Authorization Tokens

Chapter 3. Authorization Tokens

3.2. Creating Authorization Tokens

OpenShift Online All Versions User Guide

787a57211d42f251204136b05d490038830d9b7057f54f816c2a9fcd0c8333b8 session 4:40 PM about 1 day

3.3. Viewing Authorization Tokens

787a57211d42f251204136b05d490038830d9b7057f54f816c2a9fcd0c8333b8 session 4:40 PM about 23 hours

3.4. Deleting Authorization Tokens

Chapter 3. Authorization Tokens

$ rhc authorization delete-all Deleting all authorizations ... done

OpenShift Online All Versions User Guide

4.2. Creating a Domain

T his command will create the domain autom obile .

4.3. Listing Available Domains

4.4. Viewing a Domain

4.5. Renaming a Domain

OpenShift Online All Versions User Guide

4.6. Deleting a Domain

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

4.7. Custom Domains and SSL Certificates

4.7.1. Using Custom Domain Names

OpenShift Online All Versions User Guide

4.7.2. Using Custom SSL Certificates

5.2. Adding a Member

5.3. Listing Members

OpenShift Online All Versions User Guide

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

5.4. Removing a Member

Chapter 6. Applications and Cartridges

Chapter 6. Applications and Cartridges

Application Name Alias

6.1.1. About Scaled Applications

OpenShift Online All Versions User Guide

Figure 6.1. Cartridges on Gears in a Scaling Application

6.1.2. About Non-Scaled Applications

6.1.3. Viewing Accessible Applications

Chapter 6. Applications and Cartridges

6.2. About Cartridges