Chapter 1. Setting Up FHC

1.1. Installing FHC

Overview

FHC is the Red Hat Mobile Application Platform (RHMAP) command line interface. It is a Node.js based CLI for accessing the RHMAP APIs. Almost all functionality which is exposed through the RHMAP Studio is available via FHC.

As FHC is a Node.js module, it can also be included in your own Node.js applications - allowing access to the Platform to be scripted and automated. This allows interaction with the Platform to be integrated into automated processes such as build systems and Continuous Integration systems.

Requirements

To use FHC, you will first need to have Node.js & NPM installed.

To install Node.js, follow the instructions on nodejs.org for your OS. This will add 2 command line applications: node and npm.

1.1.1. Install FHC

To install FHC, you will need to execute the following in a terminal/command prompt:

npm install -g fh-fhc

If installing on Linux, you may need to run this command as a sudoer:

sudo npm install -g fh-fhc

This will install fhc from npm — the central registry of Node.js modules.

The -g flag tells nom to install fhc globally so that it will be available from any directory.

Once installation is complete, fhc will be available from your command line (if you use zsh, do a hash -r to pick it up).

To test FHC is installed correctly, and to show the version you have installed, use:

fhc -v

1.1.1.1. Command Completion (Linux and Mac only)

The FHC bash completion script allows Tab completion of the various FHC commands, including completing app identifiers when performing actions on a single app. To install the FHC bash completion script, execute the following:

fhc completion >> ~/.bashrc

If you’re using an alternative shell to bash, you should append the output of fhc completion to the relevant file for example, ~/.zshrc for zsh.

1.1.2. Usage

To get started, set the target and then login:

fhc target https://[your-studio-domain].feedhenry.com
fhc login [email address] [password]

To list your projects, use:

fhc projects

1.1.2.1. Configuration

fhc is extremely configurable. It reads its configuration options from 5 places.

  • Command line switches:
    Set a config with --key val. All keys take a value, even if they are booleans (the config parser doesn’t know what the options are at the time of parsing.) If no value is provided, then the option is set to boolean true.
  • Environment Variables:
    Set any config by prefixing the name in an environment variable with fhc_config_. For example, export fhc_config_key=val.
  • User Configs:
    The file at $HOME/.fhcrc is an ini-formatted list of configs. If present, it is parsed. If the userconfig option is set in the cli or env, then that will be used instead.
  • Global Configs:
    The file found at ../etc/fhcrc (from the node executable, by default this resolves to /usr/local/etc/fhcrc) will be parsed if it is found. If the globalconfig option is set in the cli, env, or user config, then that file is parsed instead.
  • Defaults:
    fhc’s default configuration options are defined in lib/utils/config-defs.js. These must not be changed.

See fhc help config for much much more information.

Use fhc help for a list of all commands, or fhc [command] --help for help on a specific command.

1.1.3. Next Steps

1.2. SSH Key Setup

Overview

Before you can clone a git repo, you must first upload your SSH public key (for more information on Public-key cryptography, check out this Wikipedia article).

This tutorial will show you how to generate a public/private key pair (if required) and upload the SSH Public Key to the Platform via FHC.

Requirements

You should install FHC before completing this tutorial.

1.2.1. Checking for an existing Key

To check whether or not an SSH key has been generated, open Terminal on Linux or Mac, or Git Bash on Windows.

Enter ls -la ~/.ssh

This will list the files in the .ssh directory. If you do not see either of these files, then proceed to Generating an SSH Public Key, as you must generate an SSH public key. If you see files named either id_rsa.pub or id_dsa.pub, then the key has been generated and you can skip to Adding an SSH Public Key to the Platform via FHC.

1.2.2. Generating an SSH Public Key

In order to generate a key, we will use a tool called ssh-keygen. Open Terminal on Linux or Mac, or Git Bash on Windows.

Enter the following:

ssh-keygen -t rsa -C "your_email_address@example.com"

After you have entered this command you will be asked where to save the key. Press the enter key to use the default location.

You will then be prompted to enter and confirm a password for the private key. When complete, the public & private key should be written to ~/.ssh/id_rsa.pub & ~/.ssh/id_rsa.

1.2.3. Adding an SSH Public Key to the Platform via FHC

Using FHC, log in to the Platform. When adding a public key, you must specify both a name and a key file. To add a key, enter the following command:

fhc keys ssh add <label> <key-file>

For example:

fhc keys ssh add myKey ~/.ssh/id_rsa.pub

You can verify that the key has been added correctly by listing out all ssh keys for the user.

fhc keys ssh

You should now be able to see your recently added key.

Note

If you need to use multiple SSH keys, follow our guide for configuring your local SSH to use multiple keys.

1.2.4. Adding an SSH Public Key to the Platform via Studio

Follow these steps to add your public SSH key to the Platform using the Studio:

  1. Log into the Studio.
  2. Click on the portrait button located on the top right of the screen.
  3. Select Settings.
  4. Select SSH Key Management. A list of previously uploaded SSH Keys will be displayed.
  5. Select Add New Key.
  6. Paste your public key into the Public Key field.
  7. Select Upload Public Key.

You should now be able to see your recently added key in the list of keys.

1.2.5. Using multiple SSH keys for different domains/projects

If you need to access multiple domains in the Red Hat Mobile Application Platform (RHMAP) as different users you will need to use seperate SSH keys when accessing the Git repositories, since each SSH key can only be associated with a single user. You will need to tell Git/SSH which key you want to apply to each host. This is normally done via an SSH config file.

1.2.5.1. Details

SSH will normally attempt to use all the identity files available to it, and if several of your ssh keys are valid in the cluster, it may use one that’s valid for the cluster but which doesn’t have access to the project that you are trying to clone.

You can update your local SSH config file, normally ~/.ssh/config, to list the identities to use for a particular host, but you should also add an IdentitiesOnly yes clause, to tell SSH to only use the specified identity file for a particular host, rather than all the identity files.

So if you want to access App repositories as different users, create SSH keys for each of the two users. Upload each SSH key to its corresponding user’s account.

In the example below, the SSH key file /Users/jbloggs/.ssh/key_for_domain1_id_rsa has been uploaded to my user in domain1.redhatmobile.com, and /Users/jbloggs/.ssh/key_for_domain2_id_rsa has been uploaded to the user in domain2.redhatmobile.com

To allow access to the App repositories:

git@domain1.redhatmobile.com:domain1/jbAdvTest-mmCord1.git
git@domain2.redhatmobile.com:domain2/jbAdvTest-mmCord2.git

Your ssh config file would look something like the following:

Host domain1.redhatmobile.com
HostName domain1.redhatmobile.com
IdentitiesOnly yes
IdentityFile /Users/jbloggs/.ssh/key_for_domain1_id_rsa
Host domain2.redhatmobile.com
HostName domain2.redhatmobile.com
IdentitiesOnly yes
IdentityFile /Users/jbloggs/.ssh/key_for_domain2_id_rsa

You can then clone the repos using the git commands:

git clone git@domain1.redhatmobile.com:domain1/jbAdvTest-mmCord1.git
git clone git@domain2.redhatmobile.com:domain2/jbAdvTest-mmCord2.git

Because of the ssh config file, the appropriate SSH key will be used for each domain, for further information on the configuration of ssh, you should check the documentation for your local installation of SSH, depending on your Operating System, it may be available from the command line man ssh_config.

Note that the above configurations and domain names are examples only and do not refer to actual domains.