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 Debian/Ubuntu

This tutorial is designed to help you get the most out of OpenShift Online on a Debian or Ubuntu 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 via Ruby gem

Installing the client tools this way on Ubuntu or Debian requires sudoer or root access and comprises three steps:

Step 1: Install Ruby with RubyGems

Step 2: Install Git

Step 3: Install the client tools

Step 1: Install Ruby with RubyGems

From terminal, run the following command to install Ruby:

$ sudo apt-get install ruby-full

Run the following command to verify that Ruby has installed correctly:

$ ruby -e 'puts "Welcome to Ruby"'
Welcome to Ruby

Rubygems are now part of the ruby package. However, with older Ubuntu repositories, you may need to run the following command to explicitly install RubyGems:

$ sudo apt-get install rubygems

Step 2: Install Git

Run the following command to install Git version control:

$ sudo apt-get install git-core

After installation completes, run the following command to verify that Git has installed correctly:

$ git --version

This command returns the Git version number that was installed.

Step 3: Install Client Tools

When the required software has been successfully installed, run the following command to install the client tools:

$ sudo gem install 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