capistrano 1.4.2 → 2.0.0

data/CHANGELOG

@@ -1,13 +1,149 @@
-*unreleased*
+*2.0.0* July 21, 2007
 
-* Add an explicit dependency on Net::SSH and Net::SFTP versions less than 1.99.0 so that cap1 can coexist with net-ssh v2 [Jamis Buck]
+* Make the "no matching servers" error more sane [halorgium]
 
-* Don't send no-auth-cache if no auth credentials are given [Jonathan Younger]
+* Make sure the invoke task gives a sane error when the COMMAND value is omitted [halorgium]
+
+* Make sure variables are conditionally set in the deploy recipes, so as not to clobber values set elsewhere [Jamis Buck]
+
+* Fix "input stream is empty" errors from HighLine on prompt [Jamis Buck]
+
+* Added "synchronous_connect" setting to try and work around SFTP hangs for certain users [Jamis Buck]
+
+* Auto-require the SSH shell service, to avoid race conditions [Jamis Buck]
+
+* Add a millisecond sleep in upload to reduce CPU impact [Jamis Buck]
+
+* Allow the logger to be set via Configuration#logger= [Jamis Buck]
+
+* Allow $CAPISTRANO:HOST$ to be used in filenames to the put command [Jamis Buck]
+
+* Allow execute_on_servers to be called without a current task again [Jamis Buck]
+
+* Put $stdout in sync mode, so that Net::SSH prompts are displayed [Jamis Buck]
+
+* Make sure deploy:check aborts if it fails [Jamis Buck]
+
+* Spelling corrections in docs [Tim Carey-Smith, Giles Bowkett]
+
+
+*1.99.3 (2.0 Preview 4)* June 28, 2007
+
+* Don't break task descriptions on a period that appears in the middle of a sentence [Jamis Buck]
+
+* Added support for :on_error => :continue in task definitions, allowing tasks to effectively ignore connection and execution errors that occur as they run [Rob Holland]
+
+* Use correct parameters for Logger constructor in the SCM and Strategy base initializers [Jamis Buck]
+
+* Set LC_ALL=C before querying the revision, to make sure the output is in a predictable locale and can be parsed predictably [via Leandro Nunes dos Santos]
+
+* Add :copy_remote_dir variable for the :copy strategy, to indicate where the archive should be copied to on the remote servers [Jamis Buck]
+
+* Make the awk use in the dependencies code work with POSIX awk [mcornick]
+
+* Make variable accesses thread safe [via Adrian Danieli]
+
+* Make user input for yes/no prompts work correctly in the Mercurial module [Matthew Elder]
+
+* Use single quotes to escape semicolon in find command, instead of a backslash [via michael.italia@gmail.com]
+
+* Better quoting of reserved characters in commands [Jamis Buck]
+
+* Make sure Net::SSH versions prior to 1.1.0 still work [Jamis Buck]
+
+* Allow the :hosts and :roles keys to accept lambdas, which will be evaluated lazily to allow runtime selection of hosts and roles in tasks [Jamis Buck]
+
+* Use `which' to test whether a command exists in the remote path, instead of `test -p' [Jamis Buck]
+
+* Make sure the connection factory is established synchronously, to avoid multiple gateway instances being spawned [Jamis Buck]
+
+* Make sure symlink and finalize_update tasks reference the most recent release when called by themselves [Jamis Buck]
+
+
+*1.99.2 (2.0 Preview 3)* June 15, 2007
+ 
+* CVS SCM module [Brian Phillips]
+
+* Fix typo in Perforce SCM module [Chris Bailey]
+
+* ssh_options < server options when connecting [Jamis Buck]
+
+* Logger defaults to $stderr instead of STDERR [lhartley]
+
+* Use cp -RPp instead of -a in the remote cache strategy
+
+* Make the UploadError exception include an array of the hosts that failed [rob@inversepath.com]
+
+* Allow "empty" roles to be declared [Jamis Buck]
+
+* Mercurial SCM module [Tobias Luetke, Matthew Elder]
+
+* Invoke all commands via sh (customizable via :default_shell) [Jamis Buck]
+
+* Make sure all directories exist on each deploy which are necessary for subsequent commands to succeed, since some SCM's won't save empty directories [Matthew Elder]
+
+* Add :default_environment variable, which is applied to every command
+
+
+*1.99.1 (2.0 Preview 2)* May 10, 2007
+
+* Fix some documentation typos [eventualbuddha]
+
+* Don't retry failed connections if an explicit auth_methods list is given [Chris Farms]
+
+* Added support for load and exit callbacks, which get invoked when all recipes have been loaded and when all requested tasks have been executed [Jamis Buck]
+
+* Added support for start and finish callbacks, which get invoked when any task is called via the command-line [Jamis Buck]
+
+* Make `capify' understand simple command-line switches [Jamis Buck]
+
+* Make the server definition itself available to SSH channels, rather than just the host name [Jamis Buck]
+
+* Identify servers by their complete credentials in logs, rather than simply by hostname [Jamis Buck]
+
+* Uniquely identify servers based on hostname, port, and username, instead of merely on hostname [Jamis Buck]
+
+* Allow (e.g.) scm_command and local_scm_command to be set in the event of different paths to the scm command on local vs. remote hosts. [Jamis Buck]
+
+* Kill the "deploy:app" namespace and move those tasks into deploy, directly. [Jamis Buck]
+
+* Make sure 'desc' applies to the next defined task, in any namespace. [Jamis Buck]
+
+* Fix shell so that servers for a task are correctly discovered. [Jamis Buck]
+
+* Added before(), after(), and on() callback creation methods. [Jamis Buck]
+
+* Fix broken check! method for some deployment strategies. [Jamis Buck]
+
+* deploy:cold should also run migrations before starting the app [Jamis Buck]
+
+* Make the copy strategy check out to a temporary directory [Jamis Buck]
+
+
+*1.99.0 (2.0 Preview 1)* April 24, 2007
+
+* Add `capify' script to make it easier to prepare a project for deployment using cap [Jamis Buck]
+
+* Make sure the sudo helper understands the SuSE dialect of the sudo password prompt [Steven Wisener]
+
+* Fix synchronization issue with Gateway initialization [Doug Barth]
+
+* Added opt-in "compat" and "upgrade" recipes for tasks to aid in the upgrade process to Capistrano 2 [Jamis Buck]
+
+* The deployment recipes are now opt-in. Just do 'load "deploy"' in your recipe script. [Jamis Buck]
+
+* Added $CAPISTRANO:HOST$ placeholder in commands, which will be replaced with the name of the host on which the command is executing [Jamis Buck]
+
+* Added -e switch to explain specific task. Added -X to extend -x. Made -h much briefer. Added -T to list known tasks. [Jamis Buck]
+
+* Added namespaces for tasks [Jamis Buck]
+
+* Merged the Configuration and Actor classes, performed various other massive refactorings of the code [Jamis Buck]
 
 
 *1.4.1* (February 24, 2007)
 
-* Use the no-auth-cache option with subversion so that username/password tokens do not get cached by capistrano usage [Jonathan Younger]
+* Use the no-auth-cache option with subversion so that username/password tokens do not get cached by capistrano usage [jonathan]
 
 * Deprecated upper-cased variables [Jamis Buck]
 

data/MIT-LICENSE

@@ -1,4 +1,4 @@
-Copyright (c) 2005,2006 Jamis Buck
+Copyright (c) 2005-2007 Jamis Buck <jamis@37signals.com>
 
 Permission is hereby granted, free of charge, to any person obtaining
 a copy of this software and associated documentation files (the

data/README

@@ -2,34 +2,42 @@
 
 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).
+Capistrano was originally designed to simplify and automate deployment of web applications to distributed environments, and originally came bundled with a set of tasks designed for deploying Rails applications. The deployment tasks are now (as of Capistrano 2.0) opt-in and require clients to explicitly put
+"load 'deploy'" in their recipes.
 
 == 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.
+* Net::SSH and Net::SFTP (http://net-ssh.rubyforge.org)
+* Needle (via Net::SSH)
+* HighLine (http://highline.rubyforge.org)
+
+If you want to run the tests, you'll also need to have the following dependencies installed:
+
+* Mocha (http://mocha.rubyforge.org)
 
 == 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):
+Capistrano is "opinionated software", which means it has very firm ideas about how things ought to be done, and tries to force those ideas on you. Some of the assumptions behind these opinions are:
 
-* 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.
+* You are using SSH to access the remote servers.
+* You either have the same password to all target machines, or you have public keys in place to allow passwordless access to them.
 
-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.
+Do not expect these assumptions to change.
 
 == 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).
+* Create a recipe file ("capfile" or "Capfile").
+* Use the +cap+ script to execute your recipe.
 
 Use the +cap+ script as follows:
 
-    cap -vvv someaction
+    cap sometask
+
+By default, the script will look for a file called one of +capfile+ or +Capfile+. The +someaction+ text indicates which task to execute. You can do "cap -h" to see all the available options and "cap -T" to see all the available tasks.
+
+== KNOWN ISSUES
 
-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.
+* Using "put" to upload a file to two or more hosts when a gateway is in effect has a good chance of crashing with a "corrupt mac detected" error. This is due to a bug in Net::SSH.
+* Running commands may rarely hang inexplicably. This appears to be specific only to certain platforms. Most people will never see this behavior.

data/bin/cap

@@ -1,11 +1,4 @@
 #!/usr/bin/env ruby
 
-begin
-  require 'rubygems'
-rescue LoadError
-  # no rubygems to load, so we fail silently
-end
-
 require 'capistrano/cli'
-
-Capistrano::CLI.execute!
+Capistrano::CLI.execute

data/bin/capify

@@ -0,0 +1,77 @@
+#!/usr/bin/env ruby
+
+require 'optparse'
+
+OptionParser.new do |opts|
+  opts.banner = "Usage: #{File.basename($0)} [path]"
+
+  opts.on("-h", "--help", "Displays this help info") do
+    puts opts
+    exit 0
+  end
+
+  begin
+    opts.parse!(ARGV)
+  rescue OptionParser::ParseError => e
+    warn e.message
+    puts opts
+    exit 1
+  end
+end
+
+if ARGV.empty?
+  abort "Please specify the directory to capify, e.g. `#{File.basename($0)} .'"
+elsif !File.exists?(ARGV.first)
+  abort "`#{ARGV.first}' does not exist."
+elsif !File.directory?(ARGV.first)
+  abort "`#{ARGV.first}' is not a directory."
+elsif ARGV.length > 1
+  abort "Too many arguments; please specify only the directory to capify."
+end
+
+def unindent(string)
+  indentation = string[/\A\s*/]
+  string.strip.gsub(/^#{indentation}/, "")
+end
+
+files = {
+  "Capfile" => unindent(<<-FILE),
+    load 'deploy' if respond_to?(:namespace) # cap2 differentiator
+    load 'config/deploy'
+  FILE
+
+  "config/deploy.rb" => unindent(<<-FILE),
+    set :application, "set your application name here"
+    set :repository,  "set your repository location here"
+
+    # If you aren't deploying to /u/apps/\#{application} on the target
+    # servers (which is the default), you can specify the actual location
+    # via the :deploy_to variable:
+    # set :deploy_to, "/var/www/\#{application}"
+
+    # If you aren't using Subversion to manage your source code, specify
+    # your SCM below:
+    # set :scm, :subversion
+
+    role :app, "your app-server here"
+    role :web, "your web-server here"
+    role :db,  "your db-server here", :primary => true
+  FILE
+}
+
+base = ARGV.shift
+files.each do |file, content|
+  file = File.join(base, file)
+  if File.exists?(file)
+    warn "[skip] `#{file}' already exists"
+  elsif File.exists?(file.downcase)
+    warn "[skip] `#{file.downcase}' exists, which could conflict with `#{file}'"
+  elsif !File.exists?(File.dirname(file))
+    warn "[skip] directory `#{File.dirname(file)}' does not exist"
+  else
+    puts "[add] writing `#{file}'"
+    File.open(file, "w") { |f| f.write(content) }
+  end
+end
+
+puts "[done] capified!"

data/examples/sample.rb

@@ -1,113 +1,14 @@
-# You must always specify the application and repository for every recipe. The
-# repository must be the URL of the repository you want this recipe to
-# correspond to. The deploy_to path must be the path on each machine that will
-# form the root of the application path.
+# set :user, "flippy"
+# set :password, "hello-flippy"
+# set :gateway, "gateway.example.com"
 
-set :application, "sample"
-set :repository, "http://svn.example.com/#{application}/trunk"
+role :web, "web1.example.com"
+role :app, "app1.example.com", "app2.example.com"
 
-# The deploy_to path is optional, defaulting to "/u/apps/#{application}".
-
-set :deploy_to, "/path/to/app/root"
-
-# The user value is optional, defaulting to user-name of the current user. This
-# is the user name that will be used when logging into the deployment boxes.
-
-set :user, "flippy"
-
-# By default, the source control module (scm) is set to "subversion". You can
-# set it to any supported scm:
-
-set :scm, :subversion
-
-# gateway is optional, but allows you to specify the address of a computer that
-# will be used to tunnel other requests through, such as when your machines are
-# all behind a VPN or something
-
-set :gateway, "gateway.example.com"
-
-# You can define any number of roles, each of which contains any number of
-# machines. Roles might include such things as :web, or :app, or :db, defining
-# what the purpose of each machine is. You can also specify options that can
-# be used to single out a specific subset of boxes in a particular role, like
-# :primary => true.
-
-role :web, "www01.example.com", "www02.example.com"
-role :app, "app01.example.com", "app02.example.com", "app03.example.com"
-role :db,  "db01.example.com", :primary => true
-role :db,  "db02.example.com", "db03.example.com"
-
-# Define tasks that run on all (or only some) of the machines. You can specify
-# a role (or set of roles) that each task should be executed on. You can also
-# narrow the set of servers to a subset of a role by specifying options, which
-# must match the options given for the servers to select (like :primary => true)
-
-desc <<DESC
-An imaginary backup task. (Execute the 'show_tasks' task to display all
-available tasks.)
+desc <<-DESC
+This is a sample task. It is only intended to be used as a demonstration of \
+how you can define your own tasks.
 DESC
-
-task :backup, :roles => :db, :only => { :primary => true } do
-  # the on_rollback handler is only executed if this task is executed within
-  # a transaction (see below), AND it or a subsequent task fails.
-  on_rollback { delete "/tmp/dump.sql" }
-
-  run "mysqldump -u theuser -p thedatabase > /tmp/dump.sql" do |ch, stream, out|
-    ch.send_data "thepassword\n" if out =~ /^Enter password:/
-  end
-end
-
-# Tasks may take advantage of several different helper methods to interact
-# with the remote server(s). These are:
-#
-# * run(command, options={}, &block): execute the given command on all servers
-#   associated with the current task, in parallel. The block, if given, should
-#   accept three parameters: the communication channel, a symbol identifying the
-#   type of stream (:err or :out), and the data. The block is invoked for all
-#   output from the command, allowing you to inspect output and act
-#   accordingly.
-# * sudo(command, options={}, &block): same as run, but it executes the command
-#   via sudo.
-# * delete(path, options={}): deletes the given file or directory from all
-#   associated servers. If :recursive => true is given in the options, the
-#   delete uses "rm -rf" instead of "rm -f".
-# * put(buffer, path, options={}): creates or overwrites a file at "path" on
-#   all associated servers, populating it with the contents of "buffer". You
-#   can specify :mode as an integer value, which will be used to set the mode
-#   on the file.
-# * render(template, options={}) or render(options={}): renders the given
-#   template and returns a string. Alternatively, if the :template key is given,
-#   it will be treated as the contents of the template to render. Any other keys
-#   are treated as local variables, which are made available to the (ERb)
-#   template.
-
-desc "Demonstrates the various helper methods available to recipes."
-task :helper_demo do
-  # "setup" is a standard task which sets up the directory structure on the
-  # remote servers. It is a good idea to run the "setup" task at least once
-  # at the beginning of your app's lifetime (it is non-destructive).
-  setup
-
-  buffer = render("maintenance.rhtml", :deadline => ENV['UNTIL'])
-  put buffer, "#{shared_path}/system/maintenance.html", :mode => 0644
-  sudo "killall -USR1 dispatch.fcgi"
-  run "#{release_path}/script/spin"
-  delete "#{shared_path}/system/maintenance.html"
-end
-
-# You can use "transaction" to indicate that if any of the tasks within it fail,
-# all should be rolled back (for each task that specifies an on_rollback
-# handler).
-
-desc "A task demonstrating the use of transactions."
-task :long_deploy do
-  transaction do
-    update_code
-    disable_web
-    symlink
-    migrate
-  end
-
-  restart
-  enable_web
+task :sample_task, :roles => :app do
+  run "ls -l"
 end

data/lib/capistrano.rb

@@ -1 +1,2 @@
 require 'capistrano/configuration'
+require 'capistrano/extensions'

data/lib/capistrano/callback.rb

@@ -0,0 +1,41 @@
+module Capistrano
+  class Callback
+    attr_reader :source, :options, :only, :except
+
+    def initialize(source, options={})
+      @source = source
+      @options = options
+      @only = Array(options[:only]).map { |v| v.to_s }
+      @except = Array(options[:except]).map { |v| v.to_s }
+    end
+
+    def applies_to?(task)
+      if task && only.any?
+        return only.include?(task.fully_qualified_name)
+      elsif task && except.any?
+        return !except.include?(task.fully_qualified_name)
+      else
+        return true
+      end
+    end
+  end
+
+  class ProcCallback < Callback
+    def call
+      source.call
+    end
+  end
+
+  class TaskCallback < Callback
+    attr_reader :config
+
+    def initialize(config, source, options={})
+      super(source, options)
+      @config = config
+    end
+
+    def call
+      config.find_and_execute_task(source)
+    end
+  end
+end