Beruflich Dokumente
Kultur Dokumente
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.
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.
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")); } }
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.
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
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
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
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
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
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
15
$ rhc authorization add --scopes session --note My_token Adding authorization ... done My_token -------Token: Scopes: Created: Expires In:
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
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
Delete All Authorization T okens Run the rhc authorization delete-all command to delete all the tokens associated with your account:
16
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
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
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
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
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
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 delete command to delete the domain.
20
Chapter 4. D omains
After you delete a domain, you must create a new one before creating any new applications. Report a bug
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
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
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
23
$ rhc member list automobile Login Role ------------------------ ------------login@example.com admin (owner) login2@example.com view login3@example.com edit login4@example.com admin
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
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
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.
Report a bug
26
Report a bug
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
28
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
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
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
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
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
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
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
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
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
Report a bug
36
Report a bug
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
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
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
Report a bug
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
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
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
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
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
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
T his process only deletes your remote application data. You must manually delete application data stored on your local machine. Report a bug
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
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
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
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
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
Report a bug
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
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.
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
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
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
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
****************************************************************** *** 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
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
Report a bug
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
56
Report a bug
Report a bug
Report a bug
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
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
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
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",
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
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
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
Note
T he cron commands affect all cron jobs. You cannot disable or enable individual cron jobs. Report a bug
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
HT T P cache
8080, 8118, 8123, 1000110010 11211 3528, 3529 8787 4712, 4447, 7600, 9123, 9990, 9999, 18001 5671-5672
PulseAudio
4713
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
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
Report a bug
Report a bug
64
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
Report a bug
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
Report a bug
66
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
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
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
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
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
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
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
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
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
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
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
Report a bug
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
$ 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
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.
$ rhc app delete App_Name
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
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