capistrano 1.1.0

data/lib/capistrano/extensions.rb

@@ -0,0 +1,38 @@
+require 'capistrano/actor'
+
+module Capistrano
+  class ExtensionProxy
+    def initialize(actor, mod)
+      @actor = actor
+      extend(mod)
+    end
+
+    def method_missing(sym, *args, &block)
+      @actor.send(sym, *args, &block)
+    end
+  end
+
+  EXTENSIONS = {}
+
+  def self.plugin(name, mod)
+    return false if EXTENSIONS.has_key?(name)
+
+    Capistrano::Actor.class_eval <<-STR, __FILE__, __LINE__+1
+      def #{name}
+        @__#{name}_proxy ||= Capistrano::ExtensionProxy.new(self, Capistrano::EXTENSIONS[#{name.inspect}])
+      end
+    STR
+
+    EXTENSIONS[name] = mod
+    return true
+  end
+
+  def self.remove_plugin(name)
+    if EXTENSIONS.delete(name)
+      Capistrano::Actor.send(:remove_method, name)
+      return true
+    end
+
+    return false
+  end
+end

data/lib/capistrano/gateway.rb

@@ -0,0 +1,118 @@
+require 'thread'
+require 'capistrano/ssh'
+
+Thread.abort_on_exception = true
+
+module Capistrano
+
+  # Black magic. It uses threads and Net::SSH to set up a connection to a
+  # gateway server, through which connections to other servers may be
+  # tunnelled.
+  #
+  # It is used internally by Actor, but may be useful on its own, as well.
+  #
+  # Usage:
+  #
+  #   config = Capistrano::Configuration.new
+  #   gateway = Capistrano::Gateway.new('gateway.example.com', config)
+  #
+  #   sess1 = gateway.connect_to('hidden.example.com')
+  #   sess2 = gateway.connect_to('other.example.com')
+  class Gateway
+    # The thread inside which the gateway connection itself is running.
+    attr_reader :thread
+
+    # The Net::SSH session representing the gateway connection.
+    attr_reader :session
+
+    MAX_PORT = 65535
+    MIN_PORT = 1024
+
+    def initialize(server, config) #:nodoc:
+      @config = config
+      @pending_forward_requests = {}
+      @mutex = Mutex.new
+      @next_port = MAX_PORT
+      @terminate_thread = false
+
+      waiter = ConditionVariable.new
+
+      @thread = Thread.new do
+        @config.logger.trace "starting connection to gateway #{server}"
+        SSH.connect(server, @config) do |@session|
+          @config.logger.trace "gateway connection established"
+          @mutex.synchronize { waiter.signal }
+          connection = @session.registry[:connection][:driver]
+          loop do
+            break if @terminate_thread
+            sleep 0.1 unless connection.reader_ready?
+            connection.process true
+            Thread.new { process_next_pending_connection_request }
+          end
+        end
+      end
+
+      @mutex.synchronize { waiter.wait(@mutex) }
+    end
+
+    # Shuts down all forwarded connections and terminates the gateway.
+    def shutdown!
+      # cancel all active forward channels
+      @session.forward.active_locals.each do |lport, host, port|
+        @session.forward.cancel_local(lport)
+      end
+
+      # terminate the gateway thread
+      @terminate_thread = true
+
+      # wait for the gateway thread to stop
+      @thread.join
+    end
+
+    # Connects to the given server by opening a forwarded port from the local
+    # host to the server, via the gateway, and then opens and returns a new
+    # Net::SSH connection via that port.
+    def connect_to(server)
+      @mutex.synchronize do
+        @pending_forward_requests[server] = ConditionVariable.new
+        @pending_forward_requests[server].wait(@mutex)
+        @pending_forward_requests.delete(server)
+      end
+    end
+
+    private
+
+      def next_port
+        port = @next_port
+        @next_port -= 1
+        @next_port = MAX_PORT if @next_port < MIN_PORT
+        port
+      end
+
+      def process_next_pending_connection_request
+        @mutex.synchronize do
+          key = @pending_forward_requests.keys.detect { |k| ConditionVariable === @pending_forward_requests[k] } or return
+          var = @pending_forward_requests[key]
+
+          @config.logger.trace "establishing connection to #{key} via gateway"
+
+          port = next_port
+
+          begin
+            @session.forward.local(port, key, 22)
+            @pending_forward_requests[key] = SSH.connect('127.0.0.1', @config,
+              port)
+            @config.logger.trace "connection to #{key} via gateway established"
+          rescue Errno::EADDRINUSE
+            port = next_port
+            retry
+          rescue Object
+            @pending_forward_requests[key] = nil
+            raise
+          ensure
+            var.signal
+          end
+        end
+      end
+  end
+end

data/lib/capistrano/generators/rails/deployment/deployment_generator.rb

@@ -0,0 +1,25 @@
+class DeploymentGenerator < Rails::Generator::NamedBase
+  attr_reader :recipe_file
+
+  def initialize(runtime_args, runtime_options = {})
+    super
+    @recipe_file = @args.shift || "deploy"
+  end
+
+  def manifest
+    record do |m|
+      m.directory "config"
+      m.template "deploy.rb", File.join("config", "#{recipe_file}.rb")
+      m.directory "lib/tasks"
+      m.template "capistrano.rake", File.join("lib", "tasks", "capistrano.rake")
+    end
+  end
+
+  protected
+
+    # Override with your own usage banner.
+    def banner
+      "Usage: #{$0} deployment ApplicationName [recipe-name]\n" +
+      "  (recipe-name defaults to \"deploy\")"
+    end
+end

data/lib/capistrano/generators/rails/deployment/templates/capistrano.rake

@@ -0,0 +1,46 @@
+# =============================================================================
+# A set of rake tasks for invoking the Capistrano automation utility.
+# =============================================================================
+
+# Invoke the given actions via Capistrano
+def cap(*parameters)
+  begin
+    require 'rubygems'
+  rescue LoadError
+    # no rubygems to load, so we fail silently
+  end
+
+  require 'capistrano/cli'
+
+  Capistrano::CLI.new(parameters.map { |param| param.to_s }).execute!
+end
+
+namespace :remote do
+<%- config = Capistrano::Configuration.new
+    config.load "standard"
+    options = { :show_tasks => ", '-q'" }
+    config.actor.each_task do |info| -%>
+<%- unless info[:desc].empty? -%>
+  desc "<%= info[:desc].scan(/.*?(?:\. |$)/).first.strip.gsub(/"/, "\\\"") %>"
+<%- end -%>
+  task(<%= info[:task].inspect %>) { cap <%= info[:task].inspect %><%= options[info[:task]] %> }
+
+<%- end -%>
+  desc "Execute a specific action using capistrano"
+  task :exec do
+    unless ENV['ACTION']
+      raise "Please specify an action (or comma separated list of actions) via the ACTION environment variable"
+    end
+
+    actions = ENV['ACTION'].split(",")
+    actions.concat(ENV['PARAMS'].split(" ")) if ENV['PARAMS']
+
+    cap(*actions)
+  end
+end
+
+desc "Push the latest revision into production (delegates to remote:deploy)"
+task :deploy => "remote:deploy"
+
+desc "Rollback to the release before the current release in production (delegates to remote:rollback)"
+task :rollback => "remote:rollback"

data/lib/capistrano/generators/rails/deployment/templates/deploy.rb

@@ -0,0 +1,122 @@
+# This defines a deployment "recipe" that you can feed to capistrano
+# (http://manuals.rubyonrails.com/read/book/17). It allows you to automate
+# (among other things) the deployment of your application.
+
+# =============================================================================
+# REQUIRED VARIABLES
+# =============================================================================
+# 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 :application, "<%= singular_name %>"
+set :repository, "http://svn.yourhost.com/#{application}/trunk"
+
+# =============================================================================
+# ROLES
+# =============================================================================
+# 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"
+
+# =============================================================================
+# OPTIONAL VARIABLES
+# =============================================================================
+# set :deploy_to, "/path/to/app" # defaults to "/u/apps/#{application}"
+# set :user, "flippy"            # defaults to the currently logged in user
+# set :scm, :darcs               # defaults to :subversion
+# set :svn, "/path/to/svn"       # defaults to searching the PATH
+# set :darcs, "/path/to/darcs"   # defaults to searching the PATH
+# set :cvs, "/path/to/cvs"       # defaults to searching the PATH
+# set :gateway, "gate.host.com"  # default to no gateway
+
+# =============================================================================
+# SSH OPTIONS
+# =============================================================================
+# ssh_options[:keys] = %w(/path/to/my/key /path/to/another/key)
+# ssh_options[:port] = 25
+
+# =============================================================================
+# TASKS
+# =============================================================================
+# 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
+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
+end

data/lib/capistrano/generators/rails/loader.rb

@@ -0,0 +1,20 @@
+module Capistrano
+  module Generators
+    class RailsLoader
+      def self.load!(options)
+        require "#{options[:apply_to]}/config/environment"
+        require "rails_generator"
+        require "rails_generator/scripts/generate"
+
+        Rails::Generator::Base.sources << Rails::Generator::PathSource.new(
+          :capistrano, File.dirname(__FILE__))
+
+        args = ["deployment"]
+        args << (options[:application] || "Application")
+        args << (options[:recipe_file] || "deploy")
+
+        Rails::Generator::Scripts::Generate.new.run(args)
+      end
+    end
+  end
+end

data/lib/capistrano/logger.rb

@@ -0,0 +1,59 @@
+module Capistrano
+  class Logger #:nodoc:
+    attr_accessor :level
+
+    IMPORTANT = 0
+    INFO      = 1
+    DEBUG     = 2
+    TRACE     = 3
+    
+    MAX_LEVEL = 3
+
+    def initialize(options={})
+      output = options[:output] || STDERR
+      case
+        when output.respond_to?(:puts)
+          @device = output
+        else
+          @device = File.open(output.to_str, "a")
+          @needs_close = true
+      end
+
+      @options = options
+      @level = 0
+    end
+
+    def close
+      @device.close if @needs_close
+    end
+
+    def log(level, message, line_prefix=nil)
+      if level <= self.level
+        indent = "%*s" % [MAX_LEVEL, "*" * (MAX_LEVEL - level)]
+        message.split(/\r?\n/).each do |line|
+          if line_prefix
+            @device.print "#{indent} [#{line_prefix}] #{line.strip}\n"
+          else
+            @device.puts "#{indent} #{line.strip}\n"
+          end
+        end
+      end
+    end
+
+    def important(message, line_prefix=nil)
+      log(IMPORTANT, message, line_prefix)
+    end
+
+    def info(message, line_prefix=nil)
+      log(INFO, message, line_prefix)
+    end
+
+    def debug(message, line_prefix=nil)
+      log(DEBUG, message, line_prefix)
+    end
+
+    def trace(message, line_prefix=nil)
+      log(TRACE, message, line_prefix)
+    end
+  end
+end

data/lib/capistrano/recipes/standard.rb

@@ -0,0 +1,242 @@
+# 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]
+    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, :roles => [:app, :db, :web] do
+  run <<-CMD
+    mkdir -p -m 775 #{releases_path} #{shared_path}/system &&
+    mkdir -p -m 777 #{shared_path}/log
+  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
+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, :roles => [:app, :db, :web] do
+  on_rollback { delete release_path, :recursive => true }
+
+  source.checkout(self)
+
+  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
+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, :roles => [:app, :db, :web] 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, :roles => [:app, :db, :web] 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
+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
+
+  run "cd #{directory} && " +
+      "#{rake} RAILS_ENV=#{rails_env} #{migrate_env} migrate"
+end
+
+desc <<-DESC
+A macro-task that updates the code, fixes the symlink, and restarts the
+application servers.
+DESC
+task :deploy do
+  transaction do
+    update_code
+    symlink
+  end
+
+  restart
+end
+
+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.)
+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 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")
+end
+
+desc <<-DESC
+Used only for deploying when the spinner isn't running. It invokes deploy,
+and when it finishes it then invokes the spinner task (to start the spinner).
+DESC
+task :cold_deploy do
+  deploy
+  spinner
+end
+
+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