Fetching contributors…
Cannot retrieve contributors at this time
622 lines (536 sloc) 24.2 KB
require 'benchmark'
require 'yaml'
require 'capistrano/recipes/deploy/scm'
require 'capistrano/recipes/deploy/strategy'
def _cset(name, *args, &block)
unless exists?(name)
set(name, *args, &block)
# =========================================================================
# These variables MUST be set in the client capfiles. If they are not set,
# the deploy will fail with an error.
# =========================================================================
_cset(:application) { abort "Please specify the name of your application, set :application, 'foo'" }
_cset(:repository) { abort "Please specify the repository that houses your application's code, set :repository, 'foo'" }
# =========================================================================
# These variables may be set in the client capfile if their default values
# are not sufficient.
# =========================================================================
_cset :scm, scm_default
_cset :deploy_via, :checkout
_cset(:deploy_to) { "/u/apps/#{application}" }
_cset(:revision) { source.head }
_cset :rails_env, "production"
_cset :rake, "rake"
_cset :maintenance_basename, "maintenance"
_cset(:maintenance_template_path) { File.join(File.dirname(__FILE__), "templates", "maintenance.rhtml") }
# =========================================================================
# These variables should NOT be changed unless you are very confident in
# what you are doing. Make sure you understand all the implications of your
# changes if you do decide to muck with these!
# =========================================================================
_cset(:source) {, self) }
_cset(:real_revision) { source.local.query_revision(revision) { |cmd| with_env("LC_ALL", "C") { run_locally(cmd) } } }
_cset(:strategy) {, self) }
# If overriding release name, please also select an appropriate setting for :releases below.
_cset(:release_name) { set :deploy_timestamped, true;"%Y%m%d%H%M%S") }
_cset :version_dir, "releases"
_cset :shared_dir, "shared"
_cset :shared_children, %w(public/system log tmp/pids)
_cset :current_dir, "current"
_cset(:releases_path) { File.join(deploy_to, version_dir) }
_cset(:shared_path) { File.join(deploy_to, shared_dir) }
_cset(:current_path) { File.join(deploy_to, current_dir) }
_cset(:release_path) { File.join(releases_path, release_name) }
_cset(:releases) { capture("ls -x #{releases_path}", :except => { :no_release => true }).split.sort }
_cset(:current_release) { releases.length > 0 ? File.join(releases_path, releases.last) : nil }
_cset(:previous_release) { releases.length > 1 ? File.join(releases_path, releases[-2]) : nil }
_cset(:current_revision) { capture("cat #{current_path}/REVISION", :except => { :no_release => true }).chomp }
_cset(:latest_revision) { capture("cat #{current_release}/REVISION", :except => { :no_release => true }).chomp }
_cset(:previous_revision) { capture("cat #{previous_release}/REVISION", :except => { :no_release => true }).chomp if previous_release }
_cset(:run_method) { fetch(:use_sudo, true) ? :sudo : :run }
# some tasks, like symlink, need to always point at the latest release, but
# they can also (occassionally) be called standalone. In the standalone case,
# the timestamped release_path will be inaccurate, since the directory won't
# actually exist. This variable lets tasks like symlink work either in the
# standalone case, or during deployment.
_cset(:latest_release) { exists?(:deploy_timestamped) ? release_path : current_release }
# =========================================================================
# These are helper methods that will be available to your recipes.
# =========================================================================
# Checks known version control directories to intelligently set the version
# control in-use. For example, if a .svn directory exists in the project,
# it will set the :scm variable to :subversion, if a .git directory exists
# in the project, it will set the :scm variable to :git and so on. If no
# directory is found, it will default to :git.
def scm_default
if File.exist? '.git'
elsif File.exist? '.accurev'
elsif File.exist? '.bzr'
elsif File.exist? '.cvs'
elsif File.exist? '_darcs'
elsif File.exist? '.hg'
elsif File.exist? '.perforce'
elsif File.exist? '.svn'
# Auxiliary helper method for the `deploy:check' task. Lets you set up your
# own dependencies.
def depend(location, type, *args)
deps = fetch(:dependencies, {})
deps[location] ||= {}
deps[location][type] ||= []
deps[location][type] << args
set :dependencies, deps
# Temporarily sets an environment variable, yields to a block, and restores
# the value when it is done.
def with_env(name, value)
saved, ENV[name] = ENV[name], value
ENV[name] = saved
# logs the command then executes it locally.
# returns the command output as a string
def run_locally(cmd)
logger.trace "executing locally: #{cmd.inspect}" if logger
output_on_stdout = nil
elapsed = Benchmark.realtime do
output_on_stdout = `#{cmd}`
if $?.to_i > 0 # $? is command exit code (posix style)
raise Capistrano::LocalArgumentError, "Command #{cmd} returned status code #{$?}"
logger.trace "command finished in #{(elapsed * 1000).round}ms" if logger
# If a command is given, this will try to execute the given command, as
# described below. Otherwise, it will return a string for use in embedding in
# another command, for executing that command as described below.
# If :run_method is :sudo (or :use_sudo is true), this executes the given command
# via +sudo+. Otherwise is uses +run+. If :as is given as a key, it will be
# passed as the user to sudo as, if using sudo. If the :as key is not given,
# it will default to whatever the value of the :admin_runner variable is,
# which (by default) is unset.
# THUS, if you want to try to run something via sudo, and what to use the
# root user, you'd just to try_sudo('something'). If you wanted to try_sudo as
# someone else, you'd just do try_sudo('something', :as => "bob"). If you
# always wanted sudo to run as a particular user, you could do
# set(:admin_runner, "bob").
def try_sudo(*args)
options = args.last.is_a?(Hash) ? args.pop : {}
command = args.shift
raise ArgumentError, "too many arguments" if args.any?
as = options.fetch(:as, fetch(:admin_runner, nil))
via = fetch(:run_method, :sudo)
if command
invoke_command(command, :via => via, :as => as)
elsif via == :sudo
sudo(:as => as)
# Same as sudo, but tries sudo with :as set to the value of the :runner
# variable (which defaults to "app").
def try_runner(*args)
options = args.last.is_a?(Hash) ? args.pop : {}
args << options.merge(:as => fetch(:runner, "app"))
# =========================================================================
# These are the tasks that are available to help with deploying web apps,
# and specifically, Rails applications. You can have cap give you a summary
# of them with `cap -T'.
# =========================================================================
namespace :deploy do
desc <<-DESC
Deploys your project. This calls both `update' and `restart'. Note that \
this will generally only work for applications that have already been deployed \
once. For a "cold" deploy, you'll want to take a look at the `deploy:cold' \
task, which handles the cold start specifically.
task :default do
desc <<-DESC
Prepares one or more servers for deployment. Before you can use any \
of the Capistrano deployment tasks with your project, you will need to \
make sure all of your servers have been prepared with `cap deploy:setup'. When \
you add a new server to your cluster, you can easily run the setup task \
on just that server by specifying the HOSTS environment variable:
$ cap deploy:setup
It is safe to run this task on servers that have already been set up; it \
will not destroy any deployed revisions or data.
task :setup, :except => { :no_release => true } do
dirs = [deploy_to, releases_path, shared_path]
dirs += { |d| File.join(shared_path, d.split('/').last) }
run "#{try_sudo} mkdir -p #{dirs.join(' ')}"
run "#{try_sudo} chmod g+w #{dirs.join(' ')}" if fetch(:group_writable, true)
desc <<-DESC
Copies your project and updates the symlink. It does this in a \
transaction, so that if either `update_code' or `symlink' fail, all \
changes made to the remote servers will be rolled back, leaving your \
system in the same state it was in before `update' was invoked. Usually, \
you will want to call `deploy' instead of `update', but `update' can be \
handy if you want to deploy, but not immediately restart your application.
task :update do
transaction do
desc <<-DESC
Copies your project to the remote servers. This is the first stage \
of any deployment; moving your updated code and assets to the deployment \
servers. You will rarely call this task directly, however; instead, you \
should call the `deploy' task (to do a complete deploy) or the `update' \
task (if you want to perform the `restart' task separately).
You will need to make sure you set the :scm variable to the source \
control software you are using (it defaults to :subversion), and the \
:deploy_via variable to the strategy you want to use to deploy (it \
defaults to :checkout).
task :update_code, :except => { :no_release => true } do
on_rollback { run "rm -rf #{release_path}; true" }
desc <<-DESC
[internal] Touches up the released code. This is called by update_code \
after the basic deploy finishes. It assumes a Rails project was deployed, \
so if you are deploying something else, you may want to override this \
task with your own environment's requirements.
This task will make the release group-writable (if the :group_writable \
variable is set to true, which is the default). It will then set up \
symlinks to the shared directory for the log, system, and tmp/pids \
directories, and will lastly touch all assets in public/images, \
public/stylesheets, and public/javascripts so that the times are \
consistent (so that asset timestamping works). This touch process \
is only carried out if the :normalize_asset_timestamps variable is \
set to true, which is the default The asset directories can be overridden \
using the :public_children variable.
task :finalize_update, :except => { :no_release => true } do
run "chmod -R g+w #{latest_release}" if fetch(:group_writable, true)
# mkdir -p is making sure that the directories are there for some SCM's that don't
# save empty folders do |d|
if (d.rindex('/')) then
run "rm -rf #{latest_release}/#{d} && mkdir -p #{latest_release}/#{d.slice(0..(d.rindex('/')))}"
run "rm -rf #{latest_release}/#{d}"
run "ln -s #{shared_path}/#{d.split('/').last} #{latest_release}/#{d}"
if fetch(:normalize_asset_timestamps, true)
stamp ="%Y%m%d%H%M.%S")
asset_paths = fetch(:public_children, %w(images stylesheets javascripts)).map { |p| "#{latest_release}/public/#{p}" }.join(" ")
run "find #{asset_paths} -exec touch -t #{stamp} {} ';'; true", :env => { "TZ" => "UTC" }
desc <<-DESC
Deprecated API. This has become deploy:create_symlink, please update your recipes
task :symlink, :except => { :no_release => true } do
Kernel.warn "[Deprecation Warning] This API has changed, please hook `deploy:create_symlink` instead of `deploy:symlink`."
desc <<-DESC
Updates the symlink to the most recently deployed version. Capistrano works \
by putting each new release of your application in its own directory. When \
you deploy a new version, this task's job is to update the `current' symlink \
to point at the new version. You will rarely need to call this task \
directly; instead, use the `deploy' task (which performs a complete \
deploy, including `restart') or the 'update' task (which does everything \
except `restart').
task :create_symlink, :except => { :no_release => true } do
on_rollback do
if previous_release
run "rm -f #{current_path}; ln -s #{previous_release} #{current_path}; true"
logger.important "no previous release to rollback to, rollback of symlink skipped"
run "rm -f #{current_path} && ln -s #{latest_release} #{current_path}"
desc <<-DESC
Copy files to the currently deployed version. This is useful for updating \
files piecemeal, such as when you need to quickly deploy only a single \
file. Some files, such as updated templates, images, or stylesheets, \
might not require a full deploy, and especially in emergency situations \
it can be handy to just push the updates to production, quickly.
To use this task, specify the files and directories you want to copy as a \
comma-delimited list in the FILES environment variable. All directories \
will be processed recursively, with all files being pushed to the \
deployment servers.
$ cap deploy:upload FILES=templates,controller.rb
Dir globs are also supported:
$ cap deploy:upload FILES='config/apache/*.conf'
task :upload, :except => { :no_release => true } do
files = (ENV["FILES"] || "").split(",").map { |f| Dir[f.strip] }.flatten
abort "Please specify at least one file or directory to update (via the FILES environment variable)" if files.empty?
files.each { |file| top.upload(file, File.join(current_path, file)) }
desc <<-DESC
Blank task exists as a hook into which to install your own environment \
specific behaviour.
task :restart, :roles => :app, :except => { :no_release => true } do
# Empty Task to overload with your platform specifics
namespace :rollback do
desc <<-DESC
[internal] Points the current symlink at the previous revision.
This is called by the rollback sequence, and should rarely (if
ever) need to be called directly.
task :revision, :except => { :no_release => true } do
if previous_release
run "rm #{current_path}; ln -s #{previous_release} #{current_path}"
abort "could not rollback the code because there is no prior release"
desc <<-DESC
[internal] Removes the most recently deployed release.
This is called by the rollback sequence, and should rarely
(if ever) need to be called directly.
task :cleanup, :except => { :no_release => true } do
run "if [ `readlink #{current_path}` != #{current_release} ]; then rm -rf #{current_release}; fi"
desc <<-DESC
Rolls back to the previously deployed version. The `current' symlink will \
be updated to point at the previously deployed version, and then the \
current release will be removed from the servers. You'll generally want \
to call `rollback' instead, as it performs a `restart' as well.
task :code, :except => { :no_release => true } do
desc <<-DESC
Rolls back to a previous version and restarts. This is handy if you ever \
discover that you've deployed a lemon; `cap rollback' and you're right \
back where you were, on the previously deployed version.
task :default do
desc <<-DESC
Run the migrate rake task. By default, it runs this in most recently \
deployed version of the app. However, you can specify a different release \
via the migrate_target variable, which must be one of :latest (for the \
default behavior), or :current (for the release indicated by the \
`current' symlink). Strings will work for those values instead of symbols, \
too. 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. The defaults are:
set :rake, "rake"
set :rails_env, "production"
set :migrate_env, ""
set :migrate_target, :latest
task :migrate, :roles => :db, :only => { :primary => true } do
rake = fetch(:rake, "rake")
rails_env = fetch(:rails_env, "production")
migrate_env = fetch(:migrate_env, "")
migrate_target = fetch(:migrate_target, :latest)
directory = case migrate_target.to_sym
when :current then current_path
when :latest then latest_release
else raise ArgumentError, "unknown migration target #{migrate_target.inspect}"
run "cd #{directory} && #{rake} RAILS_ENV=#{rails_env} #{migrate_env} db:migrate"
desc <<-DESC
Deploy and run pending migrations. This will work similarly to the \
`deploy' task, but will also run any pending migrations (via the \
`deploy:migrate' task) prior to 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.
task :migrations do
set :migrate_target, :latest
desc <<-DESC
Clean up old releases. By default, the last 5 releases are kept on each \
server (though you can change this with the keep_releases variable). All \
other deployed revisions are removed from the servers. By default, this \
will use sudo to clean up the old releases, but if sudo is not available \
for your environment, set the :use_sudo variable to false instead.
task :cleanup, :except => { :no_release => true } do
count = fetch(:keep_releases, 5).to_i
local_releases = capture("ls -xt #{releases_path}").split.reverse
if count >= local_releases.length
logger.important "no old releases to clean up"
else "keeping #{count} of #{local_releases.length} deployed releases"
directories = (local_releases - local_releases.last(count)).map { |release|
File.join(releases_path, release) }.join(" ")
try_sudo "rm -rf #{directories}"
desc <<-DESC
Test deployment dependencies. Checks things like directory permissions, \
necessary utilities, and so forth, reporting on the things that appear to \
be incorrect or missing. This is good for making sure a deploy has a \
chance of working before you actually run `cap deploy'.
You can define your own dependencies, as well, using the `depend' method:
depend :remote, :gem, "tzinfo", ">=0.3.3"
depend :local, :command, "svn"
depend :remote, :directory, "/u/depot/files"
task :check, :except => { :no_release => true } do
dependencies = strategy.check!
other = fetch(:dependencies, {})
other.each do |location, types|
types.each do |type, calls|
if type == :gem
dependencies.send(location).command(fetch(:gem_command, "gem")).or("`gem' command could not be found. Try setting :gem_command")
calls.each do |args|
dependencies.send(location).send(type, *args)
if dependencies.pass?
puts "You appear to have all necessary dependencies installed"
puts "The following dependencies failed. Please check them and try again:"
dependencies.reject { |d| d.pass? }.each do |d|
puts "--> #{d.message}"
desc <<-DESC
Deploys and starts a `cold' application. This is useful if you have not \
deployed your application before, or if your application is (for some \
other reason) not currently running. It will deploy the code, run any \
pending migrations, and then instead of invoking `deploy:restart', it will \
invoke `deploy:start' to fire up the application servers.
task :cold do
desc <<-DESC
Blank task exists as a hook into which to install your own environment \
specific behaviour.
task :start, :roles => :app do
# Empty Task to overload with your platform specifics
desc <<-DESC
Blank task exists as a hook into which to install your own environment \
specific behaviour.
task :stop, :roles => :app do
# Empty Task to overload with your platform specifics
namespace :pending do
desc <<-DESC
Displays the `diff' since your last deploy. This is useful if you want \
to examine what changes are about to be deployed. Note that this might \
not be supported on all SCM's.
task :diff, :except => { :no_release => true } do
desc <<-DESC
Displays the commits since your last deploy. This is good for a summary \
of the changes that have occurred since the last deploy. Note that this \
might not be supported on all SCM's.
task :default, :except => { :no_release => true } do
from = source.next_revision(current_revision)
namespace :web do
desc <<-DESC
Present a maintenance page to visitors. Disables your application's web \
interface by writing a "#{maintenance_basename}.html" file to each web server. 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.
By default, the maintenance page will just say the site is down for \
"maintenance", and will be back "shortly", but you can customize the \
page by specifying the REASON and UNTIL environment variables:
$ cap deploy:web:disable \\
REASON="hardware upgrade" \\
UNTIL="12pm Central Time"
You can use a different template for the maintenance page by setting the \
:maintenance_template_path variable in your deploy.rb file. The template file \
should either be a plaintext or an erb file.
Further customization will require that you write your own task.
task :disable, :roles => :web, :except => { :no_release => true } do
require 'erb'
on_rollback { run "rm -f #{shared_path}/system/#{maintenance_basename}.html" }
# Please add something like this to your site's Apache htaccess to redirect users to the maintenance page.
# More Info:
ErrorDocument 503 /system/#{maintenance_basename}.html
RewriteEngine On
RewriteCond %{REQUEST_URI} !\.(css|gif|jpg|png)$
RewriteCond %{DOCUMENT_ROOT}/system/#{maintenance_basename}.html -f
RewriteCond %{SCRIPT_FILENAME} !#{maintenance_basename}.html
RewriteRule ^.*$ - [redirect=503,last]
# Or if you are using Nginx add this to your server config:
if (-f $document_root/system/maintenance.html) {
return 503;
error_page 503 @maintenance;
location @maintenance {
rewrite ^(.*)$ /system/maintenance.html last;
reason = ENV['REASON']
deadline = ENV['UNTIL']
template =
result =
put result, "#{shared_path}/system/#{maintenance_basename}.html", :mode => 0644
desc <<-DESC
Makes the application web-accessible again. Removes the \
"#{maintenance_basename}.html" page generated by deploy:web:disable, which (if your \
web servers are configured correctly) will make your application \
web-accessible again.
task :enable, :roles => :web, :except => { :no_release => true } do
run "rm -f #{shared_path}/system/#{maintenance_basename}.html"