chicken_soup 0.5.3 → 0.6.0

data/README.md

@@ -1,16 +1,136 @@
-Chicken Soup... for the Deployment Soul
-================================
+![Chicken Soup... for the Deployer's Soul](http://www.thekompanee.com/public_files/chicken-soup.png)
 
-TODO
+Even more opinionated than Capistrano itself, Chicken Soup adds a lot of useful tasks
+specifically for those who want to DRY up deploying their Rails applications.
 
-Issues
-------
+Interface
+------------------------
+Whether deploying to Heroku or your own servers, Chicken Soup gives you one command
+interface to do it all.
+
+Capabilities
+------------------------
+Chicken Soup makes it easy to only use the functionality you need.  Out of the box it
+comes with:
+
+  * Heroku
+  * Unix Server
+  * Apache
+  * Nginx
+  * RVM
+  * Bundler
+  * Isolate (coming soon)
+  * Git
+  * Github
+  * Subversion (partial)
+  * Passenger
+  * Postgres
+  * MySQL
+
+Notifiers
+------------------------
+Executing items to notify upon a successful deployment is a breeze.  Chicken Soup comes
+loaded with:
+
+  * Email
+  * Git Tagging
+
+Installation
+------------------------
+    gem install chicken_soup
+
+or
+
+    gem chicken_soup, :require => false
+
+in your Gemfile.
+
+Run the included generator to create Rake tasks that Chicken Soup will need to do awesome stuff
+on the server.
+
+    rails generate chicken_soup:add_ingredients
+
+This will also modify your Capfile (or create it if you don't have one) and install a file in
+`lib/recipes/` which will load Chicken Soup when you invoke Capistrano.
+
+Finally, you'll get a deploy.rb template that will get you started with your Chicken Soup
+experience.
+
+Getting Started
+------------------------
+Chicken Soup is all about sensible defaults.  Any of which can be overridden in your deploy.rb
+file.
+
+Let's take a common example.  You're deploying to your Unix server and you have your code
+repository stored on Github.  You use Bundler to handle all of your gem needs and RVM is installed
+to manage your Ruby versions.  Instead of remembering all kinds of random configurations such
+as `default_run_options[:pty] = true` or where you need to include the Capistrano helpers for Bundler,
+you can put this in your deploy.rb file:
+
+    set :application,     'myapplication'
+    set :capabilities,    [:unix, :github, :bundler, :rvm]
+
+    set :deployment_type, :unix
+
+And you can deploy with:
+
+    cap <staging|production> deploy
 
+Want to add automatic Nginx integration?  Just add :nginx to your capabilities list and your deployment
+will do the right thing.
+
+Wnat to migrate your application's DB automatically during deployment?  Add :mysql or :postgres to your
+capabilities list.
+
+How Does This Work?
+------------------------
+Well, that's what we mean by 'sensible defaults'.  Using the above configuration, Chicken Soup will infer
+certain things.  For example, it will look in your gitconfig file for either a github username or a git
+username.  If either of these are found, it will assume your source code can be retrieved from:
+
+    git://github.com/your_username/myapplication
+
+To figure out the server, it will assume you want to connect to:
+
+    staging.myapplication.com
+
+for staging.  And:
+
+    myapplication.com
+
+for production.
+
+Built-in Multistage Support
+------------------------
+Yes it's required.  It's what makes Chicken Soup 'opinionated'.  In your deploy.rb file, you'll want
+(if you want different settings in staging vs production) to create 2 tasks:
+
+  * :staging
+  * :production
+
+Each of these tasks will contain 'siloed' variables that will only be set when deploying to that
+environment.
+
+__Note: Yes, we know about the Capistrano multi-stage extension but found it not extensible enough or useful
+enough for us to reuse here.  We attempted to keep to the same API in order to make it easy for people to
+transition.__
+
+What Isn't Chicken Soup?
+------------------------
+Chicken Soup is __not__ a server management tool.  It is used for easing deployment woes. In other words,
+use it to `start`, `stop` and `restart` Nginx.  Not to __install__ Nginx.
+
+Making Your Own Chicken Soup
+------------------------
+We attempted to develop Chicken Soup to be as easy as possible to add new notifiers and capabilities to your
+deployments.  Redis, MongoDB, Isolate, Mercurial, they're all fair game.  So get Pull Requestin'!!
+
+Issues
+------------------------
 If you have problems, please create a [Github issue](https://github.com/jfelchner/chicken_soup/issues).
 
 Credits
--------
-
+-------------------------
 ![thekompanee](http://www.thekompanee.com/public_files/kompanee-github-readme-logo.png)
 
 chicken_soup is maintained by [The Kompanee, Ltd.](http://www.thekompanee.com)
@@ -18,7 +138,6 @@ chicken_soup is maintained by [The Kompanee, Ltd.](http://www.thekompanee.com)
 The names and logos for The Kompanee are trademarks of The Kompanee, Ltd.
 
 License
--------
-
+-------------------------
 chicken_soup is Copyright &copy; 2011 The Kompanee. It is free software, and may be redistributed under the terms specified in the LICENSE file.
 

data/lib/chicken_soup/capabilities/apache/apache-checks.rb

@@ -2,6 +2,8 @@
 #                            APACHE CHECKS                           #
 ######################################################################
 Capistrano::Configuration.instance(:must_exist).load do
+  extend ChickenSoup
+
   namespace :capabilities do
     namespace :variable do
       namespace :check do

data/lib/chicken_soup/capabilities/apache/apache-defaults.rb

@@ -1,7 +1,23 @@
 ######################################################################
 #                          APACHE DEFAULTS                           #
 ######################################################################
+module ChickenSoup
+  def find_web_server_control_script
+    if remote_file_exists?("/usr/sbin/apachectl")
+      set :web_server_control_script,   "/usr/sbin/apachectl"
+    elsif remote_file_exists?("/usr/sbin/apache2")
+      set :web_server_control_script,   "/usr/sbin/apache2"
+    elsif remote_file_exists?("/usr/sbin/httpd")
+      set :web_server_control_script,   "/usr/sbin/httpd"
+    end
+
+    abort "Couldn't figure out how to control your installation of Apache" unless exists?(:web_server_control_script)
+  end
+end
+
 Capistrano::Configuration.instance(:must_exist).load do
+  extend ChickenSoup
+
   namespace :capabilities do
     namespace :defaults do
       desc "[internal] Sets intelligent defaults for Apache deployments."
@@ -16,15 +32,3 @@ Capistrano::Configuration.instance(:must_exist).load do
     end
   end
 end
-
-def find_web_server_control_script
-  if remote_file_exists?("/usr/sbin/apachectl")
-    set :web_server_control_script,   "/usr/sbin/apachectl"
-  elsif remote_file_exists?("/usr/sbin/apache2")
-    set :web_server_control_script,   "/usr/sbin/apache2"
-  elsif remote_file_exists?("/usr/sbin/httpd")
-    set :web_server_control_script,   "/usr/sbin/httpd"
-  end
-
-  abort "Couldn't figure out how to control your installation of Apache" unless exists?(:web_server_control_script)
-end

data/lib/chicken_soup/capabilities/bundler/bundler-checks.rb

@@ -2,6 +2,8 @@
 #                           BUNDLER CHECKS                           #
 ######################################################################
 Capistrano::Configuration.instance(:must_exist).load do
+  extend ChickenSoup
+
   namespace :capabilities do
     namespace :variable do
       namespace :check do

data/lib/chicken_soup/capabilities/bundler/bundler-defaults.rb

@@ -2,6 +2,8 @@
 #                          BUNDLER DEFAULTS                          #
 ######################################################################
 Capistrano::Configuration.instance(:must_exist).load do
+  extend ChickenSoup
+
   namespace :capabilities do
     namespace :defaults do
       desc "[internal] Sets intelligent defaults for Bundler deployments."

data/lib/chicken_soup/capabilities/bundler/bundler-tasks.rb

@@ -2,24 +2,31 @@
 #                           BUNDLER TASKS                            #
 ######################################################################
 Capistrano::Configuration.instance(:must_exist).load do
+  extend ChickenSoup
+
   before    'gems:install',       'bundler:install'
 
   run_task  'bundler:install',    :as => manager_username
 
   namespace :gems do
-    desc "Install Bundled Gems"
+    desc "Processes the file containing all of the gems that you want installed and installs them one-by-one."
     task :install, :roles => :app do
-      run_with_rvm rvm_ruby_string, "bundle install --gemfile #{latest_release}/Gemfile --path #{gem_packager_gem_path} --deployment --without development test"
+      run_with_ruby_manager full_ruby_environment_string, "bundle install --gemfile #{latest_release}/Gemfile --path #{gem_packager_gem_path} --deployment --without development test"
     end
 
-    desc "Update Bundled Gems"
+    desc <<-DESC
+      Checks for the newest version of each gem and installs it.
+
+      > Note: This can never be used in production.  If you really wish to do this,
+      > you'll need to log into the server manually or use Capistrano's `console` task.
+    DESC
     task :update, :roles => :app do
       abort "I'm sorry Dave, but I can't let you do that. I have full control over production." if rails_env == 'production'
 
       run "cd #{latest_release} && bundle update"
     end
 
-    desc "Remove Bundled Gems"
+    desc "Removes all of the gems currently installed."
     task :clean, :roles => :app do
       run "rm -rf #{gem_packager_gem_path}/*"
     end
@@ -30,11 +37,7 @@ Capistrano::Configuration.instance(:must_exist).load do
     task :install, :roles => :app do
       bundler_install_command = "gem install bundler --version #{gem_packager_version} --no-ri --no-rdoc && gem cleanup bundler"
 
-      if fetch(:capabilities).include? :rvm
-        run_with_rvm "#{ruby_version}@global", bundler_install_command
-      else
-        run bundler_install_command
-      end
+      run_with_ruby_manager "#{ruby_version}@global", bundler_install_command
     end
   end
 end

data/lib/chicken_soup/capabilities/git/git-checks.rb

@@ -0,0 +1,21 @@
+######################################################################
+#                             GIT CHECKS                             #
+######################################################################
+Capistrano::Configuration.instance(:must_exist).load do
+  namespace :capabilities do
+    namespace :variable do
+      namespace :check do
+        desc <<-DESC
+          [internal] Checks to see if all necessary Git variables have been set up.
+        DESC
+        task :rvm do
+          required_variables = [
+            :repository
+          ]
+
+          verify_variables(required_variables)
+        end
+      end
+    end
+  end
+end

data/lib/chicken_soup/capabilities/git/git-defaults.rb

@@ -6,13 +6,12 @@ Capistrano::Configuration.instance(:must_exist).load do
     namespace :defaults do
       desc "[internal] Sets intelligent version control defaults for deployments"
       task :git do
-        _cset :github_account,            ENV["USER"]
         _cset :deploy_via,                :remote_cache
 
         set :scm,                         :git
-        set(:repository)                  { "git@github.com:#{github_account}/#{application}.git" }
         set(:branch)                      { `git branch`.match(/\* (\S+)\s/m)[1] || raise("Couldn't determine current branch") }
         set(:remote)                      { `git remote`.match(/(\S+)\s/m)[1] || raise("Couldn't determine default remote repository") }
+
         ssh_options[:forward_agent]       = true
       end
     end

data/lib/chicken_soup/capabilities/github/github-defaults.rb

@@ -0,0 +1,23 @@
+######################################################################
+#                          GITHUB DEFAULTS                           #
+######################################################################
+require   'chicken_soup/capabilities/git/git-defaults'
+
+Capistrano::Configuration.instance(:must_exist).load do
+  before    'capabilities:defaults:github',     'capabilities:defaults:git'
+
+  namespace :capabilities do
+    namespace :defaults do
+      desc "[internal] Sets defaults for deployments from Github"
+      task :github do
+        gitconfig_github_user             = `git config --get github.user`.chomp
+
+        _cset :github_account,            gitconfig_github_user != '' ? gitconfig_github_user : local_user
+        _cset :github_repository,         application
+
+        set :github_url,                  "https://github.com/#{github_account}/#{github_repository}"
+        set(:repository)                  { "git@github.com:#{github_account}/#{github_repository}.git" }
+      end
+    end
+  end
+end

data/lib/chicken_soup/capabilities/github/github-tasks.rb

@@ -0,0 +1,14 @@
+######################################################################
+#                          GITHUB TASKS                              #
+######################################################################
+Capistrano::Configuration.instance(:must_exist).load do
+  namespace :git do
+    desc <<-DESC
+      Opens the default browser so that you can view the commit that
+      is currently on the specified environment.
+    DESC
+    task :browse do
+      `open #{github_url}/tree/#{current_revision}`
+    end
+  end
+end

data/lib/chicken_soup/capabilities/heroku/heroku-checks.rb

@@ -2,6 +2,8 @@
 #                           HEROKU CHECKS                            #
 ######################################################################
 Capistrano::Configuration.instance(:must_exist).load do
+  extend ChickenSoup
+
   namespace :capabilities do
     namespace :variable do
       namespace :check do

data/lib/chicken_soup/capabilities/heroku/heroku-defaults.rb

@@ -2,6 +2,8 @@
 #                           HEROKU DEFAULTS                          #
 ######################################################################
 Capistrano::Configuration.instance(:must_exist).load do
+  extend ChickenSoup
+
   namespace :capabilities do
     namespace :defaults do
       desc "[internal] Sets intelligent defaults for Heroku deployments"

data/lib/chicken_soup/capabilities/mysql/mysql-checks.rb

@@ -0,0 +1,32 @@
+######################################################################
+#                             MYSQL CHECKS                           #
+######################################################################
+Capistrano::Configuration.instance(:must_exist).load do
+  require 'chicken_soup/capabilities/shared/db-checks'
+
+  namespace :capabilities do
+    namespace :variable do
+      namespace :check do
+        desc <<-DESC
+          [internal] Checks to see if all necessary MySQL capabilities variables have been set up.
+        DESC
+        task :mysql do
+          capabilities.variable.check.db
+        end
+      end
+    end
+  end
+
+  namespace :capabilities do
+    namespace :deployment do
+      namespace :check do
+        desc <<-DESC
+          [internal] Checks to see MySQL is ready for deployment.
+        DESC
+        task :mysql do
+          capabilities.deployment.check.db
+        end
+      end
+    end
+  end
+end

data/lib/chicken_soup/capabilities/nginx/nginx-checks.rb

@@ -2,6 +2,8 @@
 #                             NGINX CHECKS                           #
 ######################################################################
 Capistrano::Configuration.instance(:must_exist).load do
+  extend ChickenSoup
+
   namespace :capabilities do
     namespace :variable do
       namespace :check do

data/lib/chicken_soup/capabilities/nginx/nginx-defaults.rb

@@ -1,7 +1,19 @@
 ######################################################################
 #                           NGINX DEFAULTS                           #
 ######################################################################
+module ChickenSoup
+  def find_web_server_control_script
+    if remote_file_exists?("/etc/init.d/nginx")
+      set :web_server_control_script,   "/etc/init.d/nginx"
+    end
+
+    abort "Couldn't figure out how to control your installation of Nginx" unless exists?(:web_server_control_script)
+  end
+end
+
 Capistrano::Configuration.instance(:must_exist).load do
+  extend ChickenSoup
+
   namespace :capabilities do
     namespace :defaults do
       desc "[internal] Checks to see what type of Nginx installation is running on the remote."
@@ -11,11 +23,3 @@ Capistrano::Configuration.instance(:must_exist).load do
     end
   end
 end
-
-def find_web_server_control_script
-  if remote_file_exists?("/etc/init.d/nginx")
-    set :web_server_control_script,   "/etc/init.d/nginx"
-  end
-
-  abort "Couldn't figure out how to control your installation of Nginx" unless exists?(:web_server_control_script)
-end

data/lib/chicken_soup/capabilities/postgres/postgres-checks.rb

@@ -16,4 +16,17 @@ Capistrano::Configuration.instance(:must_exist).load do
       end
     end
   end
+
+  namespace :capabilities do
+    namespace :deployment do
+      namespace :check do
+        desc <<-DESC
+          [internal] Checks to see Postgres is ready for deployment.
+        DESC
+        task :postgres do
+          capabilities.deployment.check.db
+        end
+      end
+    end
+  end
 end

data/lib/chicken_soup/capabilities/rvm/rvm-checks.rb

@@ -2,6 +2,8 @@
 #                             RVM CHECKS                             #
 ######################################################################
 Capistrano::Configuration.instance(:must_exist).load do
+  extend ChickenSoup
+
   namespace :capabilities do
     namespace :variable do
       namespace :check do
@@ -12,8 +14,8 @@ Capistrano::Configuration.instance(:must_exist).load do
           required_variables = [
             :rvmrc_file,
             :ruby_version,
-            :rvm_gemset,
-            :rvm_ruby_string,
+            :ruby_gemset,
+            :full_ruby_environment_string,
           ]
 
           verify_variables(required_variables)
@@ -26,11 +28,11 @@ Capistrano::Configuration.instance(:must_exist).load do
         task :rvm do
           abort "Could not find an .rvmrc file at #{rvmrc_file}. To use the RVM capability, you must have a valid local .rvmrc file." unless File.exist?(rvmrc_file)
 
-          rvmrc_file_contents         = capture("cat #{current_path}/.rvmrc", :roles => :app)
-          set :current_rvm_ruby_string, rvmrc_file_contents.match(ChickenSoup::RVM_INFO_FORMAT)[1]
+          rvmrc_file_contents                 = capture("cat #{current_path}/.rvmrc", :roles => :app)
+          set :current_ruby_environment_string, rvmrc_file_contents.match(ChickenSoup::RVM_INFO_FORMAT)[1]
 
           unless ruby_version_update_pending
-            abort "'#{rvm_ruby_string}' does not match the version currently installed on the server (#{current_rvm_ruby_string}).  Please run 'cap <environment> ruby:update deploy:subzero' if you would like to upgrade your Ruby version prior to deploying." unless current_rvm_ruby_string == rvm_ruby_string
+            abort "'#{full_ruby_environment_string}' does not match the version currently installed on the server (#{current_ruby_environment_string}).  Please run 'cap <environment> ruby:update deploy:subzero' if you would like to upgrade your Ruby version prior to deploying." unless current_ruby_environment_string == full_ruby_environment_string
           end
         end
       end

data/lib/chicken_soup/capabilities/rvm/rvm-defaults.rb

@@ -1,9 +1,13 @@
 ######################################################################
 #                           RVM DEFAULTS                             #
 ######################################################################
-::ChickenSoup::RVM_INFO_FORMAT = /^rvm.+\s(([a-zA-Z0-9\-\._]+)(?:@([a-zA-Z0-9\-\._]+))?)/
+module ChickenSoup
+  RVM_INFO_FORMAT = /^rvm.+\s(([a-zA-Z0-9\-\._]+)(?:@([a-zA-Z0-9\-\._]+))?)/
+end
 
 Capistrano::Configuration.instance(:must_exist).load do
+  extend ChickenSoup
+
   namespace :capabilities do
     namespace :defaults do
       _cset :rvmrc_file,                    File.join(rails_root, '.rvmrc')
@@ -14,12 +18,12 @@ Capistrano::Configuration.instance(:must_exist).load do
         contents.match(ChickenSoup::RVM_INFO_FORMAT)[2]
       end
 
-      _cset(:rvm_gemset)          do
+      _cset(:ruby_gemset)         do
         contents = File.read(rvmrc_file)
         contents.match(ChickenSoup::RVM_INFO_FORMAT)[3]
       end
 
-      _cset(:rvm_ruby_string)     {rvm_gemset ? "#{ruby_version}@#{rvm_gemset}" : ruby_version}
+      _cset(:full_ruby_environment_string)      {ruby_gemset ? "#{ruby_version}@#{ruby_gemset}" : ruby_version}
     end
   end
 end

data/lib/chicken_soup/capabilities/rvm/rvm-tasks.rb

@@ -1,11 +1,15 @@
 ######################################################################
 #                             RVM TASKS                              #
 ######################################################################
-def run_with_rvm(ruby_env_string, command)
-  run("rvm use #{ruby_env_string} && #{command}")
+module ChickenSoup
+  def run_with_ruby_manager(ruby_env_string, command, options = {})
+    run "rvm use #{ruby_env_string} && #{command}", options
+  end
 end
 
 Capistrano::Configuration.instance(:must_exist).load do
+  extend ChickenSoup
+
   run_task 'ruby:update', :as => manager_username
 
   namespace :ruby do
@@ -23,8 +27,8 @@ Capistrano::Configuration.instance(:must_exist).load do
 
         set     :ruby_version_update_pending,   false
 
-        run("rvm use --create #{rvm_ruby_string}")
-        run("rvm wrapper #{rvm_ruby_string} #{application_server_type}")
+        run("rvm use --create #{full_ruby_environment_string}")
+        run("rvm wrapper #{full_ruby_environment_string} #{application_server_type}")
       else
         set     :ruby_version_update_pending,   true
       end

data/lib/chicken_soup/capabilities/shared/db-checks.rb

@@ -2,6 +2,8 @@
 #                              DB CHECKS                             #
 ######################################################################
 Capistrano::Configuration.instance(:must_exist).load do
+  extend ChickenSoup
+
   namespace :capabilities do
     namespace :variable do
       namespace :check do

data/lib/chicken_soup/capabilities/shared/db-defaults.rb

@@ -2,6 +2,8 @@
 #                             DB DEFAULTS                            #
 ######################################################################
 Capistrano::Configuration.instance(:must_exist).load do
+  extend ChickenSoup
+
   namespace :capabilities do
     namespace :defaults do
       desc "[internal] Sets intelligent defaults for DB deployments."

data/lib/chicken_soup/capabilities/shared/db-tasks.rb

@@ -2,12 +2,15 @@
 #                          COMMON DB TASKS                           #
 ######################################################################
 Capistrano::Configuration.instance(:must_exist).load do
+  extend ChickenSoup
+
   _cset(:db_root_password)    {Capistrano::CLI.password_prompt("Root Password For DB: ")}
   _cset(:db_app_password)     {Capistrano::CLI.password_prompt("App Password For DB: ")}
 
   run_task  "db:create",       :as => manager_username
   run_task  "db:drop",         :as => manager_username
 
+  before    "deploy:cleanup",  "deploy:migrate"
   before    "deploy:migrate",  "db:backup"        unless skip_backup_before_migration
 
   namespace :db do
@@ -25,23 +28,26 @@ Capistrano::Configuration.instance(:must_exist).load do
       end
     end
 
-    desc <<-DESC
-      Creates an easy way to debug remote data locally.
-
-      * Running this task will create a dump file of all the data in the specified
-        environment.
-      * Copy the dump file to the local machine
-      * Drop and recreate all local databases
-      * Import the dump file
-      * Bring the local DB up-to-date with any local migrations
-      * Prepare the test environment
-    DESC
     namespace :pull do
+      desc <<-DESC
+        Creates an easy way to debug remote data locally.
+
+        * Running this task will create a dump file of all the data in the specified
+          environment.
+        * Copy the dump file to the local machine
+        * Drop and recreate all local databases
+        * Import the dump file
+        * Bring the local DB up-to-date with any local migrations
+        * Prepare the test environment
+      DESC
       task :default, :roles => :db, :only => {:primary => true} do
         db.backup.default
         db.pull.latest
       end
 
+      desc <<-DESC
+        Just like `db:pull` but doesn't create a new backup first.
+      DESC
       task :latest, :roles => :db, :only => {:primary => true} do
         latest_backup = capture(%Q{ls #{db_backups_path} -xtC | head -n 1 | cut -d " " -f 1}).chomp
 

data/lib/chicken_soup/capabilities/shared/web_server-tasks.rb

@@ -2,6 +2,8 @@
 #                    COMMON WEB SERVER TASKS                         #
 ######################################################################
 Capistrano::Configuration.instance(:must_exist).load do
+  extend ChickenSoup
+
   run_task  'web_server:stop',            :as => manager_username
   run_task  'web_server:start',           :as => manager_username
   run_task  'web_server:restart',         :as => manager_username

data/lib/chicken_soup/capabilities/svn/svn-defaults.rb

@@ -2,6 +2,8 @@
 #                         SUBVERSION DEFAULTS                        #
 ######################################################################
 Capistrano::Configuration.instance(:must_exist).load do
+  extend ChickenSoup
+
   namespace :capabilities do
     namespace :defaults do
       desc "[internal] Sets intelligent version control defaults for deployments"

data/lib/chicken_soup/capabilities/unix/unix-checks.rb

@@ -2,6 +2,8 @@
 #                             UNIX CHECKS                            #
 ######################################################################
 Capistrano::Configuration.instance(:must_exist).load do
+  extend ChickenSoup
+
   namespace :capabilities do
     namespace :variable do
       namespace :check do