The OpenShift Client tools, known as rhc, are built and packaged using the Ruby programming language. OpenShift Origin integrates with the Git version control system to provide powerful, decentralized version control for your application source code. OpenShift Origin client tools can be installed on any operating system with Ruby 1.8.7 or higher. Instructions for specific operating systems are provided below. It is assumed that you are running the commands from a command line window, such as Command Prompt, or Terminal.

1. Microsoft Windows

Before you can use the rhc package on Microsoft Windows, you will first need to install a few supporting packages:

  • Ruby

  • git

1.1. Install Ruby for Windows

RubyInstaller 1.9 provides the best experience for installing Ruby on Windows XP, Vista, and Windows 7. Download the newest version from the download page and launch the installer.

During the installation you should accept all of the defaults, it is mandatory that you select the "Add Ruby executables to your PATH" check box in order to run Ruby from the command line.

After the installation is complete, to verify that the installation is working run:

C:\Program Files\> ruby -e 'puts "Welcome to Ruby"'
Welcome to Ruby

If the Welcome to Ruby message does not display, the Ruby executable may not have been added to the path. Restart the installation process and ensure the "Add Ruby executables to your PATH" check box is selected.

1.2. Install Git for Windows

The next step is to install Git for Windows so that you can synchronize your local application source and your OpenShift application. Git for Windows offers the easiest Git experience on the Windows operating system and is the recommended default - if you use another version of Git please ensure it can be executed from the command line and continue to the next section.

Download and install the latest version of Git for Windows. Ensure that Git is added to your PATH so that it can be run from the command line. After the installation has completed, verify that Git is correctly configured by running:

C:\Program Files\> git --version
git version 1.7.11.msysgit.1

1.3. Install RHC for Windows

After Ruby and Git are correctly installed, use the RubyGems package manager (included in Ruby) to install the OpenShift Origin client tools. Run:

C:\Program Files\> gem install rhc

RubyGems downloads and installs the rhc gem from www.rubygems.org/gems/rhc. The installation typically proceeds without errors. After the installation has completed, run:

C:\Program Files\> rhc

2. Mac OS X

Before you can use the rhc package on OS X, you will first need to install a few supporting packages:

  • Ruby

  • git

2.1. Install Ruby for OS X

From OS X Lion onwards, Ruby 1.8.7 is installed by default. On older Mac systems, Ruby is shipped as part of the Xcode development suite and can be installed from your installation CD. If you are familiar with Mac development, you can also use MacRuby or see the Ruby installation page for help installing with homebrew.

To verify that Ruby is correctly installed run:

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

2.2. Install Git for OS X

There are a number of options on Mac OS X for Git. We recommend the Git for OS X installer - download and run the latest version of the dmg file on your system. To verify the Git for OS X installation, run:

$ git --version
git version 1.7.11.1

2.3. Install RHC for OS X

With Ruby and Git installed, use the RubyGems library system to install and run the OpenShift Origin gem. Run:

$ sudo gem install rhc

After the installation has completed, run:

$ rhc -v

3. Fedora

To install on Fedora 16 or above, the most reliable solution is to use RubyGems.

$ sudo yum install rubygems

After installing RubyGems, use it to install the OpenShift Origin client tools:

$ sudo gem install rhc

You will also need to install Git if it is not already installed:

$ sudo yum install git

After the OpenShift Origin client tools have been installed, run the following command:

$ rhc -v

4. Red Hat Enterprise Linux

To install on Red Hat Enterprise Linux 6.2, 6.3, or 6.4, the most reliable solution is to use RubyGems. In order to install the RubyGems package, the RHEL Optional channel must be enabled. There are two ways of doing this from the command line. If you are using the Certificate-Based RHN tooling, enter the following command:

$ sudo yum-config-manager --enable rhel-6-server-optional-rpms

If you are using RHN-Classic, enter the following command:

$ sudo rhn-channel --add --channel=rhel-x86rhel-x86_64-server-optional-6

With the repository in place, you can now install RubyGems:

$ sudo yum install rubygems

After installing RubyGems, use it to install the OpenShift Origin client tools:

$ sudo gem install rhc

You will also need to install Git if it is not already installed:

$ sudo yum install git

After the OpenShift Origin client tools have been installed, run the following command:

$ rhc -v

5. Ubuntu

These insructions are broken out by Ubuntu version.[1]

5.1. For Ubuntu 14.04

First, ensure that the "Universe" repository is enabled by following these instructions.

Next, issue the following command to install the necessary ruby and git packages:

$ sudo apt-get install ruby-full rubygems-integration git-core

You can verify the Ruby installation with:

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

And the git installation with:

$ git –version

Now you can install the OpenShift client tools:

$ sudo gem install rhc

5.2. For Previous Versions of Ubuntu

If the commands for Ubuntu 14.04 don’t work for you, try these instructions which worked for previous versions.

Use the apt-get command line package manager to install Ruby and Git before you install the OpenShift Origin command line tools. Run the following command:

$ sudo apt-get install ruby-full rubygems git-core

After you install both Ruby and Git, verify they can be accessed via the command line:

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

If either program is not available from the command line, please add them to your PATH environment variable.

With Ruby and Git correctly installed, you can now use the RubyGems package manager to install the OpenShift Origin client tools. From a command line, run the following command:

$ sudo gem install rhc

6. Ruby Version Manager and rhc

Ruby Version Manager (RVM) is an alternate management system for Ruby and Ruby Gems that makes it easier for users to switch between ruby versions and to work with the latest gem versions. Because rhc is itself a Ruby Gem, using it with RVM doesn’t require any special magic. Once RVM is installed, use the rvm use command to specify the ruby version / environment of your choice:

$ rvm use 1.9.3    # tells rvm to use a Ruby 1.93 environment
$ rvm use system   # tells rvm to use the Ruby environment that is not managed by RVM

To set the persistent default environment, use the --default flag:

$ rvm --default use 1.9.3
Using /path/to/homedir/.rvm/gems/ruby-1.9.3-p286

Once you are working in your preferred environment, run the gem command as usual to install rhc:

$ gem install rhc

And confirm that you are going to be using the desired version of rhc using which:

$ which rhc
/path/to/homedir/.rvm/gems/ruby-1.9.3-p286/bin/rhc

1. Hat tip to this article for the updated instructions for Ubuntu 14.04.