Skip to content
This repository

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP

Enhances default Heroku functionality.

README.md

Overview

Gem Version Code Climate GPA Gemnasium Status Travis CI Status Coverage Status

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 with 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 within the context of current application.

Requirements

  1. UNIX-based OS.
  2. Any of the following Ruby VMs:
  3. Heroku account.
  4. Heroku PG Backups Addon.

Setup

For a secure install, type the following from the command line (recommended):

gem cert --add <(curl -Ls http://www.redalchemist.com/gem-public.pem)
gem install heroku_plus --trust-policy MediumSecurity

NOTE: A HighSecurity trust policy would be best but MediumSecurity enables signed gem verification while allowing the installation of unsigned dependencies since they are beyond the scope of this gem.

For an insecure install, type the following (not recommended):

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
:current_account: ra

You can create a new account by running the following from the command line:

hp -a -c <account name>

Details

The following is an overview of all files used by this gem (including the Heroku gem) to manage your accounts:

~/.netrc - Used by the Heroku gem, holds current account credentials. When account switching, the contents of this
           file will be replaced by the contents of a *.account file.
~/.heroku/heroku_plus.yml - Settings for this gem (as mentioned above).
~/.heroku/<name>.account - Credentials for a named account (there is one for each account). When account switching,
                           the contents of this file will replace the contents of the .netrc file.
~/.ssh/config - The SSH configuration settings for all accounts.
~/.ssh/<name> - The private SSH identity for an account (there is one for each account). Defaults to id_rsa.
~/.ssh/<name>.pub - The public SSH identity for an account (there is one for each account). Defaults to id_rsa.pub.

Details of each file is described below.

Netrc (~/.netrc)

This file is automatically managed for you and looks like the following:

machine api.heroku.com
  login example@example.com
  password VbcudJUkMniDfRydcs8Byzwhr3BzHPqC
code.heroku.com
  login example@example.com
  password VbcudJUkMniDfRydcs8Byzwhr3BzHPqC

Heroku+ Settings (~/.heroku/heroku_plus.yml)

The global settings for Heroku+ (see details mentioned earlier).

Heroku+ Account Credentials (~/.heroku/.account)

Contains account credentials for a specific account. The file data is the same as mentioned above in the .netrc file.

SSH Configuration (~/.ssh/config)

This file is automatically managed for you and looks like the following:

Host heroku.example
 HostName heroku.com
 User example@example.com
 IdentityFile /Users/example/.ssh/example

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). These files are automatically created for you when running the "hp -a -c" command, but here is how to create them manually:

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

Project Git Configuration (~/Development/Projects/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 stage and production server where you deploy to stage before updating your production server. For example, your config file might look like this:

[remote "example-production"]
[remote "example-stage"]

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

heroku restart --app example-production
heroku restart --app example-stage

Which can be done faster by switching to the mode you want to run in (i.e. production or stage) and then running the necessary command. Example:

hp -m -s production
hp -r

The above basically says that you want to switch to "production" mode (i.e. git branch) and then execute an app restart via the "hp -r" command.

Finally, 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=ACCOUNT]     # Manage accounts.
hp -c, [--console]             # Open remote console.
hp -db, [--database=DATABASE]  # Manage PostgreSQL database.
hp -e, [--edit]                # Edit settings in default editor (as set via the $EDITOR environment variable).
hp -h, [--help=HELP]           # Show this message or get help for a command.
hp -m, [--mode=MODE]           # Manage modes.
hp -p, [--pass=PASS]           # Pass command to Heroku.
hp -r, [--restart]             # Restart remote server.
hp -v, [--version]             # Show version.

For account options, type: hp help account

-c, [--create=CREATE]    # Create account.
-s, [--switch=SWITCH]    # Switch account.
-d, [--destroy=DESTROY]  # Delete account.
-l, [--list]             # Show configured accounts.
-i, [--info]             # Show current credentials and SSH identity.

For mode options, type: hp help mode

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

For more db options, type: hp help db

-m, [--migrate]                      # Migrate remote PostgreSQL database and restart server.
-b, [--backup]                       # Backup remote PostgreSQL database.
-d, [--download]                     # Download last remote PostgreSQL database backup.
-t, [--transfer=TRANSFER]            # Transfer remote PostgreSQL database backup for current mode to specified mode.
-i, [--import=IMPORT]                # Import last remote PostgreSQL database backup into local database.
-I, [--import-latest=IMPORT_LATEST]  # Import latest (i.e. now) remote PostgreSQL database backup into local database.
-R, [--reset=RESET]                  # Reset and destroy all data in remote PostgreSQL database.

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
  3. Make changes to your code.
  4. Type: git commit -a “Your comments.”
  5. Type: git push heroku master.
  6. Have a beer.

Tests

To test, do the following:

  1. cd to the gem root.
  2. bundle install
  3. bundle exec rspec spec

Versioning

Read Semantic Versioning for details. Briefly, it means:

  • Patch (x.y.Z) - Incremented for small, backwards compatible bug fixes.
  • Minor (x.Y.z) - Incremented for new, backwards compatible public API enhancements and/or bug fixes.
  • Major (X.y.z) - Incremented for any backwards incompatible public API changes.

Contributions

Read CONTRIBUTING for details.

Credits

Developed by Brooke Kuhlmann at Red Alchemist

License

Copyright (c) 2010 Red Alchemist. Read the LICENSE for details.

History

Read the CHANGELOG for details. Built with Gemsmith.

Something went wrong with that request. Please try again.