heroku_builder 0.1.0 → 0.1.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 5220d5a1b120ff0b29b32536875d540c791ec88d
-  data.tar.gz: 31a7b6b0d8367547d9bb14ca37a7d4010399a767
+  metadata.gz: 9c1e7fd65d5f00bcf2611a0aad7c978cf51013ce
+  data.tar.gz: 62612b981eb174f5e068cd6d1172341931d36f92
 SHA512:
-  metadata.gz: 827062c1314073cd9a5457c64aa4b7ae26613fa3dc2719426d77c42b7ad0c8ff81c9c8760039f6a1b38e37e80b2d0a2d3768b1750818d7141bf6f95adbbcac9b
-  data.tar.gz: f0c6419243f65a0a31f081f13935d78b75a2ddf6135c3eca631db8879cc4566a97ee26b747ae4c45953490f17d9324d8e1274c39a96be0172d8994b6bfcb5c79
+  metadata.gz: 01dc148cbead348ac82d0a560797e11491ec23cf4a1b5cc5b784740fa8b7d3116b7adc43d702257de9a359dd16f0b468df0f09472de5ce4df5a80dee69df6a32
+  data.tar.gz: dc7af0370b374cc85c75d3b0374fbe44aa1b46e2fba02ac1902243604188befe5e454f9bcb31599b91f25a608b8d16be856018c8bf3cd0cebf393cc2f6e5f93d

data/.gitignore

@@ -7,3 +7,5 @@
 /pkg/
 /spec/reports/
 /tmp/
+
+*.gem

data/README.md

@@ -1,8 +1,6 @@
-# HerokuBuilder
+# Heroku Builder
 
-Welcome to your new gem! In this directory, you'll find the files you need to be able to package up your Ruby library into a gem. Put your Ruby code in the file `lib/heroku_builder`. To experiment with that code, run `bin/console` for an interactive prompt.
-
-TODO: Delete this and the text above, and describe your gem
+Heroku Builder allows for straight forward configuration of your multi (or single) stage Heroku application as well as dead simple deployment.  It uses a YAML configuration to manage a multi-environment configuration, including: configuration variables, resources, add-ons, and git based deployment.
 
 ## Installation
 
@@ -22,7 +20,154 @@ Or install it yourself as:
 
 ## Usage
 
-TODO: Write usage instructions here
+### Getting Started
+
+To get started, generate a new configuration file:
+
+    $ rake builder:init
+
+This will place a file `config/heroku.yml with some basic configuration options. You'll want update the configuration files as you see fit for your particular setup.  The configuration file is the meat of this tool, so let's take a look at what we can do with it.
+
+### Configuration
+
+When you open `config/heroku.yml`, you'll see something like this:
+
+```yaml
+staging:
+  app:
+    name: my-heroku-app-name-staging
+    git_repo: git@github.com:foo/my-heroku-app-name
+    git_branch: staging
+  config_vars: []
+  addons: []
+  resources:
+    web:
+      count: 1
+      type: Free
+production:
+  app:
+    name: my-heroku-app-name
+    git_repo: git@github.com:foo/my-heroku-app-name
+    git_branch: master
+  config_vars: []
+  addons: []
+  resources:
+    web:
+      count: 1
+      type: Free
+
+```
+
+Let's start from the outside and work our way in.
+
+`staging` and `production` are references to the environments you maintain for a particular application.  You can add as many of these as you'd like.  These environments also determine the environment a Rake task targets.  For example:
+
+    $ rake builder:staging:apply
+
+Would apply the configuration for the `staging` environment.
+
+The `app` sections provides settings particular to the application.
+* `name` - the Heroku application name.  The application will be created unless it already exists on Heroku.
+* `git_repo` - the repository the project code is kept in.  Code will be checked out from this repository as part of the deploy process, so you'll need at least read permission on the repo to deploy code to Heroku.
+* `git_branch` - the branch of the `git_repo` repo that you wish to deploy from.
+
+The `config_vars` setting allows you to set Config Vars for a particular environment.  These can be applied as follows:
+
+```yaml
+config_vars:
+  FOO: bar
+  BAZ: <%= ENV['BAZ'] %>
+```
+
+Variables can be set with either a string or ERB tags.  ERB tags allow sensitive information to be kept out of code that is committed.  It's important to know that Heroku Builder only adds or updates variables that are defined in the configuration. Variables that are set in the Heroku console, but not defined in your configuration will not be removed.
+
+The `addons` section allows you to define the Add-ons for a particular application. Add-ons are defined as an array:
+
+```yaml
+  addons:
+    - papertrail
+    - heroku-postgresql:hobby-dev
+    - heroku-redis:hobby-dev
+    - scheduler:standard
+```
+
+As with other sections, be aware that removing add-on items will not cause them to be deleted from Heroku.  Removing add-ons should be handled through the Heroku Dashboard.
+
+The `resources` section allows a user to define the resource types and counts.  An example of a resource section for a side project might look like:
+
+```yaml
+resources:
+    web:
+      count: 1
+      type: Free
+    worker:
+      count: 1
+      type: Free
+```
+
+For a production website, it might look more like:
+```yaml
+resources:
+    web:
+      count: 8
+      type: 2X
+    worker:
+      count: 4
+      type: 1X
+```
+
+### Heroku API Key
+
+Heroku Builder requires a Heroku API key. Directions for generating a key are here: [Heroku API Key](https://devcenter.heroku.com/articles/platform-api-quickstart)
+
+The gem will look for the key in the HEROKU_API_KEY environment variable.  The key can be set either in your environment variable library (ex. dotenv):
+
+```
+# .env.local
+HEROKU_API_KEY=xxxxxxxx-xxxx-xxxx-xxxxxxxxxxxxxxxxx
+```
+
+or in front of the rake task:
+
+```
+HEROKU_API_KEY=xxxxxxxx-xxxx-xxxx-xxxxxxxxxxxxxxxxx rake builder:staging:apply
+```
+
+
+
+### Running Rake Tasks
+
+Heroku Builder currently has two actions: `apply` and `deploy`.  Apply will:
+
+* Create the application, if it has not been created
+* Set Config-vars (if there are changes)
+* Deploy code (if there are changes)
+* Configure Add-ons (if there are changes)
+* Configure Resources (if there are changes)
+
+As `apply` only adds or updates when your `heroku.yml` file has changes, it's safe to always use `apply` to deploy code.  Alternatively, you can just run the `deploy` portion.  Deploy will:
+
+* Switch to the branch for that environment
+* Pull down any remote changes
+* Create a remote for Heroku, if the remote is not present
+* Push to that remote
+
+The environments defined in your `heroku.yml` file provide scope for the Heroku Builder rake tasks.  If you have the following:
+
+```yaml
+foo:
+  ...
+bar:
+  ...
+```
+
+The four rake options would be:
+
+    $ rake builder:foo:apply
+    $ rake builder:foo:deploy
+    $ rake builder:bar:apply
+    $ rake builder:bar:deploy
+
 
 ## Development
 

data/heroku_builder.gemspec

@@ -9,8 +9,8 @@ Gem::Specification.new do |spec|
   spec.authors       = ['Jason Vanderhoof']
   spec.email         = ['jvanderhoof (at) google mail']
 
-  spec.summary       = %q{Add the ability to generate multiple heroku application environments and configurations.}
-  spec.description   = %q{Add the ability to generate multiple heroku application environments and configurations.}
+  spec.summary       = %q{Generate and manage multi-environment Heroku application and simple deployment.}
+  spec.description   = %q{Heroku Builder allows for straight forward configuration of your multi (or single) stage Heroku application as well as dead simple deployment.  It uses a YAML configuration to manage a multi-environment configuration, including: configuration variables, resources, add-ons, and git based deployment.}
   spec.homepage      = 'https://github.com/jvanderhoof/heroku_builder.'
   spec.license       = 'MIT'
 

data/lib/heroku_builder/base.rb

@@ -1,6 +1,9 @@
 module HerokuBuilder
   class Base
     def conn
+      unless ENV['HEROKU_API_KEY']
+        fail 'No Heroku API Key found, please set it using the HEROKU_API_KEY environment variable'
+      end
       @conn ||= ::PlatformAPI.connect_oauth(ENV['HEROKU_API_KEY'])
     end
   end

data/lib/heroku_builder/service.rb

@@ -32,7 +32,12 @@ module HerokuBuilder
       Resource.new.set_resources(name, resources)
     end
 
-    def self.process(environment)
+    def self.deploy(environment)
+      name = config_from_environment(environment)['app']['name']
+      run_deployment(name, environment)
+    end
+
+    def self.apply(environment)
       config = config_from_environment(environment)
       name = config['app']['name']
 
@@ -43,7 +48,7 @@ module HerokuBuilder
       update_env_vars(name, environment)
 
       # deploy code
-      # run_deployment(name, environment)
+      run_deployment(name, environment)
 
       # find or create addons
       update_addons(name, environment)

data/lib/heroku_builder/version.rb

@@ -1,3 +1,3 @@
 module HerokuBuilder
-  VERSION = "0.1.0"
+  VERSION = "0.1.1"
 end

data/lib/tasks/heroku_builder.rake

@@ -1,27 +1,69 @@
 require 'heroku_builder'
 
 namespace :builder do
-  # Utility functions from development
-  # These may be removed...
+  # Utility functions from development. These may be removed...
   def pretty_print(hsh)
     hsh.keys.sort.each do |key|
       puts "#{key}: #{hsh[key].inspect}"
     end
   end
 
-  # Rake setup
-  HerokuBuilder::Service.config_file.keys.each do |env|
-    namespace env.to_sym do
-      task :update do
-        HerokuBuilder::Service.process(env)
-      end
+  def config_file
+    'config/heroku.yml'
+  end
+
+  # Rake setup per environment
+  if File.exist?(config_file)
+    HerokuBuilder::Service.config_file.keys.each do |env|
+      namespace env.to_sym do
+        task :apply do
+          HerokuBuilder::Service.apply(env)
+        end
 
-      # task :plan do
-      #   changes('backstage').each do |change|
-      #     puts change
-      #   end
-      # end
+        task :deploy do
+          HerokuBuilder::Service.deploy(env)
+        end
+
+        # task :plan do
+        #   changes('backstage').each do |change|
+        #     puts change
+        #   end
+        # end
+      end
     end
   end
 
+  desc 'Initial yaml file setup'
+  task :init do
+    if File.exist?(config_file)
+      puts "Heroku Builder configaration file alread exists: `#{config_file}`.  Please remove it if you want to generate a new configaration file."
+      exit
+    end
+
+    env_config = {
+      'app' => {
+        'name' => 'my-heroku-app-name',
+        'git_repo' =>  'git@github.com:foo/my-heroku-app-name',
+        'git_branch' =>  'master'
+      },
+      'config_vars' =>  [],
+      'addons' =>  [],
+      'resources' =>  {
+        'web' =>  {
+          'count' =>  1,
+          'type' =>  'Free'
+        }
+      }
+    }
+    config = {
+      'staging' => Marshal.load(Marshal.dump(env_config)),
+      'production' => Marshal.load(Marshal.dump(env_config))
+    }
+    config['staging']['app']['name'] = config['staging']['app']['name']+'-staging'
+    config['staging']['app']['git_branch'] = 'staging'
+
+    FileUtils.mkdir_p('config')
+    File.open(config_file, 'w') { |f| f.write(config.to_yaml) }
+    puts "Heroku Builder configuration file generated in `#{config_file}`"
+  end
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: heroku_builder
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.1.1
 platform: ruby
 authors:
 - Jason Vanderhoof
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2015-10-12 00:00:00.000000000 Z
+date: 2015-10-14 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: platform-api
@@ -94,8 +94,10 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '3.3'
-description: Add the ability to generate multiple heroku application environments
-  and configurations.
+description: 'Heroku Builder allows for straight forward configuration of your multi
+  (or single) stage Heroku application as well as dead simple deployment.  It uses
+  a YAML configuration to manage a multi-environment configuration, including: configuration
+  variables, resources, add-ons, and git based deployment.'
 email:
 - jvanderhoof (at) google mail
 executables: []
@@ -148,6 +150,5 @@ rubyforge_project:
 rubygems_version: 2.4.5.1
 signing_key: 
 specification_version: 4
-summary: Add the ability to generate multiple heroku application environments and
-  configurations.
+summary: Generate and manage multi-environment Heroku application and simple deployment.
 test_files: []