Please note that these documents apply to OpenShift Online v2 only (accounts created before August 1st, 2016).
If you are using one of the OpenShift 3 products, please refer to documents available at

OpenShift Online for RHEL/CentOS

This tutorial is designed to help you get the most out of OpenShift Online on a RHEL or CentOS machine. In addition to the web interface, OpenShift provides client tools (rhc) to help you create and manage your applications.

OpenShift allows a choice of environments (UI, command line, IDE), but in order to get the most out of your applications, you’ll want to at least use the OpenShift client tools (rhc).

If you just want to log in and create your first application, you can simply log into the web console (requires login). However, you won’t be able to make changes to your application until you’ve followed the instructions below.

Installing the Client Tools on RHEL or CentOS

You must have the following to successfully install the client tools: * Red Hat Enterprise Linux 6 or later * Sudoer or root access * Ruby and RubyGems installed (including rubygem-json and rubygem-parseconfig)

The sudo command only works if the particular user is listed in the sudoers file. As an alternative to sudo access, you can activate a root terminal with the su command and the root password. If you activate a root terminal, omit sudo from the commands shown in the examples. Be sure to close the root terminal when the installation process is complete.

Install RubyGems

If the RubyGems package is not already installed, you must enable the Red Hat Enterprise Linux optional repository channel. The RubyGems package dependencies are then automatically resolved when the client tools are installed.

If you are using the Certificate-Based Red Hat Network (RHN) tooling, use the following command to enable the optional channel:

$ sudo yum-config-manager --enable [architecture][operating_system]-optional-6

If you are using the classic RHN subscription, use the following command to enable the optional channel:

$ sudo rhn-channel --add --channel=[architecture]-[operating_system]-optional-6
  • architecture: Your system architecture. Enter either i386 or x86_64

  • operating system: Type of operating system installed. Enter either workstation or server.

For example, if you have Red Hat Enterprise Linux Workstation 6 or later installed on a 64-bit x86 computer, and you are using the classic Red Hat Network subscription, run the following command to enable the optional repository:

$ sudo rhn-channel --add --channel=rhel-x86_64-workstation-optional-6

Install Client Tools

Ensure that the RubyGems software package is installed on your system. Otherwise, the optional repository channel must be enabled on systems that are registered on RHN.

Run the following command to install the client tools:

$ sudo gem install rhc

Update rhc to the latest version:

$ sudo gem update rhc

Setting up Your Machine

After installation is complete, open a Terminal window and run:

$ rhc setup

The OpenShift interactive setup wizard displays and prompts you to complete the rest of the process.

You’ll be prompted for your OpenShift username and password:

Login to
Password: password

You are then prompted to generate an authorization token. Answering yes stores a token in your home directory to be used on subsequent requests. When it expires, you are prompted for your password again.

OpenShift can create and store a token on disk which allows to you to access the server without using your password. The key is stored in your home directory and should be kept secret. You can delete the key at any time by running 'rhc logout'.
Generate a token now? (yes|no) yes
Generating an authorization token for this client ... lasts about 1 day

After creating a configuration file, setup will configure SSH keys so that your system can remotely connect to your applications, including deploying your applications using Git:

No SSH keys were found. We will generate a pair of keys for you.
Created: C:\Users\User1\.ssh\
The path shown here is for Windows and will differ depending on your operating system.

After the new SSH keys are generated, the public key,, must be uploaded to the OpenShift server to authenticate your system to the remote server. Enter a name to use for your key, or leave it blank to use the default name. In the following example the default name is used.

Your public ssh key must be uploaded to the OpenShift server to access code.
Upload now? (yes|no) yes

Since you do not have any keys associated with your OpenShift account, your new key will be uploaded as the 'default' key

Uploading key 'default' from C:\Users\User1\.ssh\ ... done
The path shown here is for Windows and will differ depending on your operating system.

After verifying that Git is installed, you will be asked to set up your domain if you don’t already have one:

Checking for a domain ... none

Your domain is unique to your account and is the suffix of the public URLs we assign to your applications. You may configure your domain here or leave it blank and use 'rhc domain create' to create a domain later. You will not be able to create applications without first creating a domain.

Please enter a domain (letters and numbers only) |<none>|: MyDomain
Your domain name 'MyDomain' has been successfully created

Finally, the setup wizard verifies whether any applications exist under your domain. In the example below, no applications have been created. In this case the setup wizard shows the types of applications that can be created with the associated commands. The setup wizard then completes by displaying the current gear consumption along with the gear sizes available to the given user.

Checking for applications ... none

Run 'rhc app create' to create your first application.

Do-It-Yourself                            rhc app create <app name> diy-0.1
JBoss Application Server 7.1              rhc app create <app name> jbossas-7
JBoss Enterprise Application Platform 6.0 rhc app create <app name> jbosseap-6.0
Jenkins Server 1.4                        rhc app create <app name> jenkins-1.4
Node.js 0.10                              rhc app create <app name> nodejs-0.10
PHP 5.3                                   rhc app create <app name> php-5.3
PHP 5.4                                   rhc app create <app name> php-5.4
Perl 5.10                                 rhc app create <app name> perl-5.10
Python 2.6                                rhc app create <app name> python-2.6
Python 2.7 Community Cartridge            rhc app create <app name> python-2.7
Python 3.3 Community Cartridge            rhc app create <app name> python-3.3
Ruby 1.8                                  rhc app create <app name> ruby-1.8
Ruby 1.9                                  rhc app create <app name> ruby-1.9
Tomcat 6 (JBoss EWS 1.0)                  rhc app create <app name> jbossews-1.0
Tomcat 7 (JBoss EWS 2.0)                  rhc app create <app name> jbossews-2.0
Zend Server 5.6                           rhc app create <app name> zend-5.6

You are using 0 of 3 total gears
The following gear sizes are available to you: small

Your client tools are now configured.

You are now ready to create and manage an application using OpenShift.

If you cannot run OpenShift client tools at this point, please visit the Help Center for more assistance.

Creating an Application

Now that you have rhc installed and configured, you are ready to create an application.

You can create a new application with either the management console or the client tools.

Using the Web Console

You can see the full list of application types and create a new application through the OpenShift web console: Create an Application (requires login)

Using the Client tools (rhc)

Alternatively, you can use rhc to create an application using the following command:

$ rhc app create <app_name> <web_cartridge_name>

For example, to create a PHP 5.4 application named myfirstphpapp, use the following command:

$ rhc app create myfirstphpapp php-5.4

There are a number of options available when creating a new application. To learn more about creating an application on OpenShift, see Creating Applications.

Making Your First Change

OpenShift uses Git to manage application deployments on OpenShift. You make code changes on your local machine, check those changes in locally, and then push those changes to OpenShift.

Using the Git Repository

Every OpenShift application you create has its own Git repository that only you can access.

Command Line (RHC)

If you create your application from the command line, rhc will automatically download a copy of that repository (Git calls this 'cloning') to your local system.

Web Console

If you create an application from the web console, you’ll need to tell Git to clone the repository. Find the Git URL from the application page, and then run:

$ git clone <git_url> <directory to create>

Submitting Changes

Once you make changes to your local repository, you need to add and commit those changes - add tells Git that a file or set of files will become part of a larger check in, and commit completes the check in. Git requires that each commit have a message to describe it.

$ git add .
$ git commit -m "A change to my application"

Finally, you’re ready to send your changes to your application - you’ll 'push' these changes with:

$ git push

The output of the push command will contain information from OpenShift about your deployment.

Remote Access

OpenShift allows you to remotely access your application’s gears in order to perform various tasks such as troubleshooting, working with log files, and managing environment variables

Once you have created an application and set up your SSH keys (either by rhc setup or manual upload), you can SSH into the remote server using the rhc ssh command.

To SSH into a specific application:

$ rhc ssh <app_name>

You should then connect to your application’s primary gear:


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:


Welcome to OpenShift shell

This shell will assist you in managing OpenShift applications.

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

Type "help" for more info.

Now that you’re connected, you can use the OpenShift shell to explore and modify your application.

Common Commands

Once you have SSHed into your application, you can use many common Linux Commands.

In addition to Linux commands, the following commands are available to help control your OpenShift application and environment:

gear            control your application (start, stop, restart, etc)
or deps with --cart      (gear start --cart mysql-5.1)
tail_all        tail all log files
export          list available environment variables (1)
rm              remove files / directories
ls              list files / directories
ps              list running applications
kill            kill running applications
mysql           interactive MySQL shell
mongo           interactive MongoDB shell
psql            interactive PostgreSQL shell
quota           list disk usage
1 Find more information on using Environment Variables

Next Steps

This guide has just scratched the surface of what you can do with OpenShift Online. Feel free to explore other topics under Managing Your Applications or visit one of the technology-specific tutorials below:

Language More Specific Tutorials


Other Technologies