There are two ways to interact with OpenShift Online: the Management Console or the Client Tools.

The OpenShift Online Management Console is a graphical interface accessed with a web browser and is best suited for:

The OpenShift Online CLI tools, or more commonly referred to as the client tools, are used to manage a cloud environment using a command line interface, and provide features that are not currently available in the Management Console. The client tools are best suited for:

For example, although you can create an application using the Management Console, the application must be cloned to your workstation to make any code changes, and then redeployed to the remote server using the client tools.

The subsequent sections of this book describe how to install the OpenShift Online client tools on various operating systems.

When you have successfully installed the OpenShift Online client tools, they must be configured. The interactive setup wizard walks you through the steps by asking several questions to help you configure the client tools.

The following is a sample walk through of the setup wizard, and some general information to assist you with the initial configuration. It assumes you have installed the latest version of the client tools. Use rhc --version to verify the installed version, or see Section 2.4, “Updating Client Tools” for instructions on how to update the client tools.

Run the rhc setup command to launch the setup wizard:

$ rhc setup
OpenShift Client Tools (RHC) Setup Wizard

This wizard will help you upload your SSH keys, set your application namespace, and check that other programs like Git are properly installed.

The setup wizard next prompts you for the login credentials that were used to sign up for an OpenShift Online account. Alternatively, you can also use your Red Hat login credentials.

Login to openshift.redhat.com: user@myemail.com
Password: password

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

OpenShift Online
	
	 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

With your login credentials, the setup wizard creates the express.conf configuration file in your home directory. In the following example, the express.conf file is created in the C:\Users\User1\.openshift directory.

Saving configuration to C:\Users\User1\.openshift\express.conf ... done

Next, the setup wizard configures the SSH keys so that your system can authenticate with the remote server. Because this is the initial configuration, it is assumed no existing SSH keys are found on your system. Therefore, the setup wizard generates a new pair of SSH keys, named id_rsa and id_rsa.pub, and saves them in your home directory. In the following example the SSH keys are generated and saved in the C:\Users\User1\.ssh directory.

No SSH keys were found. We will generate a pair of keys for you.
	Created: C:\Users\User1\.ssh\id_rsa.pub

After the new SSH keys are generated, the public key, id_rsa.pub, must be uploaded to the OpenShift Online 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\id_rsa.pub ... done

The setup wizard verifies if Git version control software is installed on your system. Git is required to create and deploy applications to the OpenShift Online cloud environment. It is assumed that all the required software for your operating system is already installed as described in the earlier sections of this document. In the example below, the setup wizard verifies that Git for Windows is installed correctly.

In order to fully interact with OpenShift you will need to install and configure a git client if you have not already done so.
Documentation for installing other tools you will need for OpenShift can be found at https://openshift.redhat.com/community/developers/install-the-client-tools

We recommend these free applications:

  * Git for Windows - a basic git command line and GUI client https://github.com
/msysgit/msysgit/wiki/InstallMSysGit
  * TortoiseGit - git client that integrates into the file explorer http://code.
google.com/p/tortoisegit/

The setup wizard next verifies whether a domain already exists for your cloud environment. The example below assumes that a domain does not exist, and one must be created. If you did create a domain when you signed up for an OpenShift Online account, it is displayed here. To create a domain at this time, enter the desired name when prompted. Alternatively, you can create a domain using the OpenShift Online Management Console, or using the rhc domain create command later. The domain named MyDomain is created in the following example.

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. Any applications created with the Management Console are displayed here. 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
  Ruby 2.0                                  rhc app create <app name> ruby-2.0
  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.

The OpenShift Online client tools are now configured on your system.

If the client tools were installed with the gem install method, run the gem update command to update the client tools:

$ gem update rhc

Alternatively, if the client tools were installed with the yum install method, run the yum update command to update the client tools, and replace packagename with rubygem-rhc for Fedora or rhc for Red Hat Enterprise Linux:

$ yum update packagename

Visit the Get Started on OpenShift web page to get more information and access the OpenShift Online quick start guides. The quick start guides help you create and deploy applications, and provide information on managing your OpenShift Online cloud environment.

Further information on creating, deploying, and managing applications can also be found in the OpenShift Online User Guide at https://access.redhat.com/site/documentation.