chicken_soup 0.1.0 → 0.2.0

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

@@ -0,0 +1,12 @@
+######################################################################
+#                          SUBVERSION TASKS                          #
+######################################################################
+Capistrano::Configuration.instance(:must_exist).load do
+  namespace :vc do
+    desc <<-DESC
+    DESC
+    task :log do
+      set :vc_log, `svn log -r #{previous_revision.to_i + 1}:#{current_revision}`
+    end
+  end
+end

data/lib/chicken_soup/capabilities/tasks.rb

@@ -0,0 +1,12 @@
+Capistrano::Configuration.instance(:must_exist).load do
+  before  'capabilities:load_tasks',      'load_capability_tasks'
+
+  namespace :capabilities do
+    desc <<-DESC
+      [internal] A helper task used to load all of the tasks associated with the
+      requested capabilities.
+    DESC
+    task :load_tasks do
+    end
+  end
+end

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

@@ -0,0 +1,33 @@
+######################################################################
+#                             UNIX CHECKS                            #
+######################################################################
+Capistrano::Configuration.instance(:must_exist).load do
+  namespace :capabilities do
+    namespace :check do
+      desc <<-DESC
+        [internal] Checks to see if all necessary unix environment variables have been set up.
+      DESC
+      task :unix do
+        required_variables = [
+          :user,
+          :deployment_username,
+          :manager_username,
+          :user_home,
+          :deployment_user_home,
+          :manager_user_home,
+          :deploy_base_dir,
+          :deploy_site_name,
+          :deploy_to,
+          :app_server_ip,
+          :web_server_ip,
+          :db_server_ip,
+          :web_server_name,
+          :app_server_name,
+          :db_server_name
+        ]
+
+        verify_variables(required_variables)
+      end
+    end
+  end
+end

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

@@ -0,0 +1,42 @@
+######################################################################
+#                         UNIX SERVER DEFAULTS                       #
+######################################################################
+Capistrano::Configuration.instance(:must_exist).load do
+  namespace :capabilities do
+    namespace :defaults do
+      desc "[internal] Sets intelligent defaults for unix server deployments."
+      task :unix do
+        _cset :deployment_username,   "deploy"
+        _cset :manager_username,      "manage"
+        _cset :user,                  deployment_username
+
+        _cset :user_home,             "/home/#{user}"
+        _cset :manager_user_home,     "/home/#{manager_username}"
+        _cset :deployment_user_home,  "/home/#{deployment_username}"
+        _cset :deploy_base_dir,       "/var/www"
+        _cset :deploy_site_name,      domain
+        set   :deploy_to,             "#{deploy_base_dir}/#{deploy_site_name}"
+
+        _cset :app_server_ip,         default_server_ip
+        _cset :web_server_ip,         default_server_ip
+        _cset :db_server_ip,          default_server_ip
+
+        _cset :default_server_name,   domain
+
+        _cset(:app_server_name)       { default_server_name }
+        _cset(:web_server_name)       { default_server_name }
+        _cset(:db_server_name)        { default_server_name }
+
+        # Evidently roles can't be assigned in a namespace :-/
+        set_unix_server_roles
+      end
+    end
+  end
+
+  desc "[internal] This task is only here because `role` cannot be used within a `namespace`"
+  task :set_unix_server_roles do
+    role :web,                  web_server_name, :primary => true
+    role :app,                  app_server_name, :primary => true
+    role :db,                   db_server_name,  :primary => true
+  end
+end

data/lib/chicken_soup/capabilities/{unix.rb → unix/unix-tasks.rb}

@@ -52,18 +52,18 @@ Capistrano::Configuration.instance(:must_exist).load do
 
   namespace :os do
     namespace :users do
-      namespace :root do
+      namespace :superuser do
         desc <<-DESC
-          [internal] Switches Capistrano to use the root user for all subsequent SSH actions.
+          [internal] Switches Capistrano to use the superuser account for all subsequent SSH actions.
 
-          It will prompt for the root user's password the first time it's needed.
+          It will prompt for the superuser's password the first time it's needed.
         DESC
         task :use do
           set_user_to("root")
         end
       end
 
-      namespace :manager do
+      namespace :manage do
         desc <<-DESC
           [internal] Switches Capistrano to use the manager user for all subsequent SSH actions.
 
@@ -89,82 +89,3 @@ Capistrano::Configuration.instance(:must_exist).load do
     end
   end
 end
-
-######################################################################
-#                             UNIX CHECKS                            #
-######################################################################
-Capistrano::Configuration.instance(:must_exist).load do
-  namespace :capabilities do
-    namespace :check do
-      desc <<-DESC
-        [internal] Checks to see if all necessary unix environment variables have been set up.
-      DESC
-      task :unix do
-        required_variables = [
-          :user,
-          :deployment_username,
-          :manager_username,
-          :user_home,
-          :deployment_user_home,
-          :manager_user_home,
-          :deploy_dir,
-          :deploy_name,
-          :deploy_to,
-          :app_server_ip,
-          :web_server_ip,
-          :db_server_ip,
-          :web_server_name,
-          :app_server_name,
-          :db_server_name
-        ]
-
-        verify_variables(required_variables)
-      end
-    end
-  end
-end
-
-######################################################################
-#                         UNIX SERVER DEFAULTS                       #
-######################################################################
-Capistrano::Configuration.instance(:must_exist).load do
-  namespace :capabilities do
-    namespace :defaults do
-      desc "[internal] Sets intelligent defaults for unix server deployments."
-      task :unix do
-        _cset :deployment_username,   "deploy"
-        _cset :manager_username,      "manager"
-        _cset :user,                  deployment_username
-
-        _cset :user_home,             "/home/#{user}"
-        _cset :manager_user_home,     "/home/#{manager_username}"
-        _cset :deployment_user_home,  "/home/#{deployment_username}"
-        _cset :deploy_dir,            "/var/www"
-        _cset :deploy_name,           "#{application_short}.#{domain}"
-        set   :deploy_to,             "#{deploy_dir}/#{deploy_name}"
-
-        _cset :keep_releases,         15
-
-        _cset :global_shared_files,   ["config/database.yml"]
-
-        _cset :app_server_ip,         server_ip
-        _cset :web_server_ip,         server_ip
-        _cset :db_server_ip,          server_ip
-
-        _cset :app_server_name,       server_name
-        _cset :web_server_name,       server_name
-        _cset :db_server_name,        server_name
-
-        # Evidently roles can't be assigned in a namespace :-/
-        set_unix_server_roles
-      end
-    end
-  end
-
-  desc "[internal] This task is only here because `role` cannot be used within a `namespace`"
-  task :set_unix_server_roles do
-    role :web,                  web_server_name, :primary => true
-    role :app,                  app_server_name, :primary => true
-    role :db,                   db_server_name,  :primary => true
-  end
-end

data/lib/chicken_soup/deploy.rb

@@ -2,11 +2,6 @@
 #                           DEPLOYMENT TASKS                         #
 ######################################################################
 Capistrano::Configuration.instance(:must_exist).load do
-  before "deploy",          "deploy:web:disable"
-  after  "deploy",          "deploy:web:enable"
-
-  before "deploy:migrate",  "db:backup"
-
   namespace :deploy do
     desc <<-DESC
       [internal] The list of tasks used by `deploy`, `deploy:cold`, `deploy:subzero` and `deploy:initial`

data/lib/chicken_soup/environment.rb

@@ -4,4 +4,14 @@
 Capistrano::Configuration.instance(:must_exist).load do
   require 'chicken_soup/environment/defaults'
   require 'chicken_soup/environment/checks'
+  require 'chicken_soup/environment/tasks'
+
+  namespace :environment do
+    desc "[internal] Load the Chicken Soup environment"
+    task :init do
+      environment.defaults.default
+      environment.check
+      environment.load_tasks
+    end
+  end
 end

data/lib/chicken_soup/environment/checks.rb

@@ -1,8 +1,23 @@
 ######################################################################
-#                         ENVIRONMENT CHECKS                         #
+#                         ENVIRONMENT CHECKS
+#
+# Sets up a first-pass environment check for the deployment.
+#
+# First, an environment MUST be present in order for any deployment
+# to happen.  It's a safety measure that this is explicitly stated.
+#
+# It also checks to make sure that the :application and
+# :application_short environment variables have been set.
+#
+# This happens before any of the capabilities have been added to the
+# deployment and therefore that is all we know to check for at this
+# point.
+#
 ######################################################################
 Capistrano::Configuration.instance(:must_exist).load do
-  on :start, 'environment:check', :except => ['staging', 'production']
+  on      :start,               'environment:check',    :except => ['staging', 'production']
+
+  after   'environment:check',  'capabilities:check', 'notifiers:check'
 
   namespace :environment do
     desc "[internal] Checks for environment variables shared among all deployment types."

data/lib/chicken_soup/environment/defaults.rb

@@ -1,9 +1,27 @@
 ######################################################################
-#                         ENVIRONMENT DEFAULTS                       #
+#                         ENVIRONMENT DEFAULTS
+#
+# This is where all of the environment defaults for the tasks are set.
+#
+# None of these defaults are specific to any of the capabilities we
+# will add in later.
+#
+# The main tasks of note are the :staging and :production tasks.  Both
+# of which will set the :rails_env variable so that the rest of the
+# tasks know in what environment they are operating.
+#
+# Note: That these are the 'environment:defaults:staging' and
+# 'environment:defaults:production' tasks and not the 'staging' and
+# 'production' tasks.
+#
+# The latter should be set in the application's deploy.rb file.
+#
 ######################################################################
 Capistrano::Configuration.instance(:must_exist).load do
-  after   'production',                 'environment:defaults:production', 'environment:defaults'
-  after   'staging',                    'environment:defaults:staging',    'environment:defaults'
+  after   'production',                 'environment:defaults:production', 'environment:init'
+  after   'staging',                    'environment:defaults:staging',    'environment:init'
+
+  after   'environment:defaults',       'capabilities:defaults', 'notifiers:defaults'
 
   namespace :environment do
     namespace :defaults do
@@ -24,6 +42,10 @@ Capistrano::Configuration.instance(:must_exist).load do
 
         _cset :copy_compression,          :bz2
 
+        _cset :keep_releases,             15
+
+        _cset :global_shared_files,       ["config/database.yml"]
+
         _cset(:application_short)         {application}
         _cset(:application_underscored)   {application.gsub(/-/, "_")}
       end

data/lib/chicken_soup/environment/tasks.rb

@@ -0,0 +1,12 @@
+######################################################################
+#                         ENVIRONMENT TASKS                          #
+######################################################################
+Capistrano::Configuration.instance(:must_exist).load do
+  after  'environment:load_tasks',      'capabilities:load_tasks', 'notifiers:load_tasks'
+
+  namespace :environment do
+    desc "[internal] A helper task used to load the tasks for all of the capabilities."
+    task :load_tasks do
+    end
+  end
+end

data/lib/chicken_soup/global.rb

@@ -1,8 +1,21 @@
+###
+# Helper method to close all session connections to the remote servers
+#
 def close_sessions
   sessions.values.each { |session| session.close }
   sessions.clear
 end
 
+###
+# Forces all connections to switch to the user passed into it.
+#
+# It will forcibly terminate all open connections in order to accomplish this.
+#
+# @example Switch to the 'deploy' user:
+#   set_user_to 'deploy'
+#
+# @param [String] username The username you would like to begin using.
+#
 def set_user_to(username)
   close_sessions
   set :user,        username
@@ -10,8 +23,35 @@ def set_user_to(username)
   set(:user_home)   { user == "root" ? "/root" : "/home/#{username}" }
 end
 
+###
+# Helper method to run tasks in different contexts.
+#
+# The workflow is as follows:
+# * Current user is saved
+# * User is switched to the desired username passed in via the :as option
+# * The task is run
+# * The user is switched back to the original user
+#
+# By default the task hooks are prepared but the task itself is not executed.
+# You can change this by passing :now as an option.
+#
+# Running a task 'now' does not create hooks. Standard calls to the task will
+# be executed via the current user.
+#
+# @example Always run the task to install gems as the 'manage' user:
+#   run_task 'gems:install', :as => 'manage'
+# @example Run the db migration task now as the 'deploy' user:
+#   run_task 'db:migrate', :as => 'deploy', :now => true
+#
+# @param [String] task_name The name of the task to run.
+# @param [Hash] options Options to customize how the task is run.  Valid options are:
+# @option options [Boolean] :now - If present, the task will be executed immediately.
+# @option options [String]  :as - The name of the user you wish the task to be executed as.
+#
+# @todo Remove all previous hooks prior to adding new ones.  Also disable hooks when running "now"
+#
 def run_task(task_name, options = {})
-  raise "#run_task must be passed an `:as` option so that it knows who to change the user to." unless options[:as]
+  abort "#run_task must be passed an `:as` option so that it knows who to change the user to." unless options[:as]
 
   original_username = exists?(:user) ? user : nil
 
@@ -25,19 +65,54 @@ def run_task(task_name, options = {})
   end
 end
 
+###
+# Checks an array of items to see if they are currently set within the
+# Capistrano scope.  If any of them fail, Capistrano execution will terminate.
+#
+# @param [Array, #each] required_variables An iterable list of items which
+#   represent the names of Capistrano environment variables.  Each item in this
+#   list is expected to be set.
+#
+# @raise [CapistranoGoBoom] Calls #abort on the Capistrano execution if any of
+#   the variables are not set.
+#
+# @example Using an array:
+#   verify_variables [:user, :deploy_base_dir, :app_server]
+#
 def verify_variables(required_variables)
   required_variables.each do |expected_variable|
     abort( "You have not defined '#{expected_variable}' which is necessary for deployment." ) unless exists?(expected_variable)
   end
 end
 
-# Taken from the capistrano code.
+###
+# @note Taken directly from the Capistrano codebase.
+#
+# Sets a variable only if it doesn't already exist.
+#
 def _cset(name, *args, &block)
   unless exists?(name)
     set(name, *args, &block)
   end
 end
 
+###
+# Runs a command on the remote server to see if the file currently exists.
+#
+# @param [String] file The filename (optionally including path) that is may
+#   or may not exist.
+#
+# @return [Boolean] Whether or not the file exists.
+#
+# @example File without path:
+#   remote_file_exists? 'server.log'
+# @example File with path:
+#   remote_file_exists? '/var/www/myappdir/log/production.log'
+#
 def remote_file_exists?(file)
   capture("if [ -f #{file} ]; then echo 'exists'; fi;").chomp == "exists"
 end
+
+def require_if_exists(file)
+  require file if File.exists?(File.join(File.dirname(__FILE__), '..', "#{file}.rb"))
+end

data/lib/chicken_soup/notifiers.rb

@@ -4,11 +4,14 @@
 Capistrano::Configuration.instance(:must_exist).load do
   require 'chicken_soup/notifiers/defaults'
   require "chicken_soup/notifiers/checks"
+  require "chicken_soup/notifiers/tasks"
 
-  desc "[internal] This task is only here because `require` cannot be used within a `namespace`"
-  task :load_notifiers do
-    fetch(:notifiers).each do |notifier|
-      require "chicken_soup/notifiers/#{notifier}"
+  ['defaults', 'checks', 'tasks'].each do |method|
+    desc "[internal] This task is only here because `require` cannot be used within a `namespace`"
+    task "load_notifier_#{method}".to_sym do
+      fetch(:notifiers).each do |notifier|
+        require_if_exists "chicken_soup/notifiers/#{notifier}/#{notifier}-#{method}"
+      end
     end
   end
 end