switchtower 0.9.0

data/lib/switchtower/gateway.rb

@@ -0,0 +1,106 @@
+require 'thread'
+require 'switchtower/ssh'
+
+Thread.abort_on_exception = true
+
+module SwitchTower
+
+  # 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 = SwitchTower::Configuration.new
+  #   gateway = SwitchTower::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
+
+    def initialize(server, config) #:nodoc:
+      @config = config
+      @pending_forward_requests = {}
+      @mutex = Mutex.new
+      @next_port = 31310
+      @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 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
+          @next_port += 1
+
+          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 Object
+            @pending_forward_requests[key] = nil
+            raise
+          ensure
+            var.signal
+          end
+        end
+      end
+  end
+end

data/lib/switchtower/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 "switchtower.rake", File.join("lib", "tasks", "switchtower.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/switchtower/generators/rails/deployment/templates/deploy.rb

@@ -0,0 +1,116 @@
+# This defines a deployment "recipe" that you can feed to switchtower
+# (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
+
+# =============================================================================
+# 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/switchtower/generators/rails/deployment/templates/switchtower.rake

@@ -0,0 +1,33 @@
+# =============================================================================
+# A set of rake tasks for invoking the SwitchTower automation utility.
+# =============================================================================
+
+desc "Push the latest revision into production using the release manager"
+task :deploy do
+  system "switchtower -vvvv -r config/<%= recipe_file %> -a deploy"
+end
+
+desc "Rollback to the release before the current release in production"
+task :rollback do
+  system "switchtower -vvvv -r config/<%= recipe_file %> -a rollback"
+end
+
+desc "Describe the differences between HEAD and the last production release"
+task :diff_from_last_deploy do
+  system "switchtower -vvvv -r config/<%= recipe_file %> -a diff_from_last_deploy"
+end
+
+desc "Enumerate all available deployment tasks"
+task :show_deploy_tasks do
+  system "switchtower -r config/<%= recipe_file %> -a show_tasks"
+end
+
+desc "Execute a specific action using the release manager"
+task :remote_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(",").map { |a| "-a #{a}" }.join(" ")
+  system "switchtower -vvvv -r config/<%= recipe_file %> #{actions}"
+end

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

@@ -0,0 +1,20 @@
+module SwitchTower
+  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(
+          :switchtower, 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/switchtower/logger.rb

@@ -0,0 +1,56 @@
+module SwitchTower
+  class Logger #:nodoc:
+    attr_accessor :level
+
+    IMPORTANT = 0
+    INFO      = 1
+    DEBUG     = 2
+    TRACE     = 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
+        if line_prefix
+          message.split(/\r?\n/).each do |line|
+            @device.print "[#{line_prefix}] #{line.strip}\n"
+          end
+        else
+          @device.puts message.strip
+        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/switchtower/recipes/standard.rb

@@ -0,0 +1,175 @@
+# 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 Rails spinner and reaper scripts are being used to manage the FCGI
+#   processes.
+# * There is a script in script/ called "reap" that restarts the FCGI processes
+
+set :rake, "rake"
+
+desc "Enumerate and describe every available task."
+task :show_tasks do
+  keys = tasks.keys.sort_by { |a| a.to_s }
+  longest = keys.inject(0) { |len,key| key.to_s.length > len ? key.to_s.length : len } + 2
+
+  puts "Available tasks"
+  puts "---------------"
+  tasks.keys.sort_by { |a| a.to_s }.each do |key|
+    desc = (tasks[key].options[:desc] || "").strip.split(/\r?\n/)
+    puts "%-#{longest}s %s" % [key, desc.shift]
+    puts "%#{longest}s %s" % ["", desc.shift] until desc.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 "Restart the FCGI processes on the app server."
+task :restart, :roles => :app do
+  sudo "#{current_path}/script/process/reaper"
+end
+
+set :migrate_target, :current
+set :migrate_env, ""
+
+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=production #{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 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