capistrano 1.1.0 → 1.2.0

data/CHANGELOG

@@ -0,0 +1,241 @@
+*SVN*
+
+* Add experimental 'shell' task [Jamis Buck]
+
+* Display file for external configurations, rather than inspected proc. [Jamis Buck]
+
+* Connect to multiple servers in parallel, rather than serially. [Jamis Buck]
+
+* Add SCM module for Mercurial (closes #4150) [Matthew Elder]
+
+* Remove unused line in SCM::Base (closes #5619) [chris@seagul.co.uk]
+
+* More efficient "svn log" usage (closes #5620) [Anatol Pomozov]
+
+* Better support for key passphrases in the SVN module (closes #5920) [llasram@gmail.com]
+
+* Fix missing default for :local in cvs.rb (closes #3645) [jeremy@hinegardner.org]
+
+* Fix awkward spacing in gemspec file (closes #3888) [grant@antiflux.org]
+
+* Add support for :sudo variable to specify path to sudo (closes #4578) [timothee.peignier@tryphon.org]
+
+* Make previous_release return nil if there are no previous releases (closes #4959) [bdabney@cavoksolutions.com]
+
+* Uncache releases list after update_code is called so that newly released dir is included (closes #3766) [Jamis Buck]
+
+* Allow the subversion scm to accept HTTPS certificates (closes #4792) [Jamis Buck]
+
+* Make sure rollbacks occur within the scope of the task that triggered them [Jamis Buck]
+
+* Fixed the default recipe to work with setups that haven't yet gone pids [DHH]
+
+* Symlink and setup for shared/pids to tmp/pids [DHH]
+
+* Fix some incorrect usage text (closes #4507) [gerry_shaw@yahoo.com]
+
+* Added Actor#stream method that makes it easy to create cross-server streams [DHH]. Example:
+
+    desc "Run a tail on multiple log files at the same time"
+    task :tail_fcgi, :roles => :app do
+      stream "tail -f #{shared_path}/log/fastcgi.crash.log"
+    end
+
+* Make update_code and symlink a macro task under the name "update" for easy of deploy to servers that does not run fcgis [DHH]
+
+* Changed setup, update_code, rollback_code, and symlink to work on all servers instead of only those in the :app, :web, and :db roles. A server can opt out of being part of the release deployment by setting :no_release => true [DHH]
+
+* Added support for :except on task declarations as the opposite of :only [DHH]. Example:
+
+    role :app, "192.168.0.2"
+    role :file, "192.168.0.3", :no_release => true
+
+    task :symlink, :except => { :no_release => true } do
+      on_rollback { run "ln -nfs #{previous_release} #{current_path}" }
+      run "ln -nfs #{current_release} #{current_path}"
+    end
+    
+    cap symlink # will not run on 192.168.0.3
+
+* Deprecate the -r/--recipe switch in favor of -f/--file (for more make/rake-like semantics) [Jamis Buck]
+
+* Fix gemspec to include a dependency on rake 0.7 [Jamis Buck]
+
+* Added respect for ENV["HOSTS"] that'll be used instead of the roles specified in the task definition [DHH]. Example:
+
+    HOSTS=192.168.0.1 cap setup # one-off setup for that server, doesn't need to be prespecified in the recipes file
+
+* Added respect for ENV["ROLES"] that'll be used instead of the roles specified in the task definition [DHH]. Example:
+
+    task :setup, :roles => [ :app, :web, :db ]
+      # normally this would run every where
+    end
+    
+    ROLES=app cap setup # this will only run for the app role, overwritting the default declaration
+
+* Added :hosts option to task definition that allows you to specify cross-cutting tasks [DHH]. Example:
+
+    task :setup, :hosts => [ "06.example.com", "01.example.com" ] do
+      # this task will happen on 06 and 01 regardless of which roles they belong to
+    end
+
+* Fix operator precedence problem in script for touching the revisions.log #3223 [jason.garber@emu.edu]
+
+
+*1.1.0* (March 6th, 2006)
+
+* Simplify the generated capistrano.rake file, and make it easier to customize
+
+* Use rake-like command-line semantics ("cap deploy", in addition to "cap -a deploy")
+
+* Rename to capistrano
+
+* Make the generated capistrano.rake file use rake namespaces, and include all default tasks
+
+* Look for config/deploy.rb, capfile, and Capfile by default
+
+
+*1.0.1* (February 20th, 2006)
+
+* Fix broken switchtower_invoke function in switchtower.rake (missing require statement)
+
+
+*1.0.0* (Feburary 18th, 2006)
+
+* Make CVS module's :local value default to "."
+
+* Add "invoke" task for executing one-off commands
+
+* Make port selection smarter for gateway connections
+
+* Add extension mechanism for custom ST operations and third-party task libraries
+
+* Make ST rails rake tasks more configurable
+
+* Add Actor#current_task and simplify Task#servers
+
+* Add Actor#connect! method for working around lazy connection establishing
+
+* Make sure IO::TRUNC is specified for Net::SFTP uploads (#3510)
+
+* Add branch support to CVS [jeremy@hinegardner.org] (#3596)
+
+* Add bazaar-ng SCM module [Damien Merenne]
+
+* Add optional :svn_username and :svn_password variables
+
+* Allow Proc-valued variables to be set more conveniently (set(:foo) { "bar" })
+
+* Add perforce SCM module [Richard McMahon]
+
+* Add bazaar (v1) SCM module [Edd Dumbill] (#3533)
+
+* Fix stftime format string used in CVS module to be Windows-compatible (fixes #3383)
+
+* Add an better error when a task is run and no servers match the required conditions
+
+* Add default spinner and cold_deploy tasks, and spinner_user variable
+
+* Changed restart_via variable to (boolean) use_sudo
+
+* Only chmod when the revisions.log file is first created
+
+* Make UPPERCASE variables work
+
+* Added rails_env variable (defaults to production) for use by tasks that employ the RAILS_ENV environment variable
+
+* Added Actor.default_io_proc
+
+* Set :actor key on SSH channel instances
+
+
+*0.10.0* (January 2nd, 2006)
+
+* Handle ssh password prompts like "someone's password:"
+
+* Make CLI#echo available as a class method.
+
+* Add CLI#with_echo.
+
+* Make the default password prompt available as a class method.
+
+# Add documentation for the CLI class.
+
+* Add a sanity check to make sure the correct versions of Net::SSH and Net::SFTP are installed.
+
+* Added a cleanup task to remove unused releases from the deployment directory
+
+* Allow password to be reentered on sudo if it was entered incorrectly
+
+* Use && as the command separator for the checkouts, so that errors are caught early.
+
+* Ping each SSH connection every 1s during command processing so that long-running commands don't cause the connection to timeout.
+
+* Add a 0.01s sleep during the command loop so that the CPU doesn't go ballistic while ST is doing its thing.
+
+* Add :restart_via variable for specifying whether restart ought to use :sudo (default, use sudo)
+
+* Use SFTP for file transfers (if available).
+
+* Add an "update_current" task that will do an svn up on the current release
+
+* Use the :checkout variable to determine what operation to use for svn checkouts (instead of co, like "export").
+
+* The Rails rake tasks now load ST directly, instead of invoking it via system
+
+* Added ssh_options variable to configure the SSH connection parameters #2734 [jerrett@bravenet.com]
+
+* Require Net::SSH 1.0.5
+
+
+*0.9.0* (October 18th, 2005)
+
+* Use process reaper instead of custom reap script for restarting
+
+* Use -S switch to set variables before reading recipe files #2242
+
+* Have setup.rb create a switchtower.cmd file on Win32 platforms #2402
+
+* Add diff_from_last_deploy to the rails switchtower rakefile template
+
+* Add diff_from_last_deploy task (currently only works with subversion)
+
+* Add deploy_with_migrations task.
+
+* Make the migrate task more customizable.
+
+* If no password is given with the -p switch, prompt for password immediately.
+
+* Do not install a switchtower stub in the script directory. Assume the switchtower executable is in the path.
+
+* Remove trailing newlines from commands to prevent trailing backslash #2141
+
+* Default parameters work correctly with the generator #2218 [Scott Barron]
+
+* Attempt to require 'rubygems' explicitly when running the switchtower utility #2134
+
+* Make default tasks work only on app/db/web roles, so that additional roles may be created for boxes with specific needs without needing to (for instance) deploy the app to those boxes
+
+* Default the application name to "Application" when using --apply-to
+
+* Show the help screen instead of an error when no arguments are given
+
+* Make SwitchTower easier to invoke programmatically via SwitchTower::CLI
+
+* Specify the revision to release via the :revision variable (defaults to latest revision)
+
+* Allow variables to be set via the cli using the -s switch
+
+* Log checkouts to a "revisions.log" file
+
+* Changed behavior of checkout to use the timestamp as the release name, instead of the revision number
+
+* Added CVS module (very very experimental!)
+
+* Works with public keys now, for passwordless deployment
+
+* Subversion module recognizes the password prompt for HTTP authentication
+
+* Preserve +x on scripts when using darcs #1929 [Scott Barron]
+
+* When executing multiline commands, use a backslash to escape the newline

data/MIT-LICENSE

@@ -0,0 +1,20 @@
+Copyright (c) 2005,2006 Jamis Buck
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README

@@ -0,0 +1,35 @@
+= Capistrano
+
+Capistrano is a utility and framework for executing commands in parallel on multiple remote machines, via SSH. It uses a simple DSL (borrowed in part from Rake, http://rake.rubyforge.org/) that allows you to define _tasks_, which may be applied to machines in certain roles. It also supports tunneling connections via some gateway machine to allow operations to be performed behind VPN's and firewalls.
+
+Capistrano was originally designed to simplify and automate deployment of web applications to distributed environments, and so it comes with many tasks predefined for that ("update_code" and "deploy", for instance).
+
+== Dependencies
+
+Capistrano depends upon the Net::SSH library by Jamis Buck (http://net-ssh.rubyforge.org). Net::SSH itself depends on the Needle library (http://needle.rubyforge.org), also by Jamis Buck.
+
+== Assumptions
+
+In keeping with Rails' "convention over configuration", Capistrano makes several assumptions about how you will use it (most, if not all, of which may be explicitly overridden):
+
+* You are writing web applications and want to use Capistrano to deploy them.
+* You are using Ruby on Rails (http://www.rubyonrails.com) to build your apps.
+* You are using Subversion (http://subversion.tigris.org/) to manage your source code.
+* You are running your apps using FastCGI, together with Rails' spinner/reaper utilities.
+
+As with the rest of Rails, if you can abide by these assumptions, you can use Capistrano "out of the box". If any of these assumptions do not hold, you'll need to make some adjustments to your deployment recipe files.
+
+== Usage
+
+More documentation is always pending, but you'll want to see the user manual for detailed usage instructions. (The manual is online at http://manuals.rubyonrails.org/read/book/17).
+
+In general, you'll use Capistrano as follows:
+
+* Create a deployment recipe ("deploy.rb") for your application. You can use the sample recipe in examples/sample.rb as a starting point.
+* Use the +cap+ script to execute your recipe (see below).
+
+Use the +cap+ script as follows:
+
+    cap -vvv someaction
+
+By default, the script will look for a file called one of <tt>config/deploy</tt>, <tt>config/deploy.rb</tt>, <tt>capistrano</tt>, or <tt>capistrano.rb</tt>. You can the <tt>-v</tt> switch multiple times (as shown) to increase the verbosity of the output. The +someaction+ text indicates which action to execute.

data/THANKS

@@ -0,0 +1,4 @@
+* Bazaar (v1) SCM Module: Edd Dumbill <edd@usefulinc.com>
+* Perforce SCM Module: Richard McMahon <richie.mcmahon@gmail.com>
+* Bazaar-NG SCM Module: Damien Merenne <dam@capsule.org>
+* Mercurial SCM Module: Matthew Elder <mae@mindflowsolutions.com>

data/lib/capistrano/actor.rb

@@ -78,31 +78,65 @@ module Capistrano
 
       # Returns the list of servers (_not_ connections to servers) that are
       # the target of this task.
-      def servers
-        unless @servers
-          roles = [*(@options[:roles] || actor.configuration.roles.keys)].
-            map { |name|
-              actor.configuration.roles[name] or
-                raise ArgumentError, "task #{self.name.inspect} references non-existant role #{name.inspect}"
-            }.flatten
-          only  = @options[:only] || {}
+      def servers(reevaluate=false)
+        @servers = nil if reevaluate
+        @servers ||=
+          if hosts = find_hosts
+            hosts
+          else
+            roles = find_roles
+            apply_only!(roles)
+            apply_except!(roles)
+
+            roles.map { |role| role.host }.uniq
+          end
+      end
+      
+      private
+        def find_roles
+          role_names = [ *(environment_values(:roles, true) || @options[:roles] || actor.configuration.roles.keys) ]
+          role_names.collect do |name|
+            actor.configuration.roles[name] ||
+              raise(ArgumentError, "task #{self.name.inspect} references non-existant role #{name.inspect}")
+          end.flatten
+        end
+        
+        def find_hosts
+          environment_values(:hosts) || @options[:hosts]
+        end
+        
+        def environment_values(key, use_symbols = false)
+          if variable = ENV[key.to_s.upcase]
+            values = variable.split(",")
+            use_symbols ? values.collect { |e| e.to_sym } : values
+          end
+        end
+        
+        def apply_only!(roles)
+          only = @options[:only] || {}
 
           unless only.empty?
             roles = roles.delete_if do |role|
               catch(:done) do
-                only.keys.each do |key|
-                  throw(:done, true) if role.options[key] != only[key]
-                end
+                only.keys.each { |key| throw(:done, true) if role.options[key] != only[key] }
                 false
               end
             end
-          end
-
-          @servers = roles.map { |role| role.host }.uniq
+          end          
         end
+        
+        def apply_except!(roles)
+          except = @options[:except] || {}
 
-        @servers
-      end
+          unless except.empty?
+            roles = roles.delete_if do |role|
+              catch(:done) do
+                except.keys.each { |key| throw(:done, true) if role.options[key] == except[key] }
+                false
+              end
+            end
+          end          
+        end
     end
 
     def initialize(config) #:nodoc:
@@ -177,6 +211,27 @@ module Capistrano
       end
     end
 
+    # Streams the result of the command from all servers that are the target of the
+    # current task. All these streams will be joined into a single one,
+    # so you can, say, watch 10 log files as though they were one. Do note that this
+    # is quite expensive from a bandwidth perspective, so use it with care.
+    #
+    # Example:
+    #
+    #   desc "Run a tail on multiple log files at the same time"
+    #   task :tail_fcgi, :roles => :app do
+    #     stream "tail -f #{shared_path}/log/fastcgi.crash.log"
+    #   end
+    def stream(command)
+      run(command) do |ch, stream, out|
+        puts out if stream == :out
+        if stream == :err
+          puts "[err : #{ch[:host]}] #{out}"
+          break
+        end
+      end
+    end
+
     # Deletes the given file from all servers targetted by the current task.
     # If <tt>:recursive => true</tt> is specified, it may be used to remove
     # directories.
@@ -210,6 +265,12 @@ module Capistrano
     # Like #run, but executes the command via <tt>sudo</tt>. This assumes that
     # the sudo password (if required) is the same as the password for logging
     # in to the server.
+    #
+    # Also, this module accepts a <tt>:sudo</tt> configuration variable,
+    # which (if specified) will be used as the full path to the sudo
+    # executable on the remote machine:
+    #
+    #   set :sudo, "/opt/local/bin/sudo"
     def sudo(command, options={}, &block)
       block ||= default_io_proc
 
@@ -218,7 +279,7 @@ module Capistrano
       # prompts from that host.
       prompt_host = nil
       
-      run "sudo #{command}", options do |ch, stream, out|
+      run "#{sudo_command} #{command}", options do |ch, stream, out|
         if out =~ /^Password:/
           ch.send_data "#{password}\n"
         elsif out =~ /try again/
@@ -293,16 +354,14 @@ module Capistrano
     # Inspects the remote servers to determine the list of all released versions
     # of the software. Releases are sorted with the most recent release last.
     def releases
-      unless @releases
+      @releases ||= begin
         buffer = ""
         run "ls -x1 #{releases_path}", :once => true do |ch, str, out|
           buffer << out if str == :out
           raise "could not determine releases #{out.inspect}" if str == :err
         end
-        @releases = buffer.split.sort
+        buffer.split.sort
       end
-
-      @releases
     end
 
     # Returns the most recent deployed release
@@ -312,7 +371,7 @@ module Capistrano
 
     # Returns the release immediately before the currently deployed one
     def previous_release
-      release_path(releases[-2])
+      release_path(releases[-2]) if releases[-2]
     end
 
     # Invoke a set of tasks in a transaction. If any task fails (raises an
@@ -333,10 +392,16 @@ module Capistrano
           logger.important "transaction: rollback", current ? current.name : "transaction start"
           task_call_history.reverse.each do |task|
             begin
+              # throw the task back on the stack so that roles are properly
+              # interpreted in the scope of the task in question.
+              push_task_call_frame(task.name)
+
               logger.debug "rolling back", task.name
               task.rollback.call if task.rollback
             rescue Object => e
               logger.info "exception while rolling back: #{e.class}, #{e.message}", task.name
+            ensure
+              pop_task_call_frame
             end
           end
           raise
@@ -376,6 +441,10 @@ module Capistrano
     end
 
     private
+    
+      def sudo_command
+        configuration[:sudo] || "sudo"
+      end
 
       def define_method(name, &block)
         metaclass.send(:define_method, name, &block)
@@ -393,9 +462,27 @@ module Capistrano
 
       def establish_connections(servers)
         @factory = establish_gateway if needs_gateway?
-        servers.each do |server|
-          @sessions[server] ||= @factory.connect_to(server)
+        servers = Array(servers)
+
+        # because Net::SSH uses lazy loading for things, we need to make sure
+        # that at least one connection has been made successfully, to kind of
+        # "prime the pump", before we go gung-ho and do mass connection in
+        # parallel. Otherwise, the threads start doing things in wierd orders
+        # and causing Net::SSH to die of confusion.
+
+        if !@established_gateway && @sessions.empty?
+          server, servers = servers.first, servers[1..-1]
+          @sessions[server] = @factory.connect_to(server)
         end
+
+        servers.map { |server| establish_connection_to(server) }.each { |t| t.join }
+      end
+
+      # We establish the connection by creating a thread in a new method--this
+      # prevents problems with the thread's scope seeing the wrong 'server'
+      # variable if the thread just happens to take too long to start up.
+      def establish_connection_to(server)
+        Thread.new { @sessions[server] ||= @factory.connect_to(server) }
       end
 
       def establish_gateway