capistrano 1.4.2 → 2.0.0

data/lib/capistrano/recipes/deploy/strategy/base.rb

@@ -0,0 +1,64 @@
+require 'capistrano/recipes/deploy/dependencies'
+
+module Capistrano
+  module Deploy
+    module Strategy
+
+      # This class defines the abstract interface for all Capistrano
+      # deployment strategies. Subclasses must implement at least the
+      # #deploy! method.
+      class Base
+        attr_reader :configuration
+
+        # Instantiates a strategy with a reference to the given configuration.
+        def initialize(config={})
+          @configuration = config
+        end
+
+        # Executes the necessary commands to deploy the revision of the source
+        # code identified by the +revision+ variable. Additionally, this
+        # should write the value of the +revision+ variable to a file called
+        # REVISION, in the base of the deployed revision. This file is used by
+        # other tasks, to perform diffs and such.
+        def deploy!
+          raise NotImplementedError, "`deploy!' is not implemented by #{self.class.name}"
+        end
+
+        # Performs a check on the remote hosts to determine whether everything
+        # is setup such that a deploy could succeed.
+        def check!
+          Dependencies.new(configuration) do |d|
+            d.remote.directory(configuration[:releases_path]).or("`#{configuration[:releases_path]}' does not exist. Please run `cap deploy:setup'.")
+            d.remote.writable(configuration[:deploy_to]).or("You do not have permissions to write to `#{configuration[:deploy_to]}'.")
+            d.remote.writable(configuration[:releases_path]).or("You do not have permissions to write to `#{configuration[:releases_path]}'.")
+          end
+        end
+          
+        protected
+
+          # This is to allow helper methods like "run" and "put" to be more
+          # easily accessible to strategy implementations.
+          def method_missing(sym, *args, &block)
+            if configuration.respond_to?(sym)
+              configuration.send(sym, *args, &block)
+            else
+              super
+            end
+          end
+
+        private
+
+          def logger
+            @logger ||= configuration[:logger] || Capistrano::Logger.new(:output => STDOUT)
+          end
+
+          # The revision to deploy. Must return a real revision identifier,
+          # and not a pseudo-id.
+          def revision
+            configuration[:real_revision]
+          end
+      end
+
+    end
+  end
+end

data/lib/capistrano/recipes/deploy/strategy/checkout.rb

@@ -0,0 +1,20 @@
+require 'capistrano/recipes/deploy/strategy/remote'
+
+module Capistrano
+  module Deploy
+    module Strategy
+
+      # Implements the deployment strategy which does an SCM checkout on each
+      # target host. This is the default deployment strategy for Capistrano.
+      class Checkout < Remote
+        protected
+
+          # Returns the SCM's checkout command for the revision to deploy.
+          def command
+            @command ||= source.checkout(revision, configuration[:release_path])
+          end
+      end
+
+    end
+  end
+end

data/lib/capistrano/recipes/deploy/strategy/copy.rb

@@ -0,0 +1,143 @@
+require 'capistrano/recipes/deploy/strategy/base'
+require 'fileutils'
+require 'tempfile'  # Dir.tmpdir
+
+module Capistrano
+  module Deploy
+    module Strategy
+
+      # This class implements the strategy for deployments which work
+      # by preparing the source code locally, compressing it, copying the
+      # file to each target host, and uncompressing it to the deployment
+      # directory.
+      #
+      # By default, the SCM checkout command is used to obtain the local copy
+      # of the source code. If you would rather use the export operation,
+      # you can set the :copy_strategy variable to :export.
+      #
+      # This deployment strategy supports a special variable,
+      # :copy_compression, which must be one of :gzip, :bz2, or
+      # :zip, and which specifies how the source should be compressed for
+      # transmission to each host.
+      class Copy < Base
+        # Obtains a copy of the source code locally (via the #command method),
+        # compresses it to a single file, copies that file to all target
+        # servers, and uncompresses it on each of them into the deployment
+        # directory.
+        def deploy!
+          logger.debug "getting (via #{copy_strategy}) revision #{revision} to #{destination}"
+          system(command)
+          File.open(File.join(destination, "REVISION"), "w") { |f| f.puts(revision) }
+
+          logger.trace "compressing #{destination} to #{filename}"
+          Dir.chdir(tmpdir) { system(compress(File.basename(destination), File.basename(filename)).join(" ")) }
+
+          put File.read(filename), remote_filename
+          run "cd #{configuration[:releases_path]} && #{decompress(remote_filename).join(" ")} && rm #{remote_filename}"
+        ensure
+          FileUtils.rm filename rescue nil
+          FileUtils.rm_rf destination rescue nil
+        end
+
+        def check!
+          super.check do |d|
+            d.local.command(source.local.command)
+            d.local.command(compress(nil, nil).first)
+            d.remote.command(decompress(nil).first)
+          end
+        end
+
+        private
+
+          # Returns the basename of the release_path, which will be used to
+          # name the local copy and archive file.
+          def destination
+            @destination ||= File.join(tmpdir, File.basename(configuration[:release_path]))
+          end
+
+          # Returns the value of the :copy_strategy variable, defaulting to
+          # :checkout if it has not been set.
+          def copy_strategy
+            @copy_strategy ||= configuration.fetch(:copy_strategy, :checkout)
+          end
+
+          # Should return the command(s) necessary to obtain the source code
+          # locally.
+          def command
+            @command ||= case copy_strategy
+            when :checkout
+              source.checkout(revision, destination)
+            when :export
+              source.export(revision, destination)
+            end
+          end
+
+          # Returns the name of the file that the source code will be
+          # compressed to.
+          def filename
+            @filename ||= File.join(tmpdir, "#{File.basename(destination)}.#{compression_extension}")
+          end
+
+          # The directory to which the copy should be checked out
+          def tmpdir
+            @tmpdir ||= configuration[:copy_dir] || Dir.tmpdir
+          end
+
+          # The directory on the remote server to which the archive should be
+          # copied
+          def remote_dir
+            @remote_dir ||= configuration[:copy_remote_dir] || "/tmp"
+          end
+
+          # The location on the remote server where the file should be
+          # temporarily stored.
+          def remote_filename
+            @remote_filename ||= File.join(remote_dir, File.basename(filename))
+          end
+
+          # The compression method to use, defaults to :gzip.
+          def compression
+            configuration[:copy_compression] || :gzip
+          end
+
+          # Returns the file extension used for the compression method in
+          # question.
+          def compression_extension
+            case compression
+            when :gzip, :gz   then "tar.gz"
+            when :bzip2, :bz2 then "tar.bz2"
+            when :zip         then "zip"
+            else raise ArgumentError, "invalid compression type #{compression.inspect}"
+            end
+          end
+
+          # Returns the command necessary to compress the given directory
+          # into the given file. The command is returned as an array, where
+          # the first element is the utility to be used to perform the compression.
+          def compress(directory, file)
+            case compression
+            when :gzip, :gz   then ["tar", "czf", file, directory]
+            when :bzip2, :bz2 then ["tar", "cjf", file, directory]
+            when :zip         then ["zip", "-qr", file, directory]
+            else raise ArgumentError, "invalid compression type #{compression.inspect}"
+            end
+          end
+
+          # Returns the command necessary to decompress the given file,
+          # relative to the current working directory. It must also
+          # preserve the directory structure in the file. The command is returned
+          # as an array, where the first element is the utility to be used to
+          # perform the decompression.
+          def decompress(file)
+            case compression
+            when :gzip, :gz   then ["tar", "xzf", file]
+            when :bzip2, :bz2 then ["tar", "xjf", file]
+            when :zip         then ["unzip", "-q", file]
+            else raise ArgumentError, "invalid compression type #{compression.inspect}"
+            end
+          end
+      end
+
+    end
+  end
+end

data/lib/capistrano/recipes/deploy/strategy/export.rb

@@ -0,0 +1,20 @@
+require 'capistrano/recipes/deploy/strategy/remote'
+
+module Capistrano
+  module Deploy
+    module Strategy
+
+      # Implements the deployment strategy which does an SCM export on each
+      # target host.
+      class Export < Remote
+        protected
+
+          # Returns the SCM's export command for the revision to deploy.
+          def command
+            @command ||= source.export(revision, configuration[:release_path])
+          end
+      end
+
+    end
+  end
+end

data/lib/capistrano/recipes/deploy/strategy/remote.rb

@@ -0,0 +1,52 @@
+require 'capistrano/recipes/deploy/strategy/base'
+
+module Capistrano
+  module Deploy
+    module Strategy
+
+      # An abstract superclass, which forms the base for all deployment
+      # strategies which work by grabbing the code from the repository directly
+      # from remote host. This includes deploying by checkout (the default),
+      # and deploying by export.
+      class Remote < Base
+        # Executes the SCM command for this strategy and writes the REVISION
+        # mark file to each host.
+        def deploy!
+          scm_run "#{command} && #{mark}"
+        end
+
+        def check!
+          super.check do |d|
+            d.remote.command(source.command)
+          end
+        end
+
+        protected
+
+          # Runs the given command, filtering output back through the
+          # #handle_data filter of the SCM implementation.
+          def scm_run(command)
+            run(command) do |ch,stream,text|
+              ch[:state] ||= {}
+              output = source.handle_data(ch[:state], stream, text)
+              ch.send_data(output) if output
+            end
+          end
+
+          # An abstract method which must be overridden in subclasses, to
+          # return the actual SCM command(s) which must be executed on each
+          # target host in order to perform the deployment.
+          def command
+            raise NotImplementedError, "`command' is not implemented by #{self.class.name}"
+          end
+
+          # Returns the command which will write the identifier of the
+          # revision being deployed to the REVISION file on each host.
+          def mark
+            "(echo #{revision} > #{configuration[:release_path]}/REVISION)"
+          end
+      end
+
+    end
+  end
+end

data/lib/capistrano/recipes/deploy/strategy/remote_cache.rb

@@ -0,0 +1,47 @@
+require 'capistrano/recipes/deploy/strategy/remote'
+
+module Capistrano
+  module Deploy
+    module Strategy
+
+      # Implements the deployment strategy that keeps a cached checkout of
+      # the source code on each remote server. Each deploy simply updates the
+      # cached checkout, and then does a copy from the cached copy to the
+      # final deployment location.
+      class RemoteCache < Remote
+        # Executes the SCM command for this strategy and writes the REVISION
+        # mark file to each host.
+        def deploy!
+          update_repository_cache
+          copy_repository_cache
+        end
+
+        def check!
+          super.check do |d|
+            d.remote.writable(shared_path)
+          end
+        end
+
+        private
+
+          def repository_cache
+            File.join(shared_path, configuration[:repository_cache] || "cached-copy")
+          end
+
+          def update_repository_cache
+            logger.trace "updating the cached checkout on all servers"
+            command = "if [ -d #{repository_cache} ]; then " +
+              "#{source.sync(revision, repository_cache)}; " +
+              "else #{source.checkout(revision, repository_cache)}; fi"
+            scm_run(command)
+          end
+
+          def copy_repository_cache
+            logger.trace "copying the cached version to #{configuration[:release_path]}"
+            run "cp -RPp #{repository_cache} #{configuration[:release_path]} && #{mark}"
+          end
+      end
+
+    end
+  end
+end

data/lib/capistrano/recipes/deploy/templates/maintenance.rhtml

@@ -0,0 +1,53 @@
+
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
+       "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
+
+<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
+
+<head>
+  <meta http-equiv="content-type" content="text/html;charset=UTF-8" />
+  <title>System down for maintenance</title>
+
+  <style type="text/css">
+    div.outer {
+      position: absolute;
+      left: 50%;
+      top: 50%;
+      width: 500px;
+      height: 300px;
+      margin-left: -260px; 
+      margin-top: -150px;
+    }
+
+    .DialogBody {
+      margin: 0;
+      padding: 10px;
+      text-align: left;
+      border: 1px solid #ccc;
+      border-right: 1px solid #999;
+      border-bottom: 1px solid #999;
+      background-color: #fff;
+    }
+
+    body { background-color: #fff; }
+  </style>
+</head>
+
+<body>
+
+  <div class="outer">
+     <div class="DialogBody" style="text-align: center;">
+       <div style="text-align: center; width: 200px; margin: 0 auto;">
+         <p style="color: red; font-size: 16px; line-height: 20px;">
+           The system is down for <%= reason ? reason : "maintenance" %>
+           as of <%= Time.now.strftime("%H:%M %Z") %>.
+         </p>
+         <p style="color: #666;">
+           It'll be back <%= deadline ? deadline : "shortly" %>.
+         </p>
+       </div>
+     </div>
+  </div>
+
+</body>
+</html>

data/lib/capistrano/recipes/standard.rb

@@ -1,287 +1,37 @@
-# Standard tasks that are useful for most recipes. It makes a few assumptions:
-# 
-# * The :app role has been defined as the set of machines consisting of the
-#   application servers.
-# * The :web role has been defined as the set of machines consisting of the
-#   web servers.
-# * The :db role has been defined as the set of machines consisting of the
-#   databases, with exactly one set up as the :primary DB server.
-# * The Rails spawner and reaper scripts are being used to manage the FCGI
-#   processes.
-
-set :rake, "rake"
-
-set :rails_env, :production
-
-set :migrate_target, :current
-set :migrate_env, ""
-
-set :use_sudo, true
-set(:run_method) { use_sudo ? :sudo : :run }
-
-set :spinner_user, :app
-
-desc "Enumerate and describe every available task."
-task :show_tasks do
-  puts "Available tasks"
-  puts "---------------"
-  each_task do |info|
-    wrap_length = 80 - info[:longest] - 1
-    lines = info[:desc].gsub(/(.{1,#{wrap_length}})(?:\s|\Z)+/, "\\1\n").split(/\n/)
-    puts "%-#{info[:longest]}s %s" % [info[:task], lines.shift]
-    puts "%#{info[:longest]}s %s" % ["", lines.shift] until lines.empty?
-    puts
-  end
-end
-
-desc "Set up the expected application directory structure on all boxes"
-task :setup, :except => { :no_release => true } do
-  run <<-CMD
-    umask 02 &&
-    mkdir -p #{deploy_to} #{releases_path} #{shared_path} #{shared_path}/system &&
-    mkdir -p #{shared_path}/log &&
-    mkdir -p #{shared_path}/pids
-  CMD
-end
-
-desc <<-DESC
-Disable the web server by writing a "maintenance.html" file to the web
-servers. 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.
-DESC
-task :disable_web, :roles => :web do
-  on_rollback { delete "#{shared_path}/system/maintenance.html" }
-
-  maintenance = render("maintenance", :deadline => ENV['UNTIL'],
-    :reason => ENV['REASON'])
-  put maintenance, "#{shared_path}/system/maintenance.html", :mode => 0644
-end
-
-desc %(Re-enable the web server by deleting any "maintenance.html" file.)
-task :enable_web, :roles => :web do
-  delete "#{shared_path}/system/maintenance.html"
-end
-
-desc <<-DESC
-Sets group permissions on checkout. Useful for team environments, bad on
-shared hosts. Override this task if you're on a shared host.
-DESC
-task :set_permissions, :except => { :no_release => true } do
-  run "chmod -R g+w #{release_path}"
-end
-
-desc <<-DESC
-Update all servers with the latest release of the source code. All this does
-is do a checkout (as defined by the selected scm module).
-DESC
-task :update_code, :except => { :no_release => true } do
-  on_rollback { delete release_path, :recursive => true }
-
-  source.checkout(self)
-
-  set_permissions
-
-  run <<-CMD
-    rm -rf #{release_path}/log #{release_path}/public/system &&
-    ln -nfs #{shared_path}/log #{release_path}/log &&
-    ln -nfs #{shared_path}/system #{release_path}/public/system
-  CMD
-  
-  run <<-CMD
-    test -d #{shared_path}/pids && 
-    rm -rf #{release_path}/tmp/pids && 
-    ln -nfs #{shared_path}/pids #{release_path}/tmp/pids; true
-  CMD
-
-  # update the asset timestamps so they are in sync across all servers. This
-  # lets the asset timestamping feature of rails work correctly
-  stamp = Time.now.utc.strftime("%Y%m%d%H%M.%S")
-  asset_paths = %w(images stylesheets javascripts).map { |p| "#{release_path}/public/#{p}" }
-  run "TZ=UTC find #{asset_paths.join(" ")} -exec touch -t #{stamp} {} \\;; true"
-
-  # uncache the list of releases, so that the next time it is called it will
-  # include the newly released path.
-  @releases = nil
-end
-
-desc <<-DESC
-Rollback the latest checked-out version to the previous one by fixing the
-symlinks and deleting the current release from all servers.
-DESC
-task :rollback_code, :except => { :no_release => true } do
-  if releases.length < 2
-    raise "could not rollback the code because there is no prior release"
-  else
-    run <<-CMD
-      ln -nfs #{previous_release} #{current_path} &&
-      rm -rf #{current_release}
-    CMD
-  end
-end
-
-desc <<-DESC
-Update the 'current' symlink to point to the latest version of
-the application's code.
-DESC
-task :symlink, :except => { :no_release => true } do
-  on_rollback { run "ln -nfs #{previous_release} #{current_path}" }
-  run "ln -nfs #{current_release} #{current_path}"
-end
-
-desc <<-DESC
-Restart the FCGI processes on the app server. This uses the :use_sudo
-variable to determine whether to use sudo or not. By default, :use_sudo is
-set to true, but you can set it to false if you are in a shared environment.
-DESC
-task :restart, :roles => :app do
-  send(run_method, "#{current_path}/script/process/reaper")
-end
-
-desc <<-DESC
-Updates the code and fixes the symlink under a transaction
-DESC
-task :update do
-  transaction do
-    update_code
-    symlink
-  end
-end
-
 desc <<-DESC
-Run the migrate rake task. By default, it runs this in the version of the app
-indicated by the 'current' symlink. (This means you should not invoke this task
-until the symlink has been updated to the most recent version.) However, you
-can specify a different release via the migrate_target variable, which must be
-one of "current" (for the default behavior), or "latest" (for the latest release
-to be deployed with the update_code task). You can also specify additional
-environment variables to pass to rake via the migrate_env variable. Finally, you
-can specify the full path to the rake executable by setting the rake variable.
-DESC
-task :migrate, :roles => :db, :only => { :primary => true } do
-  directory = case migrate_target.to_sym
-    when :current then current_path
-    when :latest  then current_release
-    else
-      raise ArgumentError,
-        "you must specify one of current or latest for migrate_target"
-  end
+  Invoke a single command on the remote servers. This is useful for performing \
+  one-off commands that may not require a full task to be written for them. \
+  Simply specify the command to execute via the COMMAND environment variable. \
+  To execute the command only on certain roles, specify the ROLES environment \
+  variable as a comma-delimited list of role names. Alternatively, you can \
+  specify the HOSTS environment variable as a comma-delimited list of hostnames \
+  to execute the task on those hosts, explicitly. Lastly, if you want to \
+  execute the command via sudo, specify a non-empty value for the SUDO \
+  environment variable.
 
-  run "cd #{directory} && " +
-      "#{rake} RAILS_ENV=#{rails_env} #{migrate_env} db:migrate"
-end
-
-desc <<-DESC
-A macro-task that updates the code, fixes the symlink, and restarts the
-application servers.
-DESC
-task :deploy do
-  update
-  restart
-end
+  Sample usage:
 
-desc <<-DESC
-Similar to deploy, but it runs the migrate task on the new release before
-updating the symlink. (Note that the update in this case it is not atomic,
-and transactions are not used, because migrations are not guaranteed to be
-reversible.)
-DESC
-task :deploy_with_migrations do
-  update_code
-
-  begin
-    old_migrate_target = migrate_target
-    set :migrate_target, :latest
-    migrate
-  ensure
-    set :migrate_target, old_migrate_target
-  end
-
-  symlink
-
-  restart
-end
-
-desc "A macro-task that rolls back the code and restarts the application servers."
-task :rollback do
-  rollback_code
-  restart
-end
-
-desc <<-DESC
-Displays the diff between HEAD and what was last deployed. (Not available
-with all SCM's.)
+    $ cap COMMAND=uptime HOSTS=foo.capistano.test invoke
+    $ cap ROLES=app,web SUDO=1 COMMAND="tail -f /var/log/messages" invoke
 DESC
-task :diff_from_last_deploy do
-  diff = source.diff(self)
-  puts
-  puts diff
-  puts
-end
-
-desc "Update the currently released version of the software directly via an SCM update operation"
-task :update_current do
-  source.update(self)
-end
-
-desc <<-DESC
-Removes unused releases from the releases directory. By default, the last 5
-releases are retained, but this can be configured with the 'keep_releases'
-variable. This will use sudo to do the delete by default, but you can specify
-that run should be used by setting the :use_sudo variable to false.
-DESC
-task :cleanup, :except => { :no_release => true } do
-  count = (self[: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(" ")
-
-    send(run_method, "rm -rf #{directories}")
-  end
-end
-
-desc <<-DESC
-Start the spinner daemon for the application (requires script/spin). This will
-use sudo to start the spinner by default, unless :use_sudo is false. If using
-sudo, you can specify the user that the spinner ought to run as by setting the
-:spinner_user variable (defaults to :app).
-DESC
-task :spinner, :roles => :app do
-  user = (use_sudo && spinner_user) ? "-u #{spinner_user} " : ""
-  send(run_method, "#{user}#{current_path}/script/spin")
+task :invoke do
+  command = ENV["COMMAND"] || ""
+  abort "Please specify a command to execute on the remote servers (via the COMMAND environment variable)" if command.empty?
+  method = ENV["SUDO"] ? :sudo : :run
+  invoke_command(command, :via => method)
 end
 
 desc <<-DESC
-Used only for deploying when the spinner isn't running. It invokes 'update',
-and when it finishes it then invokes the spinner task (to start the spinner).
-DESC
-task :cold_deploy do
-  update
-  spinner
-end
+  Begin an interactive Capistrano session. This gives you an interactive \
+  terminal from which to execute tasks and commands on all of your servers. \
+  (This is still an experimental feature, and is subject to change without \
+  notice!)
 
-desc <<-DESC
-A simple task for performing one-off commands that may not require a full task
-to be written for them. Simply specify the command to execute via the COMMAND
-environment variable. To execute the command only on certain roles, specify
-the ROLES environment variable as a comma-delimited list of role names. Lastly,
-if you want to execute the command via sudo, specify a non-empty value for the
-SUDO environment variable.
-DESC
-task :invoke, :roles => Capistrano.str2roles(ENV["ROLES"] || "") do
-  method = ENV["SUDO"] ? :sudo : :run
-  send(method, ENV["COMMAND"])
-end
+  Sample usage:
 
-desc <<-DESC
-Begin an interactive Capistrano session. This gives you an interactive
-terminal from which to execute tasks and commands on all of your servers.
-(This is still an experimental feature, and is subject to change without
-notice!)
+    $ cap shell
 DESC
-task(:shell) do
+task :shell do
   require 'capistrano/shell'
-  Capistrano::Shell.run!(self)
-end
+  Capistrano::Shell.run(self)
+end