sunshine 1.2.2 → 1.2.3

data/History.txt

@@ -1,3 +1,17 @@
+=== 1.2.3 / 2011-02-11
+
+* Bugfixes:
+
+  * Completely removed the Healthcheck implementation.
+
+  * Removed superfluous App#upload_tasks method.
+
+  * Changed Apache#bin from apachectl to apache2ctl.
+
+  * Made RsyncRepo available for remote checkout only.
+
+  * Lots of rdoc updates.
+
 === 1.2.2 / 2010-10-13
 
 * Bugfixes:

data/Manifest.txt

@@ -33,7 +33,6 @@ lib/sunshine/daemons/unicorn.rb
 lib/sunshine/dependencies.rb
 lib/sunshine/dependency_lib.rb
 lib/sunshine/exceptions.rb
-lib/sunshine/healthcheck.rb
 lib/sunshine/output.rb
 lib/sunshine/package_managers/apt.rb
 lib/sunshine/package_managers/dependency.rb
@@ -53,7 +52,6 @@ templates/nginx/nginx.conf.erb
 templates/nginx/nginx_optimize.conf
 templates/nginx/nginx_proxy.conf
 templates/rainbows/rainbows.conf.erb
-templates/sunshine/middleware/health.rb
 templates/sunshine/sunshine.rake
 templates/thin/thin.conf.erb
 templates/unicorn/unicorn.conf.erb
@@ -68,7 +66,6 @@ test/unit/test_binder.rb
 test/unit/test_crontab.rb
 test/unit/test_daemon.rb
 test/unit/test_git_repo.rb
-test/unit/test_healthcheck.rb
 test/unit/test_nginx.rb
 test/unit/test_rainbows.rb
 test/unit/test_remote_shell.rb

data/README.txt

@@ -26,19 +26,22 @@ Call sunshine to create the config file:
   Missing config file was created for you: /Users/jsmith/.sunshine
 
   --- 
-  web_directory: /var/www
-  max_deploy_versions: 5
   auto_dependencies: true
+  deploy_env: :development
+  exception_behavior: :revert
+  exclude_paths: []
+  interactive: true
   level: info
-  auto: false
+  max_deploy_versions: 5
   remote_checkouts: false
-  deploy_env: :development
-
+  timeout: 300
+  sigint_behavior: :revert
+  web_directory: /srv/http
 
 You can either use sunshine by requiring the gem in your script, such as
 in a rakefile (which is more common):
 
-  $ rake sunshine:deploy
+  $ rake sunshine:deploy env=qa
 
 Or you can also call built-in sunshine commands:
 
@@ -58,11 +61,11 @@ You have the deploy information and you need to do things involving that
 specific deploy. Rake tasks are great for that, and Sunshine comes with a
 template rake file that you can modify to fit your needs.
 
-You can copy the template rake file to lib/tasks/ by running:
-  $ sunshine --rakefile lib/tasks/.
+You can copy the template rake file to rake/ by running:
+  $ sunshine --rakefile rake/.
 
 If you open the file, you'll see a variety of tasks that handle deployment, to
-application start/stop/restart-ing, to health checks. Most likely, the two tasks
+application start/stop/restart-ing, to status checks. Most likely, the two tasks
 you'll need to update are the :app (for instantiation) and the :deploy tasks.
 
 First off, if you're using rails, you'll probably want to update "task :app" to
@@ -110,12 +113,7 @@ to the @app.deploy block. Here's a sample of completed :app and :deploy tasks:
 And that's it! Try running your Sunshine rake tasks!
 
   rake sunshine:app             # Instantiate Sunshine
-  rake sunshine:db_migrate      # Run db:migrate on remote :db servers
   rake sunshine:deploy          # Deploy the app
-  rake sunshine:health          # Get the health state
-  rake sunshine:health:disable  # Turn off health check
-  rake sunshine:health:enable   # Turn on health check
-  rake sunshine:health:remove   # Remove health check
   rake sunshine:info            # Get deployed app info
   rake sunshine:restart         # Run the remote restart script
   rake sunshine:start           # Run the remote start script
@@ -149,9 +147,9 @@ a block to its deploy method:
   Sunshine::App.deploy(options) do |app|
 
     app_server = Sunshine::Rainbows.new(app)
-    app_server.restart
+    app_server.setup
 
-    Sunshine::Nginx.new(app, :point_to => app_server).restart
+    Sunshine::Nginx.new(app, :point_to => app_server).setup
 
   end
 
@@ -177,7 +175,7 @@ using configuration files.
 The App::new methods support passing a path to a yaml config file:
 
   app = Sunshine::App.new("path/to/config.yml")
-  app.deploy{|app| Sunshine::Rainbows.new(app).restart }
+  app.deploy{|app| Sunshine::Rainbows.new(app).setup }
 
 
 The yaml file can also be any IO stream who's output will parse to yaml.
@@ -188,7 +186,7 @@ information in one place:
     app = Sunshine::App.new
     app = Sunshine::App.new Sunshine::DATA
 
-    app.deploy{|app| Sunshine::Rainbows.new(app).restart }
+    app.deploy{|app| Sunshine::Rainbows.new(app).setup }
 
     __END__
 
@@ -461,6 +459,21 @@ Note: You may notice that you can set a sudo config value on the Sunshine
 module. This is used for the default value of Sunshine::App#sudo and is passed
 along to an app's shells on instantiation.
 
+==== Servers
+
+Because of how unix works with servers and ports, it's not uncommon to have to
+run start/stop/restart server commands with upgraded permissions. This is true
+for Apache and Nginx on ports below 1024. Due to this, servers automatically try
+to adjust their permissions to run their commands correctly. Since servers
+should run their commands consistantly, the only way to affect their sudo value
+is on a server instance basis:
+
+  server = Nginx.new app, :sudo => nil  # let the shell handle sudo
+
+However, the above will most likely cause Nginx's start command to fail if
+shell permissions don't allow running root processes.
+
+Note: Servers will ONLY touch permissions if their port is smaller than 1024.
 
 ==== Dependencies
 
@@ -488,38 +501,27 @@ It can also be set on an individual basis:
   dep.install! :call => shell, :sudo => nil
 
 
-==== Servers
-
-Because of how unix works with servers and ports, it's not uncommon to have to
-run start/stop/restart server commands with upgraded permissions. This is true
-for Apache and Nginx on ports below 1024. Due to this, servers automatically try
-to adjust their permissions to run their commands correctly. Since servers
-should run their commands consistantly, the only way to affect their sudo value
-is on a server instance basis:
-
-  server = Nginx.new app, :sudo => nil  # let the shell handle sudo
-
-However, the above will most likely cause Nginx's start command to fail if
-shell permissions don't allow running root processes.
-
-Note: Servers will ONLY touch permissions if their port is smaller than 1024.
-
-
 == Sunshine Configuration
 
 Aside from passing the sunshine command options, Sunshine can be configured
 both in the deploy script by calling Sunshine.setup and globally in the
 ~/.sunshine file. The following is a list of supported config keys:
 
-'auto'                -> Automate calls; fail instead of prompting the user;
-defaults to false.
-
 'auto_dependencies'   -> Check and install missing deploy dependencies;
 defaults to true.
 
 'deploy_env'          -> The default deploy environment to use;
 defaults to :development.
 
+'exception_behavior'  -> The behavior called when an exception is raised during
+a deploy; defaults to :revert.
+
+'exclude_paths'       -> Paths to exclude in the checkout when deploying code
+with via rsync; defaults to empty Array.
+
+'interactive'         -> Automate calls; fail instead of prompting the user;
+defaults to false.
+
 'level'               -> Logger's debug level; defaults to 'info'.
 
 'max_deploy_versions' -> The maximum number of deploys to keep on a server;
@@ -530,10 +532,16 @@ defaults to false.
 
 'require'             -> Require external ruby libs or gems; defaults to nil.
 
+'timeout'             -> The amount of time in seconds for shells to wait with
+no incoming data before timing out; defaults to 300.
+
+'sigint_behavior'     -> The behavior called when a SIGINT is received during
+a deploy; defaults to :revert.
+
 'trace'               -> Show detailed output messages; defaults to false.
 
 'web_directory'       -> Path to where apps should be deployed to;
-defaults to '/var/www'.
+defaults to '/srv/http'.
 
 
 == Deployed Application Control
@@ -541,13 +549,12 @@ defaults to '/var/www'.
 Sunshine has a variety of commands that allow simple control of
 remote or locally deployed applications. These include start, stop, restart
 actions to be taken application-wide, as well as querying for the
-health and state of the app:
+state of the app:
 
 Examples:
   sunshine run deploy_script.rb
   sunshine restart myapp -r user@server.com,user@host.com
-  sunshine list myapp myotherapp --health -r user@server.com
-  sunshine list myapp --status
+  sunshine list myapp myotherapp --status -r user@server.com
 
 The Sunshine commands are as follows:
   add       Register an app with sunshine
@@ -603,7 +610,7 @@ This is true for the following commands:
 
 (The MIT License)
 
-Copyright (c) 2010
+Copyright (c) 2010 At&t Interactive
 
 Permission is hereby granted, free of charge, to any person obtaining
 a copy of this software and associated documentation files (the

data/Rakefile

@@ -37,10 +37,10 @@ Hoe.plugin :isolate
 
 Hoe.spec 'sunshine' do |p|
   developer('Jeremie Castagna', 'jcastagna@attinteractive.com')
-  self.extra_deps << ['open4',    '>= 1.0.1']
-  self.extra_deps << ['rainbow',  '>= 1.0.4']
-  self.extra_deps << ['highline', '>= 1.5.1']
-  self.extra_deps << ['json',     '>= 1.2.0']
+  self.extra_deps << ['open4',    '~> 1.0.1']
+  self.extra_deps << ['rainbow',  '~> 1.0.4']
+  self.extra_deps << ['highline', '~> 1.5.1']
+  self.extra_deps << ['json',     '~> 1.2.0']
 end
 
 # vim: syntax=Ruby

data/bin/sunshine

@@ -1,4 +1,4 @@
-#!/usr/bin/env ruby -w
+#!/usr/bin/env ruby
 
 begin
   require 'sunshine'

data/examples/deploy_tasks.rake

@@ -80,31 +80,4 @@ namespace :sunshine do
   task :info => :app do
     puts @app.deploy_details.to_yaml
   end
-
-
-  desc "Get the health state"
-  task :health => :app do
-    puts @app.health.to_yaml
-  end
-
-
-  namespace :health do
-
-    desc "Turn on health check"
-    task :enable => :app do
-      puts @app.health(:enable).to_yaml
-    end
-
-
-    desc "Turn off health check"
-    task :disable => :app do
-      puts @app.health(:disable).to_yaml
-    end
-
-
-    desc "Remove health check"
-    task :remove => :app do
-      puts @app.health(:remove).to_yaml
-    end
-  end
 end

data/lib/commands/list.rb

@@ -11,8 +11,6 @@ module Sunshine
   # Options:
   #   -s, --status             Check if an app is running.
   #   -d, --details            Get details about the deployed apps.
-  #   -h, --health [STATUS]    Set or get the healthcheck status.
-  #                            (enable, disable, remove)
   #   -f, --format FORMAT      Set the output format (txt, yml, json)
   #   -u, --user USER          User to use for remote login. Use with -r
   #   -r, --remote svr1,svr2   Run on one or more remote servers.
@@ -157,20 +155,6 @@ module Sunshine
     end
 
 
-    ##
-    # Get or set the healthcheck state.
-    # Returns a response hash (see ListCommand#each_app).
-
-    def health(*app_names)
-      action = app_names.delete_at(0) if Symbol === app_names.first
-
-      each_app(*app_names) do |server_app|
-        server_app.health.send action if action
-        server_app.health.status
-      end
-    end
-
-
     ##
     # Checks if the apps' pids are present.
     # Returns a response hash (see ListCommand#each_app).
@@ -313,14 +297,6 @@ Arguments:
           options['return'] = :details
         end
 
-
-        vals = [:enable, :disable, :remove]
-        desc = "Set or get the healthcheck status. (#{vals.join(", ")})"
-
-        opt.on('-h', '--health [STATUS]', vals, desc) do |status|
-          options['health'] = status.to_sym if status
-          options['return'] = :health
-        end
       end
     end
   end

data/lib/sunshine.rb

@@ -4,7 +4,6 @@ require 'rainbow'
 require 'highline'
 require 'json'
 
-require 'yaml'
 require 'erb'
 require 'logger'
 require 'optparse'
@@ -12,6 +11,7 @@ require 'time'
 require 'fileutils'
 require 'tmpdir'
 require 'irb'
+require 'yaml'
 
 
 # Turn off EOF tracking to be able to prompt on deploy exceptions.
@@ -25,7 +25,7 @@ module Sunshine
 
   ##
   # Sunshine version.
-  VERSION = '1.2.2'
+  VERSION = '1.2.3'
 
   ##
   # Path to the list of installed sunshine apps.
@@ -42,14 +42,15 @@ module Sunshine
   ##
   # Default configuration.
   DEFAULT_CONFIG = {
-    'interactive'         => true,
     'auto_dependencies'   => true,
     'deploy_env'          => :development,
     'exception_behavior'  => :revert,
     'exclude_paths'       => [],
+    'interactive'         => true,
     'level'               => 'info',
     'max_deploy_versions' => 5,
     'remote_checkouts'    => false,
+    'threads_enabled'     => true,
     'timeout'             => 300,
     'sigint_behavior'     => :revert,
     'web_directory'       => '/srv/http'
@@ -217,6 +218,15 @@ module Sunshine
   end
 
 
+  ##
+  # Check if App objects should use threads when iterating over ServerApps.
+  # Defaults to true, overridden with the 'threads_enabled' config.
+
+  def self.use_threads?
+    @config['threads_enabled']
+  end
+
+
   ##
   # The default directory where apps should be deployed to:
   # '/var/www' by default. Overridden in the config.
@@ -259,15 +269,7 @@ module Sunshine
   # config file and exits if not present.
 
   def self.load_user_config
-    unless File.file? USER_CONFIG_FILE
-      File.open(USER_CONFIG_FILE, "w+"){|f| f.write DEFAULT_CONFIG.to_yaml}
-
-      msg = "Missing config file was created for you: #{USER_CONFIG_FILE}\n\n"
-      msg << DEFAULT_CONFIG.to_yaml
-
-      self.exit 1, msg
-    end
-
+    create_default_config!
     load_config_file USER_CONFIG_FILE
 
     @config['deploy_env'] =
@@ -280,6 +282,16 @@ module Sunshine
     @config
   end
 
+  def self.create_default_config!
+    unless File.file? USER_CONFIG_FILE
+      File.open(USER_CONFIG_FILE, "w+"){|f| f.write DEFAULT_CONFIG.to_yaml}
+
+      msg = "Missing config file was created for you: #{USER_CONFIG_FILE}\n\n"
+      msg << DEFAULT_CONFIG.to_yaml
+
+      self.exit 1, msg
+    end
+  end
 
   ##
   # Loads an array of libraries or gems.
@@ -423,8 +435,6 @@ module Sunshine
 
   require 'sunshine/crontab'
 
-  require 'sunshine/healthcheck'
-
   require 'commands/default'
   require 'commands/list'
   require 'commands/add'

data/lib/sunshine/app.rb

@@ -3,19 +3,34 @@ module Sunshine
   ##
   # App objects are the core of Sunshine deployment. The Sunshine paradygm
   # is to construct an app object, and run custom deploy code by passing
-  # a block to its deploy method:
+  # a block to its deploy method. The following is the simplest way to
+  # instantiate an app:
+  #
+  #   app = Sunshine::App.new :remote_shells => "deploy_server.com"
+  #
+  # By default, Sunshine will look in the pwd for scm information and will
+  # extract the app's name. The default root deploy path is specified by
+  # Sunshine.web_directory, in this case: "/srv/http/app_name".
+  #
+  # More complex setups may look like the following:
   #
   #   someserver = Sunshine::RemoteShell.new "user@someserver.com",
   #                                          :roles => [:web, :app]
   #
-  #   options = {
-  #     :name => 'myapp',
-  #     :repo => {:type => :svn, :url => 'svn://blah...'},
-  #     :root_path => '/usr/local/myapp',
-  #     :remote_shells => 'user@someserver.com'
-  #   }
+  #   myapprepo = Sunshine::SvnRepo.new "svn://my_repo/myapp/tags/release"
   #
-  #   app = Sunshine::App.new(options)
+  #   app = Sunshine::App.new :name          => 'myapp',
+  #                           :repo          => myapprepo,
+  #                           :root_path     => '/usr/local/myapp',
+  #                           :remote_shells => someserver
+  #
+  # Note: The instantiation options :repo and :remote_shells support
+  # the same data format that their respective initialize methods support.
+  # The :remote_shells option also supports arrays of remote shell instance
+  # arguments.
+  #
+  # Once an App is instantiated it can be manipulated in a variety of ways,
+  # including deploying it:
   #
   #   app.deploy do |app|
   #
@@ -26,36 +41,18 @@ module Sunshine
   #     web_server.setup
   #   end
   #
-  # Multiple apps can be defined, and deployed from a single deploy script.
-  # The constructor also supports passing a yaml file path:
-  #
-  #   Sunshine::App.new("path/to/config.yml")
-  #
-  # Deployment can be expressed more concisely by calling App::deploy:
-  #
-  #   App.deploy("path/to/config.yml") do |app|
-  #     Sunshine::Rainbows.new(app).setup
-  #   end
-  #
-  #
-  # An App holds information about where to deploy an application to and
-  # how to deploy it, as well as many convenience methods to setup and
-  # manipulate the deployment process. Most of these methods support passing
-  # remote shell find options:
+  # The constructor also supports reading multi-env configs fom a yaml file,
+  # which can also be the deploy script's DATA, to allow for concise,
+  # encapsulated deploy files:
   #
-  #   app.rake 'db:migrate', :role => :db
-  #   app.deploy :host => 'server1.com'
+  #   # Load from an explicit yaml file:
+  #   Sunshine::App.new "path/to/config.yml"
   #
-  # See App#find for more information.
-  #
-  # App instantiation can be done in several ways:
-  #  App.new instantiation_hash
-  #  App.new "path/to/config.yml", optional_extra_hash
-  #  App.new #=> will attempt to load ruby's file DATA as yaml
+  #   # Load from the yaml in the script file's DATA:
+  #   Sunshine::App.new
   #
   # Yaml files must define settings on a per-environment basis. The default
-  # environment will be used if the deploy_env is not found in the config.
-  # Let's consider the following config:
+  # environment will be used as a base for all other environments:
   #
   #   #config.yml:
   #   ---
@@ -65,78 +62,23 @@ module Sunshine
   #       :url:  http://subversion/repo/tags/release-001
   #     :remote_shells: dev.myserver.com
   #
-  #   :qa:
+  #   qa:
   #     :remote_shells:
   #       - qa1.myserver.com
   #       - qa2.myserver.com
   #
-  #   :qa_special:
-  #     :inherits: :qa
+  #   qa_special:
+  #     :inherits: qa
   #     :root_path: /path/to/application
+  #     :deploy_env: qa
   #
-  # By default, environment definitions inherit the :default environment. In
-  # this instance, :qa_special also inherits from :qa.
-  # With the given config, I could setup the App instance as so:
-  #
-  #   App.new "config.yml", :deploy_env => :development
-  #   # Note: by default, App will get the deploy_env value
-  #   # from Sunshine.deploy_env
-  #
-  # The above will simply load the default config. The following, however,
-  # will load the :qa_special config which inherits from
-  # both :qa and :default:
-  #
-  #   App.new "config.yml", :deploy_env => :qa_special
-  #
-  #
-  # Another way of instantiating an App is to pass it a hash. Unlike the yaml
-  # config file, the hash is not on a per-environment basis and isexpected
-  # to already have the correct values for the given environment.
-  # The following is equivalent to loading the above :default environment:
-  #
-  #   App.new :remote_shells => "dev.myserver.com",
-  #           :repo => {
-  #             :type => :svn,
-  #             :url => "http://subversion/repo/tags/release-001"
-  #           }
-  #
-  # In theory, the minimum amount of information required to instantiate
-  # an app is the repo and remote_shells. If the repo option is omitted,
-  # the App will attempt to detect if the pwd is a checkout out repo and
-  # use that information. If you would like to deploy an application that
-  # is not under source countrol, you may do so by using Sunshine::RsyncRepo,
-  # or passing :rsync in your hash as your repo type.
-  #
-  #
-  # Options supported by App.new are the following:
-  #
-  # :deploy_env:: String - specify the env to deploy with; defaults to
-  # Sunshine#deploy_env.
-  #
-  # :deploy_name:: String - if you want to specify a name for your deploy and
-  # checkout directory (affects the checkout_path); defaults to Time.now.to_i.
-  #
-  # :remote_shells:: String|Array|Sunshine::Shell - the shell(s) to use for
-  # deployment. Accepts any single instance or array of a Sunshine::Shell
-  # type instance or Sunshine::Shell instantiator-friendly arguments.
-  #
-  # :repo:: Hash|Sunshine::Repo - the scm and repo to use for deployment.
-  # Accepts any hash that can be passed to Sunshine::Repo::new_of_type
-  # or any Sunshine::Repo object.
-  #
-  # :root_path:: String - the absolute path the deployed application
-  # should live in; defaults to "#{Sunshine.web_directory}/#{@name}".
-  #
-  # :shell_env:: Hash - environment variables to add to deploy shells.
-  #
-  # :sudo:: true|false|nil|String - which sudo value should be assigned to
-  # deploy shells; defaults to Sunshine#sudo. For more information on using
-  # sudo, see the Using Permissions section in README.txt.
+  # By default, App will get the deploy_env value from Sunshine.deploy_env, but
+  # it may also be passed in explicitely as an option.
 
   class App
 
     ##
-    # Initialize and deploy an application.
+    # Initialize and deploy an application in a single step.
     # Takes any arguments supported by the constructor.
 
     def self.deploy(*args, &block)
@@ -156,6 +98,34 @@ module Sunshine
     #  App.new instantiation_hash
     #  App.new "path/to/config.yml", optional_extra_hash
     #  App.new #=> will attempt to load ruby's file DATA as yaml
+    #
+    # Options supported are:
+    #
+    # :deploy_env:: String - specify the env to deploy with; defaults to
+    # Sunshine#deploy_env.
+    #
+    # :deploy_name:: String - if you want to specify a name for your deploy and
+    # checkout directory (affects the checkout_path); defaults to Time.now.to_i.
+    #
+    # :remote_checkout:: Boolean - when true, will checkout the codebase
+    # directly from the deploy servers; defaults to false.
+    #
+    # :remote_shells:: String|Array|Sunshine::Shell - the shell(s) to use for
+    # deployment. Accepts any single instance or array of a Sunshine::Shell
+    # type instance or Sunshine::Shell instantiator-friendly arguments.
+    #
+    # :repo:: Hash|Sunshine::Repo - the scm and repo to use for deployment.
+    # Accepts any hash that can be passed to Sunshine::Repo::new_of_type
+    # or any Sunshine::Repo object.
+    #
+    # :root_path:: String - the absolute path the deployed application
+    # should live in; defaults to "#{Sunshine.web_directory}/#{@name}".
+    #
+    # :shell_env:: Hash - environment variables to add to deploy shells.
+    #
+    # :sudo:: true|false|nil|String - which sudo value should be assigned to
+    # deploy shells; defaults to Sunshine#sudo. For more information on using
+    # sudo, see the Using Permissions section in README.txt.
 
     def initialize config_file=Sunshine::DATA, options={}
       options, config_file = config_file, Sunshine::DATA if Hash === config_file
@@ -199,8 +169,10 @@ module Sunshine
 
 
     ##
-    # Call a command on specified server apps.
-    # Supports any App#find and Shell#call options.
+    # Call a command on specified server apps. Returns an array of responses.
+    # Supports any App#find and Shell#call options:
+    #   app.call "ls -1", :sudo => true, :host => "web.app.com"
+    #   #=> [".\n..\ndir1", ".\n..\ndir1", ".\n..\ndir2"]
 
     def call cmd, options=nil, &block
       with_server_apps options, :msg => "Running #{cmd}" do |server_app|
@@ -210,7 +182,8 @@ module Sunshine
 
 
     ##
-    # Connect server apps. Supports any App#find options.
+    # Start a persistant connection to app servers.
+    # Supports any App#find options.
 
     def connect options=nil
       Sunshine.logger.info :app, "Connecting..." do
@@ -248,7 +221,7 @@ module Sunshine
 
 
     ##
-    # Disconnect server apps. Supports any App#find options.
+    # Disconnect from app servers. Supports any App#find options.
 
     def disconnect options=nil
       Sunshine.logger.info :app, "Disconnecting..." do
@@ -264,17 +237,19 @@ module Sunshine
     # call user's post-deploy code. Supports any App#find options.
     #
     # If the deploy fails or an exception is raised, it will attempt to
-    # run the Sunshine.failed_deploy_behavior, which is set to :revert by
+    # run the Sunshine.exception_behavior, which is set to :revert by
     # default. However, this is not true of ssh connection failures.
     #
     # If the deploy is interrupted by a SIGINT, it will attempt to run
     # the Sunshine.sigint_behavior, which is set to :revert by default.
     #
-    # Note: The deploy method will stop the former deploy just before
+    # The deploy method will stop the former deploy just before
     # symlink and the passed block is run.
     #
-    # Note: Once deployment is complete, the deploy method will attempt to
-    # run App#start.
+    # Once deployment is complete, the deploy method will attempt to
+    # run App#start! which will run any start script checked into
+    # App#scripts_path, or the start script that will have been generated
+    # by using Sunshine server setups.
 
     def deploy options=nil
 
@@ -302,8 +277,6 @@ module Sunshine
 
           run_post_user_lambdas
 
-          health :enable
-
           build_control_scripts
           build_deploy_info_file
           build_crontab
@@ -325,9 +298,10 @@ module Sunshine
 
 
     ##
-    # Handles SIGINTs and exceptions according to rules set by
-    # Sunshine.sigint_behavior and Sunshine.exception_behavior
-    # or with the override hooks App#on_sigint and App#on_exception.
+    # Runs the given block while handling SIGINTs and exceptions
+    # according to rules set by Sunshine.sigint_behavior and
+    # Sunshine.exception_behavior or with the override hooks
+    # App#on_sigint and App#on_exception.
 
     def interruptable options={}
       interrupt_trap =
@@ -446,8 +420,9 @@ module Sunshine
     ##
     # Symlink current directory to previous checkout and remove
     # the current deploy directory. Supports any App#find options.
+    #   app.revert! :role => :web
 
-    def revert!(options=nil)
+    def revert! options=nil
       with_server_apps options,
         :msg  => "Reverting to previous deploy.",
         :send => :revert!
@@ -455,7 +430,7 @@ module Sunshine
 
 
     ##
-    # Add paths the the shell $PATH env.
+    # Add paths the the shell $PATH env on all app shells.
 
     def add_shell_paths(*paths)
       path = @shell_env["PATH"] || "$PATH"
@@ -596,12 +571,14 @@ module Sunshine
     # Checks out the app's codebase to one or all deploy servers.
     # Supports all App#find options, plus:
     # :copy:: Bool - Checkout locally and rsync; defaults to false.
+    # :exclude:: String|Array - Exclude the specified paths during
+    # a deploy via copy.
 
     def checkout_codebase options=nil
       copy_option = options[:copy]          if options
-      exclude     = options.delete(:exclude) if options
+      exclude     = options.delete :exclude if options
 
-      if @remote_checkout && !copy_option
+      if RsyncRepo === @repo || (@remote_checkout && !copy_option)
         with_server_apps options,
           :msg  => "Checking out codebase (remotely)",
           :send => [:checkout_repo, @repo]
@@ -638,7 +615,8 @@ module Sunshine
 
 
     ##
-    # Check if app has been deployed successfully.
+    # Check if app has been deployed successfully by checking the name of the
+    # deploy on every app server with the instance's deploy name.
 
     def deployed? options=nil
       with_server_apps options,
@@ -651,10 +629,11 @@ module Sunshine
 
 
     ##
-    # Iterate over each server app.
+    # Iterate over each server app. Supports all App#find options.
+    # See Sunshine::ServerApp for more information.
 
-    def each(options=nil, &block)
-      server_apps = find(options)
+    def each options=nil, &block
+      server_apps = find options
       server_apps.each(&block)
     end
 
@@ -686,61 +665,6 @@ module Sunshine
     end
 
 
-    ##
-    # Decrypt a file using gpg. Allows all DeployServerDispatcher#find
-    # options, plus:
-    # :output:: str - the path the output file should go to
-    # :passphrase:: str - the passphrase gpg should use
-
-    def gpg_decrypt gpg_file, options={}
-      options[:passphrase] ||=
-        Sunshine.shell.ask("Enter gpg passphrase:") do |q|
-        q.echo = false
-      end
-
-      with_server_apps options,
-        :msg  => "Gpg decrypt: #{gpg_file}",
-        :send => [:gpg_decrypt, gpg_file, options]
-    end
-
-
-    ##
-    # Gets or sets the healthcheck state. Returns a hash of host/state
-    # pairs. State values are :enabled, :disabled, and :down. The method
-    # argument can be omitted or take a value of :enable, :disable, or :remove:
-    #   app.health
-    #   #=> Returns the health status for all server_apps
-    #
-    #   app.health :role => :web
-    #   #=> Returns the status of all server_apps of role :web
-    #
-    #   app.health :enable
-    #   #=> Enables all health checking and returns the status
-    #
-    #   app.health :disable, :role => :web
-    #   #=> Disables health checking for :web server_apps and returns the status
-
-    def health method=nil, options=nil
-      valid_methods = [:enable, :disable, :remove]
-      options = method if options.nil? && Hash === method
-
-      valid_method = valid_methods.include? method
-
-      message   = "#{method.to_s.capitalize[0..-2]}ing" if valid_method
-      message ||= "Getting status of"
-      message   = "#{message} healthcheck"
-
-      statuses = {}
-      with_server_apps options, :msg => message do |server_app|
-        server_app.health.send method if valid_method
-
-        statuses[server_app.shell.host] = server_app.health.status
-      end
-
-      statuses
-    end
-
-
     ##
     # Install dependencies defined as a Sunshine dependency object:
     #   rake   = Sunshine.dependencies.gem 'rake', :version => '~>0.8'
@@ -768,6 +692,7 @@ module Sunshine
 
     ##
     # Creates the required application directories.
+    # Supports all App#find options.
 
     def make_app_directories options=nil
       with_server_apps options,
@@ -778,10 +703,11 @@ module Sunshine
 
     ##
     # Assign the prefered package manager to all server_apps:
-    #   app.prefer_pkg_manager Settler::Yum
+    #   app.prefer_pkg_manager Sunshine::Yum
     #
     # Package managers are typically detected automatically by each
     # individual server_apps.
+    # Supports all App#find options.
 
     def prefer_pkg_manager pkg_manager, options=nil
       with_server_apps options,
@@ -791,6 +717,7 @@ module Sunshine
 
     ##
     # Run a rake task on any or all deploy servers.
+    # Supports all App#find options.
 
     def rake command, options=nil
       with_server_apps options,
@@ -801,6 +728,7 @@ module Sunshine
 
     ##
     # Adds the app to the deploy servers deployed-apps list.
+    # Supports all App#find options.
 
     def register_as_deployed options=nil
       with_server_apps options,
@@ -814,6 +742,7 @@ module Sunshine
     #   remove_cronjob "reboot", :role => :web
     #   remove_cronjob :all
     #   #=> deletes all cronjobs related to this app
+    # Supports all App#find options.
 
     def remove_cronjob name, options=nil
       with_server_apps options,
@@ -830,6 +759,7 @@ module Sunshine
     ##
     # Removes old deploys from the checkout_dir
     # based on Sunshine's max_deploy_versions.
+    # Supports all App#find options.
 
     def remove_old_deploys options=nil
       with_server_apps options,
@@ -841,7 +771,7 @@ module Sunshine
     ##
     # Run the restart script of a deployed app on the specified
     # deploy servers.
-    # Post-deploy only.
+    # Post-deploy only. Supports all App#find options.
 
     def restart options=nil
       with_server_apps options,
@@ -853,7 +783,7 @@ module Sunshine
     ##
     # Run the restart script of a deployed app on the specified
     # deploy servers. Raises an exception on failure.
-    # Post-deploy only.
+    # Post-deploy only. Supports all App#find options.
 
     def restart! options=nil
       with_server_apps options,
@@ -863,7 +793,7 @@ module Sunshine
 
 
     ##
-    # Runs bundler on deploy servers.
+    # Runs bundler on deploy servers. Supports all App#find options.
 
     def run_bundler options=nil
       with_server_apps options,
@@ -873,7 +803,7 @@ module Sunshine
 
 
     ##
-    # Runs GemInstaller on deploy servers.
+    # Runs GemInstaller on deploy servers. Supports all App#find options.
 
     def run_geminstaller options=nil
       with_server_apps options,
@@ -896,7 +826,7 @@ module Sunshine
     ##
     # Run the given script of a deployed app on the specified
     # deploy servers.
-    # Post-deploy only.
+    # Post-deploy only. Supports all App#find options.
 
     def run_script name, options=nil
       with_server_apps options,
@@ -908,7 +838,7 @@ module Sunshine
     ##
     # Run the given script of a deployed app on the specified
     # deploy servers. Raises an exception on failure.
-    # Post-deploy only.
+    # Post-deploy only. Supports all App#find options.
 
     def run_script! name, options=nil
       with_server_apps options,
@@ -919,6 +849,7 @@ module Sunshine
 
     ##
     # Run a sass task on any or all deploy servers.
+    # Supports all App#find options.
 
     def sass *sass_names
       options = sass_names.delete_at(-1) if Hash === sass_names.last
@@ -932,13 +863,14 @@ module Sunshine
     ##
     # Set and return the remote shell env variables.
     # Also assigns shell environment to the app's deploy servers.
+    # Supports all App#find options.
 
-    def shell_env env_hash=nil
+    def shell_env env_hash=nil, options=nil
       env_hash ||= {}
 
       @shell_env.merge!(env_hash)
 
-      with_server_apps :all,
+      with_server_apps options,
         :no_threads => true,
         :no_session => true,
         :msg => "Shell env: #{@shell_env.inspect}" do |server_app|
@@ -952,7 +884,7 @@ module Sunshine
     ##
     # Run the start script of a deployed app on the specified
     # deploy servers.
-    # Post-deploy only.
+    # Post-deploy only. Supports all App#find options.
 
     def start options=nil
       with_server_apps options,
@@ -964,7 +896,7 @@ module Sunshine
     ##
     # Run the start script of a deployed app on the specified
     # deploy servers. Raises an exception on failure.
-    # Post-deploy only.
+    # Post-deploy only. Supports all App#find options.
 
     def start! options=nil
       with_server_apps options,
@@ -975,7 +907,7 @@ module Sunshine
 
     ##
     # Get a hash of which deploy server apps are :running or :down.
-    # Post-deploy only.
+    # Post-deploy only. Supports all App#find options.
 
     def status options=nil
       statuses = {}
@@ -991,7 +923,7 @@ module Sunshine
     ##
     # Run the stop script of a deployed app on the specified
     # deploy servers.
-    # Post-deploy only.
+    # Post-deploy only. Supports all App#find options.
 
     def stop options=nil
       with_server_apps options,
@@ -1003,7 +935,7 @@ module Sunshine
     ##
     # Run the stop script of a deployed app on the specified
     # deploy servers. Raises an exception on failure.
-    # Post-deploy only.
+    # Post-deploy only. Supports all App#find options.
 
     def stop! options=nil
       with_server_apps options,
@@ -1013,7 +945,7 @@ module Sunshine
 
 
     ##
-    # Use sudo on deploy servers. Set to true/false, or
+    # Use sudo on all the app's deploy servers. Set to true/false, or
     # a username to use 'sudo -u'.
 
     def sudo=(value)
@@ -1030,6 +962,7 @@ module Sunshine
 
     ##
     # Creates a symlink to the app's checkout path.
+    # Supports all App#find options.
 
     def symlink_current_dir options=nil
       with_server_apps options,
@@ -1041,8 +974,12 @@ module Sunshine
     ##
     # Iterate over all deploy servers but create a thread for each
     # deploy server. Means you can't return from the passed block!
+    # Calls App#each if Sunshine.use_threads? is false.
+    # Supports all App#find options.
+
+    def threaded_each options=nil, &block
+      return each options, &block unless Sunshine.use_threads?
 
-    def threaded_each(options=nil, &block)
       mutex   = Mutex.new
       threads = []
       error   = nil
@@ -1072,34 +1009,13 @@ module Sunshine
     end
 
 
-    ##
-    # Upload common rake tasks from the sunshine lib.
-    #   app.upload_tasks
-    #     #=> upload all tasks
-    #   app.upload_tasks 'app', 'common', :role => :web
-    #     #=> upload app and common rake files
-    #
-    # Allows standard DeployServerDispatcher#find options, plus:
-    # :remote_path:: str - the remote absolute path to upload the files to
-
-    def upload_tasks *files
-      options = Hash === files.last ? files.last.dup : {}
-
-      options.delete(:remote_path)
-      options = :all if options.empty?
-
-      with_server_apps options,
-        :msg  => "Uploading tasks: #{files.join(" ")}",
-        :send => [:upload_tasks, *files]
-    end
-
-
     ##
     # Execute a block with a specified server app filter:
     #   app.with_filter :role => :cdn do |app|
     #     app.sass 'file1', 'file2', 'file3'
     #     app.rake 'asset:packager:build_all'
     #   end
+    # Supports all App#find options.
 
     def with_filter filter_hash
       old_server_apps, @server_apps = @server_apps, find(filter_hash)
@@ -1200,7 +1116,7 @@ module Sunshine
       @shared_path   = "#{@root_path}/shared"
       @log_path      = "#{@shared_path}/log"
       @checkout_path = "#{@deploys_path}/#{@deploy_name}"
-      @scripts_path  = "#{@checkout_path}/sunshine_scripts"
+      @scripts_path  = "#{@current_path}/script"
     end