@@ -1,4 +1,4 @@ -Copyright (c) 2005,2006 Jamis Buck +Copyright (c) 2005-2007 Jamis Buck <jamis@37signals.com> Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the MIT-LICENSE @@ -2,34 +2,36 @@ Capistrano 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. -Capistrano 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). +Capistrano was originally designed to simplify and automate deployment of web applications to distributed environments, and originally came bundled with a set of tasks designed for deploying Rails applications. The deployment tasks are now (as of Capistrano 2.0) distributed as a separate package: capistrano-deploy. == Dependencies -Capistrano depends upon the Net::SSH library by Jamis Buck (http://net-ssh.rubyforge.org). Net::SSH itself depends on the Needle library (http://needle.rubyforge.org), also by Jamis Buck. +* Net::SSH and Net::SFTP (http://net-ssh.rubyforge.org) +* Needle (via Net::SSH) +* HighLine (http://highline.rubyforge.org) + +If you want to run the tests, you'll also need to have the following dependencies installed: + +* Mocha (http://mocha.rubyforge.org) == Assumptions -In keeping with Rails' "convention over configuration", Capistrano makes several assumptions about how you will use it (most, if not all, of which may be explicitly overridden): +Capistrano is "opinionated software", which means it has very firm ideas about how things ought to be done, and tries to force those ideas on you. Some of the assumptions behind these opinions are: -* You are writing web applications and want to use Capistrano 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. +* You are using SSH to access the remote servers. +* You either have the same password to all target machines, or you have public keys in place to allow passwordless access to them. -As with the rest of Rails, if you can abide by these assumptions, you can use Capistrano "out of the box". If any of these assumptions do not hold, you'll need to make some adjustments to your deployment recipe files. +Do not expect these assumptions to change. == Usage -More documentation is always pending, but you'll want to see the user manual for detailed usage instructions. (The manual is online at http://manuals.rubyonrails.org/read/book/17). - In general, you'll use Capistrano 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 +cap+ script to execute your recipe (see below). +* Create a recipe file ("capfile" or "Capfile"). +* Use the +cap+ script to execute your recipe. Use the +cap+ script as follows: - cap -vvv someaction + cap sometask -By default, the script will look for a file called one of <tt>config/deploy</tt>, <tt>config/deploy.rb</tt>, <tt>capistrano</tt>, or <tt>capistrano.rb</tt>. You can the <tt>-v</tt> switch multiple times (as shown) to increase the verbosity of the output. The +someaction+ text indicates which action to execute. +By default, the script will look for a file called one of +capfile+ or +Capfile+. The +someaction+ text indicates which task to execute. You can do "cap -h" to see all the available options and "cap -T" to see all the available tasks. README @@ -6,7 +6,7 @@ Gem::Specification.new do |s| s.version = PKG_VERSION s.platform = Gem::Platform::RUBY s.summary = <<-DESC.strip.gsub(/\n\s+/, " ") - Capistrano is a framework and utility for executing commands in parallel + Capistrano is a utility and framework for executing commands in parallel on multiple remote machines, via SSH. DESC capistrano.gemspec @@ -1,113 +1,14 @@ -# 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 :user, "flippy" +# set :password, "hello-flippy" +# set :gateway, "gateway.example.com" -set :application, "sample" -set :repository, "http://svn.example.com/#{application}/trunk" +role :web, "web1.example.com" +role :app, "app1.example.com", "app2.example.com" -# 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 <<-DESC +This is a sample task. It is only intended to be used as a demonstration of \ +how you can define your own 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 +task :sample_task, :roles => :app do + run "ls -l" end examples/sample.rb THANKS c0e2ee20f9ed0d7cb3a5466d1ebcf55dd41891b6 Jamis Buck jamis@37signals.com http://github.com/jamis/capistrano/commit/414da791d23ee9184d473533843a41919e059db0 414da791d23ee9184d473533843a41919e059db0 2007-03-04T14:25:51-08:00 2007-03-04T14:25:51-08:00 THANKS file is not applicable anymore. Bring various other files up-to-date with reality. git-svn-id: http://svn.rubyonrails.org/rails/tools/capistrano@6326 5ecf4fe2-1ee6-0310-87b1-e25e094e27de c5bc8d7fa38da582d0bd94fc951ac0b1da53dd9b Jamis Buck jamis@37signals.com