Overview¶ ↑

Managing multiple Heroku accounts is not easy with the Heroku gem. This gem builds upon capabilities found in the Heroku gem by adding multi-account support so you can switch between accounts using a single command line command. In addition to the multi-account support, this gem also allows native Heroku commands enhanced with your current account settings. Once you get your feet wet this this gem, you’ll soon find that you’ll be using less of the heroku command and more of the hp command.

Features¶ ↑

• Multiple account management.

• Remote database management.

• Convenient workflow commands for current application.

Requirements¶ ↑

1. Mac OS X, Linux, or UNIX.

2. A Heroku account.

Setup¶ ↑

Type the following from the command line to install:

gem install heroku_plus

You can change the default settings for this gem by creating the following file:

~/.heroku/heroku_plus.yml

The contents of the file should look like this (where the default values can be changed to your liking):

---
:ssh_id: id_rsa
:mode: stage
:skip_switch_warnings: false
:pg_restore_options: -O -w

In order to understand how this gem benefits you, you first need to understand how the Heroku gem determines what your accounts settings are (as originally discussed here). Heroku does this by pulling information from your Heroku credentials and your SSH settings.

Overview¶ ↑

The Heroku gem determines your setup from your Heroku credentials, SSH files, and your project Git config within your project directory. Example:

~/.heroku/credentials
~/.ssh/config
~/.ssh/id_rsa
~/.ssh/id_rsa.pub
~/Development/Ruby/your_project/.git/config

This setup works wonderfully if you only own one Heroku account but breaks down considerably with multiple accounts because you have to manually maintain multiple credentials, id_rsa, and id_rsa.pub files for each Heroku account you own. Luckily, this gem solves this management headache for you but lets make sure we understand the above list in detail so you can learn how this gem helps you. Read on.

Heroku Setup¶ ↑

For each of your Heroku apps, change to the root directory of each app, and issue the following command:

git remote add heroku [email protected]:<your app>.git

This will allow you to push and deploy your changes back to the Heroku servers properly.

Heroku Credentials (~/.heroku/credentials)¶ ↑

You need a credentials files for each Heroku account. This file is created for you by the Heroku gem when you first setup your account and is a text file that consists of your login (i.e. email address) and password. Example:

[email protected]
dafkk3$59dkagblk3k5l56

This file contains the credentials necessary to validate your machine with your Heroku account. To support multiple accounts, I suggest the following:

~/.heroku/credentials - The active/current account.
~/.heroku/account_1.credentials - Your first account.
~/.heroku/account_2.credentials - Your second account.

NOTE: Account switching will not work properly if accounts are not suffixed with the .credentials file extension.

SSH Configuration (~/.ssh/config)¶ ↑

The SSH configuration file. This file should consist of or at least contain the following due to the Heroku setup steps mentioned earlier:

Host official.heroku.com
HostName heroku.com
User git
IdentitiesOnly yes

SSH Identity (~/.ssh/id_rsa and ~/.ssh/id_rsa.pub)¶ ↑

You need private and public SSH identity files for each Heroku account (it is assumed you are using RSA encryption but any encryption technique will work). If these files do not already exist, then here is how to create them:

ssh-keygen -t rsa -C "<email>" -f ~/.ssh/id_rsa

To support multiple accounts, I suggest the following:

~/.ssh/id_rsa - The active/current private key.
~/.ssh/id_rsa.pub - The active/current public key.

~/.ssh/account_1.identity - Your first private identity.
~/.ssh/account_1.identity.pub - Your first public identity.

~/.ssh/account_2.identity - Your second private identity.
~/.ssh/account_2.identity.pub - Your second public identity.

NOTE: Account switching will not work properly if all accounts are not suffixed with the .identity file extension.

After you have created your identities, send the identity of each public key to Heroku. For example:

hp -a -s account_1
heroku keys:add ~/.ssh/account_1.identity.pub

The easiest way to test if it is setup right is to SSH to Heroku:

ssh -v [email protected]

You should see “You can only access Heroku by ssh via git push and pull commands.” at the bottom. If you do, look for the correct email at the end of a line. For example: “debug1: Remote: Forced command: /home/git/bin/git_proxy <email>”.

Project Git Configuration (~/Development/Ruby/your_project/.git/config)¶ ↑

This is somewhat outside the scope of documentation for this gem but I think it is important to mention. The Git configuration file, as you might know, is what configures Git for your particular project. If you have more than one branch (i.e. remote) listed within this config file you will still need to pass the –app command when issuing Heroku commands. The reason for supporting multiple branches is because you might wish to have a production and test server where you deploy to test before updating your production server. For example, your config file might look like this:

[remote "example-prod"]
[remote "example-test"]

This would then require you use the –app option when issuing a Heroku command. For example:

heroku restart --app example-prod
heroku restart --app example-test

While this gem alleviates the need to specify the –app command when dealing within multiple Heroku accounts, it does not help you when dealing with multiple branches within a single Heroku account. That, I leave to you.

Usage¶ ↑

From the command line, type: hp

hp -a, [account]       # Manage accounts.
hp -c, [console]       # Open remote console.
hp -e, [edit]          # Edit settings in default editor (as set via the $EDITOR environment variable).
hp -h, [help]          # Show this message.
hp -m, [mode]          # Manage development modes.
hp -p, [pass=COMMAND]  # Pass command to Heroku for current app/mode.
hp -r, [restart]       # Restart remote server.
hp -v, [version]       # Show version.
hp db                  # Manage PostgreSQL database.

For more account options, type: hp help account

-f, [--files]            # Show current account files.
-b, [--backup=BACKUP]    # Backup existing account to new account.
-d, [--destroy=DESTROY]  # Delete existing account.
-i, [--info]             # Show current credentials and SSH identity.
-l, [--list]             # Show all configured accounts.
-s, [--switch=SWITCH]    # Switch to existing account.

For more mode options, type: hp help mode

-l, [--list]           # Show development modes.
-s, [--switch=SWITCH]  # Switch development mode.

For more db options, type: hp help db

-b, [--backup]                   # Backup remote PostgreSQL database (for current mode).
-m, [--migrate]                  # Migrate remote PostgreSQL database (for current mode) and restart server.
-R, [--reset=RESET]              # Reset and destroy all data in remote PostgreSQL database (for current mode).
-i, [--import=IMPORT]            # Import latest remote PostgreSQL database (for current mode) into local database.
-I, [--import-full=IMPORT_FULL]  # Import remote PostgreSQL database (for current mode) into local database by destroying local datbase, backing up and importing remote database, and running local migrations.

Workflow¶ ↑

From this point forward, you can switch between accounts as follows:

1. Change directory to the app you want to work on.

2. Type: hp -a -s <account name>

3. Make changes to your code.

4. Type: git commit -a -m “Your comments.”

5. Type: git push heroku master.

6. Have a beer.

Author¶ ↑

Red Alchemist

License¶ ↑

Copyright © 2010 Red Alchemist. Read the LICENSE for details.

History¶ ↑

Read the CHANGELOG for details.