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.
- Multiple account management.
- Remote database management.
- Convenient workflow commands within the context of current application.
- UNIX-based OS.
- Any of the following Ruby VMs:
- Heroku account.
- Heroku PG Backups Addon.
For a secure install, type the following from the command line (recommended):
gem cert --add <(curl -Ls https://www.alchemists.io/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:
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>
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.
This file is automatically managed for you and looks like the following:
machine api.heroku.com login email@example.com password VbcudJUkMniDfRydcs8Byzwhr3BzHPqC code.heroku.com login firstname.lastname@example.org 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 email@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.
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.
From this point forward, you can switch between accounts as follows:
- Change directory to the app you want to work on.
- Type: hp -a -s
- Make changes to your code.
- Type: git commit -a “Your comments.”
- Type: git push heroku master.
- Have a beer.
To test, run:
bundle exec rspec spec
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.
Code of Conduct
Please note that this project is released with a CODE OF CONDUCT. By participating in this project you agree to abide by its terms.
Read CONTRIBUTING for details.