Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Enhances default Heroku functionality.
Ruby

This branch is 185 commits behind bkuhlmann:master

Fetching latest commit…

Cannot retrieve the latest commit at this time

Failed to load latest commit information.
bin
lib
spec
.gitignore
.rspec
.travis.yml
CHANGELOG.rdoc
Gemfile
Gemfile.lock
LICENSE.rdoc
README.rdoc
Rakefile
heroku_plus.gemspec

README.rdoc

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. A UNIX-based system.

  2. Ruby 1.9.x

  3. 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 git@official.heroku.com:<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:

example@test.com
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 git@official.heroku.com

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 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).
-t, [--transfer=TRANSFER]        # Transfer remote PostgreSQL database backup for current mode to specified 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.

Resources

Tests

To test, do the following:

  1. cd to the gem root.

  2. bundle install

  3. bundle exec rspec spec

Contributions

Please log all feedback/issues via GitHub Issues. Thanks.

Credits

Developed by Brooke Kuhlmann at Red Alchemist

License

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

History

Read the CHANGELOG for details.

Something went wrong with that request. Please try again.