capistrano 2.0.0 → 2.15.5

data/lib/capistrano/recipes/deploy.rb

@@ -1,6 +1,9 @@
-require 'yaml'
-require 'capistrano/recipes/deploy/scm'
-require 'capistrano/recipes/deploy/strategy'
+require "benchmark"
+require "set"
+require "shellwords"
+require "yaml"
+require "capistrano/recipes/deploy/scm"
+require "capistrano/recipes/deploy/strategy"
 
 def _cset(name, *args, &block)
   unless exists?(name)
@@ -21,12 +24,15 @@ _cset(:repository)  { abort "Please specify the repository that houses your appl
 # are not sufficient.
 # =========================================================================
 
-_cset :scm, :subversion
+_cset(:scm) { scm_default }
 _cset :deploy_via, :checkout
 
 _cset(:deploy_to) { "/u/apps/#{application}" }
 _cset(:revision)  { source.head }
 
+_cset :rails_env, "production"
+_cset :rake, "rake"
+
 # =========================================================================
 # These variables should NOT be changed unless you are very confident in
 # what you are doing. Make sure you understand all the implications of your
@@ -34,23 +40,30 @@ _cset(:revision)  { source.head }
 # =========================================================================
 
 _cset(:source)            { Capistrano::Deploy::SCM.new(scm, self) }
-_cset(:real_revision)     { source.local.query_revision(revision) { |cmd| with_env("LC_ALL", "C") { `#{cmd}` } } }
+_cset(:real_revision)     { source.local.query_revision(revision) { |cmd| with_env("LC_ALL", "C") { run_locally(cmd) } } }
 
 _cset(:strategy)          { Capistrano::Deploy::Strategy.new(deploy_via, self) }
 
+# If overriding release name, please also select an appropriate setting for :releases below.
 _cset(:release_name)      { set :deploy_timestamped, true; Time.now.utc.strftime("%Y%m%d%H%M%S") }
-_cset(:releases_path)     { File.join(deploy_to, "releases") }
-_cset(:shared_path)       { File.join(deploy_to, "shared") }
-_cset(:current_path)      { File.join(deploy_to, "current") }
+
+_cset :version_dir,       "releases"
+_cset :shared_dir,        "shared"
+_cset :shared_children,   %w(public/system log tmp/pids)
+_cset :current_dir,       "current"
+
+_cset(:releases_path)     { File.join(deploy_to, version_dir) }
+_cset(:shared_path)       { File.join(deploy_to, shared_dir) }
+_cset(:current_path)      { File.join(deploy_to, current_dir) }
 _cset(:release_path)      { File.join(releases_path, release_name) }
 
-_cset(:releases)          { capture("ls -x #{releases_path}").split.sort }
-_cset(:current_release)   { File.join(releases_path, releases.last) }
-_cset(:previous_release)  { File.join(releases_path, releases[-2]) }
+_cset(:releases)          { capture("#{try_sudo} ls -x #{releases_path}", :except => { :no_release => true }).split.sort }
+_cset(:current_release)   { releases.length > 0 ? File.join(releases_path, releases.last) : nil }
+_cset(:previous_release)  { releases.length > 1 ? File.join(releases_path, releases[-2]) : nil }
 
-_cset(:current_revision)  { capture("cat #{current_path}/REVISION").chomp }
-_cset(:latest_revision)   { capture("cat #{current_release}/REVISION").chomp }
-_cset(:previous_revision) { capture("cat #{previous_release}/REVISION").chomp }
+_cset(:current_revision)  { capture("#{try_sudo} cat #{current_path}/REVISION",     :except => { :no_release => true }).chomp }
+_cset(:latest_revision)   { capture("#{try_sudo} cat #{current_release}/REVISION",  :except => { :no_release => true }).chomp }
+_cset(:previous_revision) { capture("#{try_sudo} cat #{previous_release}/REVISION", :except => { :no_release => true }).chomp if previous_release }
 
 _cset(:run_method)        { fetch(:use_sudo, true) ? :sudo : :run }
 
@@ -61,10 +74,39 @@ _cset(:run_method)        { fetch(:use_sudo, true) ? :sudo : :run }
 # standalone case, or during deployment.
 _cset(:latest_release) { exists?(:deploy_timestamped) ? release_path : current_release }
 
+_cset :maintenance_basename, "maintenance"
+_cset(:maintenance_template_path) { File.join(File.dirname(__FILE__), "templates", "maintenance.rhtml") }
 # =========================================================================
 # These are helper methods that will be available to your recipes.
 # =========================================================================
 
+# Checks known version control directories to intelligently set the version
+# control in-use. For example, if a .svn directory exists in the project,
+# it will set the :scm variable to :subversion, if a .git directory exists
+# in the project, it will set the :scm variable to :git and so on. If no
+# directory is found, it will default to :git.
+def scm_default
+  if File.exist? '.git'
+    :git
+  elsif File.exist? '.accurev'
+    :accurev
+  elsif File.exist? '.bzr'
+    :bzr
+  elsif File.exist? '.cvs'
+    :cvs
+  elsif File.exist? '_darcs'
+    :darcs
+  elsif File.exist? '.hg'
+    :mercurial
+  elsif File.exist? '.perforce'
+    :perforce
+  elsif File.exist? '.svn'
+    :subversion
+  else
+    :none
+  end
+end
+
 # Auxiliary helper method for the `deploy:check' task. Lets you set up your
 # own dependencies.
 def depend(location, type, *args)
@@ -84,6 +126,64 @@ ensure
   ENV[name] = saved
 end
 
+# logs the command then executes it locally.
+# returns the command output as a string
+def run_locally(cmd)
+  if dry_run
+    return logger.debug "executing locally: #{cmd.inspect}"
+  end
+  logger.trace "executing locally: #{cmd.inspect}" if logger
+  output_on_stdout = nil
+  elapsed = Benchmark.realtime do
+    output_on_stdout = `#{cmd}`
+  end
+  if $?.to_i > 0 # $? is command exit code (posix style)
+    raise Capistrano::LocalArgumentError, "Command #{cmd} returned status code #{$?}"
+  end
+  logger.trace "command finished in #{(elapsed * 1000).round}ms" if logger
+  output_on_stdout
+end
+
+
+# If a command is given, this will try to execute the given command, as
+# described below. Otherwise, it will return a string for use in embedding in
+# another command, for executing that command as described below.
+#
+# If :run_method is :sudo (or :use_sudo is true), this executes the given command
+# via +sudo+. Otherwise is uses +run+. If :as is given as a key, it will be
+# passed as the user to sudo as, if using sudo. If the :as key is not given,
+# it will default to whatever the value of the :admin_runner variable is,
+# which (by default) is unset.
+#
+# THUS, if you want to try to run something via sudo, and what to use the
+# root user, you'd just to try_sudo('something'). If you wanted to try_sudo as
+# someone else, you'd just do try_sudo('something', :as => "bob"). If you
+# always wanted sudo to run as a particular user, you could do
+# set(:admin_runner, "bob").
+def try_sudo(*args)
+  options = args.last.is_a?(Hash) ? args.pop : {}
+  command = args.shift
+  raise ArgumentError, "too many arguments" if args.any?
+
+  as = options.fetch(:as, fetch(:admin_runner, nil))
+  via = fetch(:run_method, :sudo)
+  if command
+    invoke_command(command, :via => via, :as => as)
+  elsif via == :sudo
+    sudo(:as => as)
+  else
+    ""
+  end
+end
+
+# Same as sudo, but tries sudo with :as set to the value of the :runner
+# variable (which defaults to "app").
+def try_runner(*args)
+  options = args.last.is_a?(Hash) ? args.pop : {}
+  args << options.merge(:as => fetch(:runner, "app"))
+  try_sudo(*args)
+end
+
 # =========================================================================
 # These are the tasks that are available to help with deploying web apps,
 # and specifically, Rails applications. You can have cap give you a summary
@@ -105,19 +205,20 @@ namespace :deploy do
   desc <<-DESC
     Prepares one or more servers for deployment. Before you can use any \
     of the Capistrano deployment tasks with your project, you will need to \
-    make sure all of your servers have been prepared with `cap setup'. When \
+    make sure all of your servers have been prepared with `cap deploy:setup'. When \
     you add a new server to your cluster, you can easily run the setup task \
     on just that server by specifying the HOSTS environment variable:
 
-      $ cap HOSTS=new.server.com setup
+      $ cap HOSTS=new.server.com deploy:setup
 
     It is safe to run this task on servers that have already been set up; it \
     will not destroy any deployed revisions or data.
   DESC
   task :setup, :except => { :no_release => true } do
     dirs = [deploy_to, releases_path, shared_path]
-    dirs += %w(system log pids).map { |d| File.join(shared_path, d) }
-    run "umask 02 && mkdir -p #{dirs.join(' ')}"
+    dirs += shared_children.map { |d| File.join(shared_path, d.split('/').last) }
+    run "#{try_sudo} mkdir -p #{dirs.join(' ')}"
+    run "#{try_sudo} chmod g+w #{dirs.join(' ')}" if fetch(:group_writable, true)
   end
 
   desc <<-DESC
@@ -131,7 +232,7 @@ namespace :deploy do
   task :update do
     transaction do
       update_code
-      symlink
+      create_symlink
     end
   end
 
@@ -164,25 +265,47 @@ namespace :deploy do
     symlinks to the shared directory for the log, system, and tmp/pids \
     directories, and will lastly touch all assets in public/images, \
     public/stylesheets, and public/javascripts so that the times are \
-    consistent (so that asset timestamping works).
+    consistent (so that asset timestamping works).  This touch process \
+    is only carried out if the :normalize_asset_timestamps variable is \
+    set to true, which is the default. The asset directories can be overridden \
+    using the :public_children variable.
   DESC
   task :finalize_update, :except => { :no_release => true } do
-    run "chmod -R g+w #{latest_release}" if fetch(:group_writable, true)
+    escaped_release = latest_release.to_s.shellescape
+    commands = []
+    commands << "chmod -R -- g+w #{escaped_release}" if fetch(:group_writable, true)
 
     # mkdir -p is making sure that the directories are there for some SCM's that don't
     # save empty folders
-    run <<-CMD
-      rm -rf #{latest_release}/log #{latest_release}/public/system #{latest_release}/tmp/pids &&
-      mkdir -p #{latest_release}/public &&
-      mkdir -p #{latest_release}/tmp &&
-      ln -s #{shared_path}/log #{latest_release}/log &&
-      ln -s #{shared_path}/system #{latest_release}/public/system &&
-      ln -s #{shared_path}/pids #{latest_release}/tmp/pids
-    CMD
-
-    stamp = Time.now.utc.strftime("%Y%m%d%H%M.%S")
-    asset_paths = %w(images stylesheets javascripts).map { |p| "#{latest_release}/public/#{p}" }.join(" ")
-    run "find #{asset_paths} -exec touch -t #{stamp} {} ';'; true", :env => { "TZ" => "UTC" }
+    shared_children.map do |dir|
+      d = dir.shellescape
+      if (dir.rindex('/')) then
+        commands += ["rm -rf -- #{escaped_release}/#{d}",
+                     "mkdir -p -- #{escaped_release}/#{dir.slice(0..(dir.rindex('/'))).shellescape}"]
+      else
+        commands << "rm -rf -- #{escaped_release}/#{d}"
+      end
+      commands << "ln -s -- #{shared_path}/#{dir.split('/').last.shellescape} #{escaped_release}/#{d}"
+    end
+
+    run commands.join(' && ') if commands.any?
+
+    if fetch(:normalize_asset_timestamps, true)
+      stamp = Time.now.utc.strftime("%Y%m%d%H%M.%S")
+      asset_paths = fetch(:public_children, %w(images stylesheets javascripts)).
+        map { |p| "#{latest_release}/public/#{p}" }.
+        map { |p| p.shellescape }
+      run("find #{asset_paths.join(" ")} -exec touch -t #{stamp} -- {} ';'; true",
+          :env => { "TZ" => "UTC" }) if asset_paths.any?
+    end
+  end
+
+  desc <<-DESC
+    Deprecated API. This has become deploy:create_symlink, please update your recipes
+  DESC
+  task :symlink, :except => { :no_release => true } do
+    Kernel.warn "[Deprecation Warning] This API has changed, please hook `deploy:create_symlink` instead of `deploy:symlink`."
+    create_symlink
   end
 
   desc <<-DESC
@@ -194,9 +317,16 @@ namespace :deploy do
     deploy, including `restart') or the 'update' task (which does everything \
     except `restart').
   DESC
-  task :symlink, :except => { :no_release => true } do
-    on_rollback { run "rm -f #{current_path}; ln -s #{previous_release} #{current_path}; true" }
-    run "rm -f #{current_path} && ln -s #{latest_release} #{current_path}"
+  task :create_symlink, :except => { :no_release => true } do
+    on_rollback do
+      if previous_release
+        run "#{try_sudo} rm -f #{current_path}; #{try_sudo} ln -s #{previous_release} #{current_path}; true"
+      else
+        logger.important "no previous release to rollback to, rollback of symlink skipped"
+      end
+    end
+
+    run "#{try_sudo} rm -f #{current_path} && #{try_sudo} ln -s #{latest_release} #{current_path}"
   end
 
   desc <<-DESC
@@ -209,60 +339,73 @@ namespace :deploy do
     To use this task, specify the files and directories you want to copy as a \
     comma-delimited list in the FILES environment variable. All directories \
     will be processed recursively, with all files being pushed to the \
-    deployment servers. Any file or directory starting with a '.' character \
-    will be ignored.
+    deployment servers.
 
       $ cap deploy:upload FILES=templates,controller.rb
+
+    Dir globs are also supported:
+
+      $ cap deploy:upload FILES='config/apache/*.conf'
   DESC
   task :upload, :except => { :no_release => true } do
-    files = (ENV["FILES"] || "").
-      split(",").
-      map { |f| f.strip!; File.directory?(f) ? Dir["#{f}/**/*"] : f }.
-      flatten.
-      reject { |f| File.directory?(f) || File.basename(f)[0] == ?. }
-
-    abort "Please specify at least one file to update (via the FILES environment variable)" if files.empty?
+    files = (ENV["FILES"] || "").split(",").map { |f| Dir[f.strip] }.flatten
+    abort "Please specify at least one file or directory to update (via the FILES environment variable)" if files.empty?
 
-    files.each do |file|
-      put File.read(file), File.join(current_path, file)
-    end
+    files.each { |file| top.upload(file, File.join(current_path, file)) }
   end
 
   desc <<-DESC
-    Restarts your application. This works by calling the script/process/reaper \
-    script under the current path. By default, this will be invoked via sudo, \
-    but if you are in an environment where sudo is not an option, or is not \
-    allowed, you can indicate that restarts should use `run' instead by \
-    setting the `use_sudo' variable to false:
-
-      set :use_sudo, false
+    Blank task exists as a hook into which to install your own environment \
+    specific behaviour.
   DESC
   task :restart, :roles => :app, :except => { :no_release => true } do
-    invoke_command "#{current_path}/script/process/reaper", :via => run_method
+    # Empty Task to overload with your platform specifics
   end
 
-  desc <<-DESC
-    Rolls back to the previously deployed version. The `current' symlink will \
-    be updated to point at the previously deployed version, and then the \
-    current release will be removed from the servers. You'll generally want \
-    to call `rollback' instead, as it performs a `restart' as well.
-  DESC
-  task :rollback_code, :except => { :no_release => true } do
-    if releases.length < 2
-      abort "could not rollback the code because there is no prior release"
-    else
-      run "rm #{current_path}; ln -s #{previous_release} #{current_path} && rm -rf #{current_release}"
+  namespace :rollback do
+    desc <<-DESC
+      [internal] Points the current symlink at the previous revision.
+      This is called by the rollback sequence, and should rarely (if
+      ever) need to be called directly.
+    DESC
+    task :revision, :except => { :no_release => true } do
+      if previous_release
+        run "#{try_sudo} rm #{current_path}; #{try_sudo} ln -s #{previous_release} #{current_path}"
+      else
+        abort "could not rollback the code because there is no prior release"
+      end
     end
-  end
 
-  desc <<-DESC
-    Rolls back to a previous version and restarts. This is handy if you ever \
-    discover that you've deployed a lemon; `cap rollback' and you're right \
-    back where you were, on the previously deployed version.
-  DESC
-  task :rollback do
-    rollback_code
-    restart
+    desc <<-DESC
+      [internal] Removes the most recently deployed release.
+      This is called by the rollback sequence, and should rarely
+      (if ever) need to be called directly.
+    DESC
+    task :cleanup, :except => { :no_release => true } do
+      run "if [ `readlink #{current_path}` != #{current_release} ]; then #{try_sudo} rm -rf #{current_release}; fi"
+    end
+
+    desc <<-DESC
+      Rolls back to the previously deployed version. The `current' symlink will \
+      be updated to point at the previously deployed version, and then the \
+      current release will be removed from the servers. You'll generally want \
+      to call `rollback' instead, as it performs a `restart' as well.
+    DESC
+    task :code, :except => { :no_release => true } do
+      revision
+      cleanup
+    end
+
+    desc <<-DESC
+      Rolls back to a previous version and restarts. This is handy if you ever \
+      discover that you've deployed a lemon; `cap rollback' and you're right \
+      back where you were, on the previously deployed version.
+    DESC
+    task :default do
+      revision
+      restart
+      cleanup
+    end
   end
 
   desc <<-DESC
@@ -288,11 +431,11 @@ namespace :deploy do
 
     directory = case migrate_target.to_sym
       when :current then current_path
-      when :latest  then current_release
+      when :latest  then latest_release
       else raise ArgumentError, "unknown migration target #{migrate_target.inspect}"
       end
 
-    run "cd #{directory}; #{rake} RAILS_ENV=#{rails_env} #{migrate_env} db:migrate"
+    run "cd #{directory} && #{rake} RAILS_ENV=#{rails_env} #{migrate_env} db:migrate"
   end
 
   desc <<-DESC
@@ -306,7 +449,7 @@ namespace :deploy do
     set :migrate_target, :latest
     update_code
     migrate
-    symlink
+    create_symlink
     restart
   end
 
@@ -319,16 +462,7 @@ namespace :deploy do
   DESC
   task :cleanup, :except => { :no_release => true } do
     count = fetch(:keep_releases, 5).to_i
-    if count >= releases.length
-      logger.important "no old releases to clean up"
-    else
-      logger.info "keeping #{count} of #{releases.length} deployed releases"
-
-      directories = (releases - releases.last(count)).map { |release|
-        File.join(releases_path, release) }.join(" ")
-
-      invoke_command "rm -rf #{directories}", :via => run_method
-    end
+    try_sudo "ls -1dt #{releases_path}/* | tail -n +#{count + 1} | #{try_sudo} xargs rm -rf"
   end
 
   desc <<-DESC
@@ -384,40 +518,19 @@ namespace :deploy do
   end
 
   desc <<-DESC
-    Start the application servers. This will attempt to invoke a script \
-    in your application called `script/spin', which must know how to start \
-    your application listeners. For Rails applications, you might just have \
-    that script invoke `script/process/spawner' with the appropriate \
-    arguments.
-
-    By default, the script will be executed via sudo as the `app' user. If \
-    you wish to run it as a different user, set the :runner variable to \
-    that user. If you are in an environment where you can't use sudo, set \
-    the :use_sudo variable to false.
+    Blank task exists as a hook into which to install your own environment \
+    specific behaviour.
   DESC
   task :start, :roles => :app do
-    as = fetch(:runner, "app")
-    via = fetch(:run_method, :sudo)
-    invoke_command "sh -c 'cd #{current_path} && nohup script/spin'", :via => via, :as => as
+    # Empty Task to overload with your platform specifics
   end
 
   desc <<-DESC
-    Stop the application servers. This will call script/process/reaper for \
-    both the spawner process, and all of the application processes it has \
-    spawned. As such, it is fairly Rails specific and may need to be \
-    overridden for other systems.
-
-    By default, the script will be executed via sudo as the `app' user. If \
-    you wish to run it as a different user, set the :runner variable to \
-    that user. If you are in an environment where you can't use sudo, set \
-    the :use_sudo variable to false.
+    Blank task exists as a hook into which to install your own environment \
+    specific behaviour.
   DESC
   task :stop, :roles => :app do
-    as = fetch(:runner, "app")
-    via = fetch(:run_method, :sudo)
-
-    invoke_command "#{current_path}/script/process/reaper -a kill -r dispatch.spawner.pid", :via => via, :as => as
-    invoke_command "#{current_path}/script/process/reaper -a kill", :via => via, :as => as
+    # Empty Task to overload with your platform specifics
   end
 
   namespace :pending do
@@ -436,14 +549,15 @@ namespace :deploy do
       might not be supported on all SCM's.
     DESC
     task :default, :except => { :no_release => true } do
-      system(source.local.log(current_revision))
+      from = source.next_revision(current_revision)
+      system(source.local.log(from))
     end
   end
 
   namespace :web do
     desc <<-DESC
       Present a maintenance page to visitors. Disables your application's web \
-      interface by writing a "maintenance.html" file to each web server. The \
+      interface by writing a "#{maintenance_basename}.html" file to each web server. The \
       servers must be configured to detect the presence of this file, and if \
       it is present, always display it instead of performing the request.
 
@@ -455,29 +569,57 @@ namespace :deploy do
               REASON="hardware upgrade" \\
               UNTIL="12pm Central Time"
 
+      You can use a different template for the maintenance page by setting the \
+      :maintenance_template_path variable in your deploy.rb file. The template file \
+      should either be a plaintext or an erb file.
+
       Further customization will require that you write your own task.
     DESC
     task :disable, :roles => :web, :except => { :no_release => true } do
       require 'erb'
-      on_rollback { run "rm #{shared_path}/system/maintenance.html" }
+      on_rollback { run "rm -f #{shared_path}/system/#{maintenance_basename}.html" }
+
+      warn <<-EOHTACCESS
+
+        # Please add something like this to your site's Apache htaccess to redirect users to the maintenance page.
+        # More Info: http://www.shiftcommathree.com/articles/make-your-rails-maintenance-page-respond-with-a-503
+
+        ErrorDocument 503 /system/#{maintenance_basename}.html
+        RewriteEngine On
+        RewriteCond %{REQUEST_URI} !\.(css|gif|jpg|png)$
+        RewriteCond %{DOCUMENT_ROOT}/system/#{maintenance_basename}.html -f
+        RewriteCond %{SCRIPT_FILENAME} !#{maintenance_basename}.html
+        RewriteRule ^.*$  -  [redirect=503,last]
+
+        # Or if you are using Nginx add this to your server config:
+
+        if (-f $document_root/system/maintenance.html) {
+          return 503;
+        }
+        error_page 503 @maintenance;
+        location @maintenance {
+          rewrite  ^(.*)$  /system/maintenance.html break;
+          break;
+        }
+      EOHTACCESS
 
       reason = ENV['REASON']
       deadline = ENV['UNTIL']
 
-      template = File.read(File.join(File.dirname(__FILE__), "templates", "maintenance.rhtml"))
+      template = File.read(maintenance_template_path)
       result = ERB.new(template).result(binding)
 
-      put result, "#{shared_path}/system/maintenance.html", :mode => 0644
+      put result, "#{shared_path}/system/#{maintenance_basename}.html", :mode => 0644
     end
 
     desc <<-DESC
       Makes the application web-accessible again. Removes the \
-      "maintenance.html" page generated by deploy:web:disable, which (if your \
+      "#{maintenance_basename}.html" page generated by deploy:web:disable, which (if your \
       web servers are configured correctly) will make your application \
       web-accessible again.
     DESC
     task :enable, :roles => :web, :except => { :no_release => true } do
-      run "rm #{shared_path}/system/maintenance.html"
+      run "rm -f #{shared_path}/system/#{maintenance_basename}.html"
     end
   end
 end

data/lib/capistrano/recipes/standard.rb

@@ -34,4 +34,4 @@ DESC
 task :shell do
   require 'capistrano/shell'
   Capistrano::Shell.run(self)
-end
+end