Permalink
Browse files

Initial commit of the new switchtower utility

git-svn-id: http://svn.rubyonrails.org/rails/trunk/switchtower@1967 5ecf4fe2-1ee6-0310-87b1-e25e094e27de
  • Loading branch information...
0 parents commit f9da6dbb4ca3c52bb826653b3313e64541f7f693 @jamis jamis committed Aug 3, 2005
@@ -0,0 +1,20 @@
+Copyright (c) 2005 Jamis Buck
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
29 README
@@ -0,0 +1,29 @@
+= SwitchTower
+
+SwitchTower 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.
+
+SwitchTower 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).
+
+== Assumptions
+
+In keeping with Rails' "convention over configuration", SwitchTower makes several assumptions about how you will use it (most, if not all, of which may be explicitly overridden):
+
+* You are writing web applications and want to use SwitchTower 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.
+
+As with the rest of Rails, if you can abide by these assumptions, you can use SwitchTower "out of the box". If any of these assumptions do not hold, you'll need to make some adjustments to your deployment recipe files.
+
+== Usage
+
+More documentation is always pending, but you'll want to see the user manual for detailed usage instructions. In general, you'll use SwitchTower 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 +switchtower+ script to execute your recipe (see below).
+
+Use the +switchtower+ script as follows:
+
+ switchtower -r deploy -a someaction -vvvv
+
+The <tt>-r</tt> switch specifies the recipe to use, and the <tt>-a</tt> switch specifies which action you want to execute. You can the <tt>-v</tt> switch multiple times (as shown) to increase the verbosity of the output.
@@ -0,0 +1,38 @@
+require 'rake'
+require 'rake/testtask'
+require 'rake/rdoctask'
+require 'rake/gempackagetask'
+
+require "./lib/switchtower/version"
+
+SOFTWARE_NAME = "switchtower"
+SOFTWARE_VERSION = SwitchTower::Version::STRING
+
+desc "Default task"
+task :default => [ :test ]
+
+desc "Build documentation"
+task :doc => [ :rdoc ]
+
+Rake::TestTask.new do |t|
+ t.test_files = Dir["test/*_test.rb"]
+ t.verbose = true
+end
+
+GEM_SPEC = eval(File.read("#{File.dirname(__FILE__)}/#{SOFTWARE_NAME}.gemspec"))
+
+Rake::GemPackageTask.new(GEM_SPEC) do |p|
+ p.gem_spec = GEM_SPEC
+ p.need_tar = true
+ p.need_zip = true
+end
+
+desc "Build the RDoc API documentation"
+Rake::RDocTask.new do |rdoc|
+ rdoc.rdoc_dir = "doc"
+ rdoc.title = "SwitchTower -- A framework for remote command execution"
+ rdoc.options << '--line-numbers --inline-source --main README'
+ rdoc.rdoc_files.include 'README'
+ rdoc.rdoc_files.include 'lib/**/*.rb'
+ rdoc.template = "jamis"
+end
@@ -0,0 +1,109 @@
+#!/usr/bin/env ruby
+
+require 'optparse'
+require 'switchtower'
+
+begin
+ if !defined?(USE_TERMIOS) || USE_TERMIOS
+ require 'termios'
+ else
+ raise LoadError
+ end
+
+ # Enable or disable stdin echoing to the terminal.
+ def echo(enable)
+ term = Termios::getattr(STDIN)
+
+ if enable
+ term.c_lflag |= (Termios::ECHO | Termios::ICANON)
+ else
+ term.c_lflag &= ~Termios::ECHO
+ end
+
+ Termios::setattr(STDIN, Termios::TCSANOW, term)
+ end
+rescue LoadError
+ def echo(enable)
+ end
+end
+
+options = { :verbose => 0, :recipes => [], :actions => [] }
+
+OptionParser.new do |opts|
+ opts.banner = "Usage: #{$0} [options]"
+ opts.separator ""
+
+ opts.on("-a", "--action ACTION",
+ "An action to execute. Multiple actions may",
+ "be specified, and are loaded in the given order."
+ ) { |value| options[:actions] << value }
+
+ opts.on("-p", "--password PASSWORD",
+ "The password to use when connecting.",
+ "(Default: prompt for password)"
+ ) { |value| options[:password] = value }
+
+ opts.on("-P", "--[no-]pretend",
+ "Run the task(s), but don't actually connect to or",
+ "execute anything on the servers. (For various reasons",
+ "this will not necessarily be an accurate depiction",
+ "of the work that will actually be performed.",
+ "Default: don't pretend.)"
+ ) { |value| options[:pretend] = value }
+
+ opts.on("-r", "--recipe RECIPE",
+ "A recipe file to load. Multiple recipes may",
+ "be specified, and are loaded in the given order."
+ ) { |value| options[:recipes] << value }
+
+ opts.on("-v", "--verbose",
+ "Specify the verbosity of the output.",
+ "May be given multiple times. (Default: silent)"
+ ) { options[:verbose] += 1 }
+
+ opts.separator ""
+ opts.on_tail("-h", "--help", "Display this help message") do
+ puts opts
+ exit
+ end
+ opts.on_tail("-V", "--version",
+ "Display the version info for this utility"
+ ) do
+ require 'switchtower/version'
+ puts "Release Manager v#{SwitchTower::Version::STRING}"
+ exit
+ end
+
+ opts.parse!
+end
+
+abort "You must specify at least one recipe" if options[:recipes].empty?
+abort "You must specify at least one action" if options[:actions].empty?
+
+unless options.has_key?(:password)
+ options[:password] = Proc.new do
+ sync = STDOUT.sync
+ begin
+ echo false
+ STDOUT.sync = true
+ print "Password: "
+ STDIN.gets.chomp
+ ensure
+ echo true
+ STDOUT.sync = sync
+ puts
+ end
+ end
+end
+
+config = SwitchTower::Configuration.new
+config.logger.level = options[:verbose]
+config.set :password, options[:password]
+config.set :pretend, options[:pretend]
+
+config.load "standard" # load the standard recipe definition
+
+options[:recipes].each { |recipe| config.load(recipe) }
+
+actor = config.actor
+options[:actions].each { |action| actor.send action }
@@ -0,0 +1,113 @@
+# 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, "sample"
+set :repository, "http://svn.example.com/#{application}/trunk"
+
+# 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
+
+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
@@ -0,0 +1 @@
+require 'switchtower/configuration'
Oops, something went wrong.

0 comments on commit f9da6db

Please sign in to comment.