capistrano 2.1.0 → 3.0.0

data/README.md

@@ -0,0 +1,226 @@
+# Capistrano [![Build Status](https://travis-ci.org/capistrano/capistrano.png?branch=v3)](https://travis-ci.org/capistrano/capistrano)
+
+## Requirements
+
+* Ruby >= 1.9 (JRuby and C-Ruby/YARV are supported)
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+``` ruby
+gem 'capistrano', '~> 3.0.0'
+```
+
+And then execute:
+
+``` ruby
+$ bundle --binstubs
+```
+
+Capify:
+*make sure there's no "Capfile" or "capfile" present*
+``` shell
+$ cap install
+```
+
+This creates the following files:
+
+```
+├── Capfile
+├── config
+│   ├── deploy
+│   │   ├── production.rb
+│   │   └── staging.rb
+│   └── deploy.rb
+└── lib
+    └── capistrano
+            └── tasks
+```
+
+To create different stages:
+
+``` shell
+$ cap install STAGES=local,sandbox,qa,production
+```
+
+## Usage
+
+``` shell
+$ cap -vT
+
+$ cap staging deploy
+$ cap production deploy
+
+$ cap production deploy --dry-run
+$ cap production deploy --prereqs
+$ cap production deploy --trace
+```
+
+## Tasks
+
+``` ruby
+server 'example.com', roles: [:web, :app]
+server 'example.org', roles: [:db, :workers]
+desc "Report Uptimes"
+task :uptime do
+  on roles(:all) do |host|
+    info "Host #{host} (#{host.roles.join(', ')}):\t#{capture(:uptime)}"
+  end
+end
+```
+
+## Before / After
+
+Where calling on the same task name, executed in order of inclusion
+
+``` ruby
+# call an existing task
+before :starting, :ensure_user
+
+after :finishing, :notify
+
+
+# or define in block
+before :starting, :ensure_user do
+  #
+end
+
+after :finishing, :notify do
+  #
+end
+```
+
+If it makes sense for your use-case (often, that means *generating a file*)
+the Rake prerequisite mechanism can be used:
+
+``` ruby
+desc "Create Important File"
+file 'important.txt' do |t|
+  sh "touch #{t.name}"
+end
+desc "Upload Important File"
+task :upload => 'important.txt' do |t|
+  on roles(:all) do
+    upload!(t.prerequisites.first, '/tmp')
+  end
+end
+```
+
+The final way to call out to other tasks is to simply `invoke()` them:
+
+``` ruby
+task :one do
+  on roles(:all) { info "One" }
+end
+task :two do
+  invoke :one
+  on roles(:all) { info "Two" }
+end
+```
+
+This method is widely used.
+
+## Getting User Input
+
+``` ruby
+desc "Ask about breakfast"
+task :breakfast do
+  breakfast = ask(:breakfast, "What would you like your colleagues to you for breakfast?")
+  on roles(:all) do |h|
+    execute "echo \"$(whoami) wants #{breakfast} for breakfast!\" | wall"
+  end
+end
+```
+
+Perfect, who needs telephones.
+
+
+## Running local tasks
+
+Local tasks can be run by replacing `on` with `run_locally`
+
+``` ruby
+desc "Notify service of deployment"
+task :notify do
+  run_locally do
+    with rails_env: :development do
+      rake 'service:notify'
+    end
+  end
+end
+```
+
+## Console
+
+**Note:** Here be dragons. The console is very immature, but it's much more
+cleanly architected than previous incarnations and it'll only get better from
+here on in.
+
+Execute arbitrary remote commands, to use this simply add
+`require 'capistrano/console'` which will add the necessary tasks to your
+environment:
+
+``` shell
+$ cap staging console
+```
+
+Then, after setting up the server connections, this is how that might look:
+
+```
+$ cap production console
+capistrano console - enter command to execute on production
+production> uptime
+ INFO [94db8027] Running /usr/bin/env uptime on leehambley@example.com:22
+DEBUG [94db8027] Command: /usr/bin/env uptime
+DEBUG [94db8027]   17:11:17 up 50 days, 22:31,  1 user,  load average: 0.02, 0.02, 0.05
+ INFO [94db8027] Finished in 0.435 seconds command successful.
+production> who
+ INFO [9ce34809] Running /usr/bin/env who on leehambley@example.com:22
+DEBUG [9ce34809] Command: /usr/bin/env who
+DEBUG [9ce34809]  leehambley pts/0        2013-06-13 17:11 (port-11262.pppoe.wtnet.de)
+ INFO [9ce34809] Finished in 0.420 seconds command successful.
+```
+
+## A word about PTYs
+
+There is a configuration option which asks the backend driver to as the remote host
+to assign the connection a *pty*. A *pty* is a pseudo-terminal, which in effect means
+*tell the backend that this is an **interactive** session*. This is normally a bad idea.
+
+Most of the differences are best explained by [this page](https://github.com/sstephenson/rbenv/wiki/Unix-shell-initialization) from the author of *rbenv*.
+
+**When Capistrano makes a connection it is a *non-login*, *non-interactive* shell.
+This was not an accident!**
+
+It's often used as a band aid to cure issues related to RVM and rbenv not loading login
+and shell initialisation scripts. In these scenarios RVM and rbenv are the tools at fault,
+or at least they are being used incorrectly.
+
+Whilst, especially in the case of language runtimes (Ruby, Node, Python and friends in
+particular) there is a temptation to run multiple versions in parallel on a single server
+and to switch between them using environmental variables, this is an anti-pattern, and
+symptomatic of bad design (i.e. you're testing a second version of Ruby in production because
+your company lacks the infrastructure to test this in a staging environment).
+
+## Configuration
+
+The following variables are settable:
+
+| Variable Name         | Description                                                         | Notes                                                           |
+|:---------------------:|---------------------------------------------------------------------|-----------------------------------------------------------------|
+| `:repo_url`           | The URL of your Git repository                                      | file://, https://, or ssh:// are all supported                  |
+| `:git_https_username` | The (optional) username for accessing your Git repostory over HTTPS | if this is an SSH connection, this setting will have no effect. |
+| `:git_https_password` | The (optional) password for accessing your Git repostory over HTTPS | if this is an SSH connection, this setting will have no effect. |
+| `:tmp_dir` | The (optional) temp directory that will be used (default: /tmp) | if you have a shared web host, this setting may need to be set (i.e. /home/user/tmp/capistrano). |
+
+## SSHKit
+
+[SSHKit](https://github.com/capistrano/sshkit) is the driver for SSH
+connections behind the scenes in Capistrano, depending how deep you dig, you
+might run into interfaces that come directly from SSHKit (the configuration is
+a good example).
+
+## Licence
+
+<a rel="license" href="http://creativecommons.org/licenses/by-nc-sa/3.0/deed.en_US"><img alt="Creative Commons License" style="border-width:0" src="http://i.creativecommons.org/l/by-nc-sa/3.0/88x31.png" /></a><br /><span xmlns:dct="http://purl.org/dc/terms/" property="dct:title">Capistrano</span> by <a xmlns:cc="http://creativecommons.org/ns#" href="http://www.capistranorb.com." property="cc:attributionName" rel="cc:attributionURL">Lee Hambley and Tom Clements</a> is licensed under a <a rel="license" href="http://creativecommons.org/licenses/by-nc-sa/3.0/deed.en_US">Creative Commons Attribution-NonCommercial-ShareAlike 3.0 Unported License</a>.<br />Based on a work at <a xmlns:dct="http://purl.org/dc/terms/" href="https://www.github.com/capistrano" rel="dct:source">https://www.github.com/capistrano</a>.

data/Rakefile

@@ -0,0 +1,5 @@
+require "bundler/gem_tasks"
+
+task :default => :spec
+require 'rspec/core/rake_task'
+RSpec::Core::RakeTask.new

data/bin/cap

@@ -1,4 +1,3 @@
 #!/usr/bin/env ruby
-
-require 'capistrano/cli'
-Capistrano::CLI.execute
+require 'capistrano/all'
+Capistrano::Application.new.run

data/bin/capify

@@ -1,78 +1,8 @@
 #!/usr/bin/env ruby
-
-require 'optparse'
-
-OptionParser.new do |opts|
-  opts.banner = "Usage: #{File.basename($0)} [path]"
-
-  opts.on("-h", "--help", "Displays this help info") do
-    puts opts
-    exit 0
-  end
-
-  begin
-    opts.parse!(ARGV)
-  rescue OptionParser::ParseError => e
-    warn e.message
-    puts opts
-    exit 1
-  end
-end
-
-if ARGV.empty?
-  abort "Please specify the directory to capify, e.g. `#{File.basename($0)} .'"
-elsif !File.exists?(ARGV.first)
-  abort "`#{ARGV.first}' does not exist."
-elsif !File.directory?(ARGV.first)
-  abort "`#{ARGV.first}' is not a directory."
-elsif ARGV.length > 1
-  abort "Too many arguments; please specify only the directory to capify."
-end
-
-def unindent(string)
-  indentation = string[/\A\s*/]
-  string.strip.gsub(/^#{indentation}/, "")
-end
-
-files = {
-  "Capfile" => unindent(<<-FILE),
-    load 'deploy' if respond_to?(:namespace) # cap2 differentiator
-    Dir['vendor/plugins/*/recipes/*.rb'].each { |plugin| load(plugin) }
-    load 'config/deploy'
-  FILE
-
-  "config/deploy.rb" => unindent(<<-FILE),
-    set :application, "set your application name here"
-    set :repository,  "set your repository location here"
-
-    # If you aren't deploying to /u/apps/\#{application} on the target
-    # servers (which is the default), you can specify the actual location
-    # via the :deploy_to variable:
-    # set :deploy_to, "/var/www/\#{application}"
-
-    # If you aren't using Subversion to manage your source code, specify
-    # your SCM below:
-    # set :scm, :subversion
-
-    role :app, "your app-server here"
-    role :web, "your web-server here"
-    role :db,  "your db-server here", :primary => true
-  FILE
-}
-
-base = ARGV.shift
-files.each do |file, content|
-  file = File.join(base, file)
-  if File.exists?(file)
-    warn "[skip] `#{file}' already exists"
-  elsif File.exists?(file.downcase)
-    warn "[skip] `#{file.downcase}' exists, which could conflict with `#{file}'"
-  elsif !File.exists?(File.dirname(file))
-    warn "[skip] directory `#{File.dirname(file)}' does not exist"
-  else
-    puts "[add] writing `#{file}'"
-    File.open(file, "w") { |f| f.write(content) }
-  end
-end
-
-puts "[done] capified!"
+puts "-" * 80
+puts "Capistrano 3.x is incompatible with Capistrano 2.x. "
+puts
+puts "This command has become `cap install` in Capistrano 3.x"
+puts
+puts "For more information see http://www.capistranorb.com/"
+puts "-" * 80

data/capistrano-public_cert.pem

@@ -0,0 +1,22 @@
+-----BEGIN CERTIFICATE-----
+MIIDkjCCAnqgAwIBAgIBATANBgkqhkiG9w0BAQUFADBHMRIwEAYDVQQDDAlnZW1t
+YXN0ZXIxHDAaBgoJkiaJk/IsZAEZFgxjYXBpc3RyYW5vcmIxEzARBgoJkiaJk/Is
+ZAEZFgNjb20wHhcNMTMwNjI4MTM0MzQ1WhcNMTQwNjI4MTM0MzQ1WjBHMRIwEAYD
+VQQDDAlnZW1tYXN0ZXIxHDAaBgoJkiaJk/IsZAEZFgxjYXBpc3RyYW5vcmIxEzAR
+BgoJkiaJk/IsZAEZFgNjb20wggEiMA0GCSqGSIb3DQEBAQUAA4IBDwAwggEKAoIB
+AQDnuMT+SoCTQoxEOma65Vf9ftibHTzfaZPGSNcheguiFa3/Mc69/xurtUa7bGY8
+ZyuJbd2pb4pqhx7PcVlByJnBQCmOHzZPzn6wVa5n4n8/VBccYcFNePdPj8+KK13x
++97E6mjNZJtf4BZm4tZD6Ztyq90+mQ0WeoseYfYdm+ZJ9BNFdB2EHmTnh983MHMj
+WNn52ZC2pAHDRuxKAOj5yq8IZWA8B/IWNjMXQCJbM9eaH0+vVvquC2RyprpkfoqQ
+Xb7BJA2hftizHUMk4LOldNvy220GHjKL0Ot7tlGcD2DzaZNN0aPUfezz306ytsMp
+KDYYLbLcg63TPHFHu1fzyQG9AgMBAAGjgYgwgYUwCQYDVR0TBAIwADALBgNVHQ8E
+BAMCBLAwHQYDVR0OBBYEFEzXgfsvOB8Aw2b+Md3t3O9PUGZCMCUGA1UdEQQeMByB
+GmdlbW1hc3RlckBjYXBpc3RyYW5vcmIuY29tMCUGA1UdEgQeMByBGmdlbW1hc3Rl
+ckBjYXBpc3RyYW5vcmIuY29tMA0GCSqGSIb3DQEBBQUAA4IBAQCnS7Pcy/srhZCb
+TrUNkCTHI4QEURAWRNYFLL9TCCl3oyKkwW6aZxarpQbJK3Es99sugsKh/sKijOIE
+xhflvSNN59Zc/BETve1y0VktN+94GiQQ1F82SmRwmY2tJJD7C3jQ6Og6pX7eNBWZ
+W1su8leIv8sj3o5Vdn/Le1HKVXMakFICq9HdLnIH1jW2Brfthlc2ujAg0cOU58GC
+wNkME+L45pR9zggNpbBY23mlbAicPrsmybEdk9SOdaOCgxh+fyGx6Q2n0m5YAXgN
+KVoU0DazqHs6BVyJaajxht4kCpPDD1wUqCvwlOQtotdwD7CCGCPdcYgf6fAp4yQZ
+jC76QR6/
+-----END CERTIFICATE-----

data/capistrano.gemspec

@@ -0,0 +1,35 @@
+# -*- encoding: utf-8 -*-
+lib = File.expand_path('../lib', __FILE__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+require 'capistrano/version'
+
+Gem::Specification.new do |gem|
+  gem.name          = "capistrano"
+  gem.version       = Capistrano::VERSION
+  gem.authors       = ["Tom Clements", "Lee Hambley"]
+  gem.email         = ["seenmyfate@gmail.com", "lee.hambley@gmail.com"]
+  gem.description   = %q{Capistrano is a utility and framework for executing commands in parallel on multiple remote machines, via SSH.}
+  gem.summary       = %q{Capistrano - Welcome to easy deployment with Ruby over SSH}
+  gem.homepage      = ""
+
+  gem.files         = `git ls-files`.split($/)
+  gem.executables   = 'cap'
+  gem.test_files    = gem.files.grep(%r{^(test|spec|features)/})
+  gem.require_paths = ["lib"]
+
+  gem.post_install_message = "If you're updating Capistrano from 2.x.x, we recommend you to read the upgrade guide: http://www.capistranorb.com/documentation/upgrading/"
+
+  #gem.signing_key = '/Volumes/SD Card/leehambley-private_key.pem'
+  #gem.cert_chain  = ['capistrano-public_cert.pem', 'leehambley-public_cert.pem']
+
+  gem.add_dependency 'sshkit', '>= 0.0.23'
+  gem.add_dependency 'rake', '>= 10.0.0'
+  gem.add_dependency 'i18n'
+
+  gem.add_development_dependency 'rspec'
+  gem.add_development_dependency 'mocha'
+  gem.add_development_dependency 'vagrant', '~> 1.0.7'
+  gem.add_development_dependency 'kuroko'
+  gem.add_development_dependency 'cucumber'
+
+end

data/features/deploy.feature

@@ -0,0 +1,52 @@
+Feature: Deploy
+
+  Background:
+    Given a test app with the default configuration
+    And servers with the roles app and web
+
+  Scenario: Creating the repo
+    When I run cap "git:check"
+    Then references in the remote repo are listed
+
+  Scenario: Creating the directory structure
+    When I run cap "deploy:check:directories"
+    Then the shared path is created
+    And the releases path is created
+
+  Scenario: Creating linked directories
+    When I run cap "deploy:check:linked_dirs"
+    Then directories in :linked_dirs are created in shared
+
+  Scenario: Creating linked directories for linked files
+    When I run cap "deploy:check:make_linked_dirs"
+    Then directories referenced in :linked_files are created in shared
+
+  Scenario: Checking linked files - missing file
+    Given a required file
+    But the file does not exist
+    When I run cap "deploy:check:linked_files"
+    Then the task will exit
+
+  Scenario: Checking linked files - file exists
+    Given a required file
+    And that file exists
+    When I run cap "deploy:check:linked_files"
+    Then the task will be successful
+
+  Scenario: Creating a release
+    When I run cap "git:create_release" as part of a release
+    Then the repo is cloned
+    And the release is created
+
+  Scenario: Symlink linked files
+    When I run cap "deploy:symlink:linked_files" as part of a release
+    Then file symlinks are created in the new release
+
+  Scenario: Symlink linked dirs
+    When I run cap "deploy:symlink:linked_dirs" as part of a release
+    Then directory symlinks are created in the new release
+
+  Scenario: Publishing
+    When I run cap "deploy:symlink:release"
+    Then the current directory will be a symlink to the release
+

data/features/installation.feature

@@ -0,0 +1,16 @@
+Feature: Installation
+
+  Background:
+    Given a test app with the default configuration
+
+  Scenario: With default stages
+    When I run cap "install"
+    Then the deploy.rb file is created
+    And the default stage files are created
+    And the tasks folder is created
+
+  Scenario: With specified stages
+    When I run cap "install STAGES=qa,production"
+    Then the deploy.rb file is created
+    And the specified stage files are created
+    And the tasks folder is created

data/features/remote_file_task.feature

@@ -0,0 +1,14 @@
+Feature: Remote file task
+
+  Background:
+    Given a test app with the default configuration
+    And a custom task to generate a file
+    And servers with the roles app and web
+
+  Scenario: Where the file does not exist
+    When I run cap "deploy:check:linked_files"
+    Then it creates the file with the remote_task prerequisite
+
+  Scenario: Where the file already exists
+    When I run cap "deploy:check:linked_files"
+    Then it will not recreate the file

data/features/step_definitions/assertions.rb

@@ -0,0 +1,90 @@
+Then(/^references in the remote repo are listed$/) do
+end
+
+Then(/^the shared path is created$/) do
+  run_vagrant_command(test_dir_exists(TestApp.shared_path))
+end
+
+Then(/^the releases path is created$/) do
+  run_vagrant_command(test_dir_exists(TestApp.releases_path))
+end
+
+Then(/^directories in :linked_dirs are created in shared$/) do
+  TestApp.linked_dirs.each do |dir|
+    run_vagrant_command(test_dir_exists(TestApp.shared_path.join(dir)))
+  end
+end
+
+Then(/^directories referenced in :linked_files are created in shared$/) do
+  dirs = TestApp.linked_files.map { |path| TestApp.shared_path.join(path).dirname }
+  dirs.each do | dir|
+    run_vagrant_command(test_dir_exists(dir))
+  end
+end
+
+Then(/^the task will be successful$/) do
+end
+
+
+Then(/^the task will exit$/) do
+end
+
+Then(/^the repo is cloned$/) do
+  run_vagrant_command(test_dir_exists(TestApp.repo_path))
+end
+
+Then(/^the release is created$/) do
+  run_vagrant_command("ls -g #{TestApp.releases_path}")
+end
+
+Then(/^file symlinks are created in the new release$/) do
+  pending
+  TestApp.linked_files.each do |file|
+    run_vagrant_command(test_symlink_exists(TestApp.release_path.join(file)))
+  end
+end
+
+Then(/^directory symlinks are created in the new release$/) do
+  pending
+  TestApp.linked_dirs.each do |dir|
+    run_vagrant_command(test_symlink_exists(TestApp.release_path.join(dir)))
+  end
+end
+
+Then(/^the current directory will be a symlink to the release$/) do
+  run_vagrant_command(test_symlink_exists(TestApp.current_path))
+end
+
+Then(/^the deploy\.rb file is created$/) do
+  file = TestApp.test_app_path.join('config/deploy.rb')
+  expect(File.exists?(file)).to be_true
+end
+
+Then(/^the default stage files are created$/) do
+  staging = TestApp.test_app_path.join('config/deploy/staging.rb')
+  production = TestApp.test_app_path.join('config/deploy/production.rb')
+  expect(File.exists?(staging)).to be_true
+  expect(File.exists?(production)).to be_true
+end
+
+Then(/^the tasks folder is created$/) do
+  path = TestApp.test_app_path.join('lib/capistrano/tasks')
+  expect(Dir.exists?(path)).to be_true
+end
+
+Then(/^the specified stage files are created$/) do
+  qa = TestApp.test_app_path.join('config/deploy/qa.rb')
+  production = TestApp.test_app_path.join('config/deploy/production.rb')
+  expect(File.exists?(qa)).to be_true
+  expect(File.exists?(production)).to be_true
+end
+
+Then(/^it creates the file with the remote_task prerequisite$/) do
+  TestApp.linked_files.each do |file|
+    run_vagrant_command(test_file_exists(TestApp.shared_path.join(file)))
+  end
+end
+
+Then(/^it will not recreate the file$/) do
+  #
+end

data/features/step_definitions/cap_commands.rb

@@ -0,0 +1,8 @@
+When(/^I run cap "(.*?)"$/) do |task|
+  TestApp.cap(task)
+end
+
+When(/^I run cap "(.*?)" as part of a release$/) do |task|
+  TestApp.cap("deploy:new_release_path #{task}")
+end
+

data/features/step_definitions/setup.rb

@@ -0,0 +1,25 @@
+Given(/^a test app with the default configuration$/) do
+  TestApp.install
+end
+
+Given(/^servers with the roles app and web$/) do
+  vagrant_cli_command('up')
+end
+
+Given(/^a required file$/) do
+end
+
+Given(/^that file exists$/) do
+  run_vagrant_command("touch #{TestApp.linked_file}")
+end
+
+Given(/^the file does not exist$/) do
+  pending
+  file = TestApp.linked_file
+  run_vagrant_command("[ -f #{file} ] && rm #{file}")
+end
+
+Given(/^a custom task to generate a file$/) do
+  TestApp.copy_task_to_test_app('spec/support/tasks/database.cap')
+end
+

data/features/support/env.rb

@@ -0,0 +1,12 @@
+require 'kuroko'
+
+project_root = File.expand_path('../../../', __FILE__)
+vagrant_root = File.join(project_root, 'spec/support')
+
+Kuroko.configure do |config|
+  config.vagrant_root = 'spec/support'
+end
+
+puts vagrant_root.inspect
+
+require_relative '../../spec/support/test_app'

data/features/support/remote_command_helpers.rb

@@ -0,0 +1,20 @@
+module RemoteCommandHelpers
+
+  def test_dir_exists(path)
+    exists?('d', path)
+  end
+
+  def test_symlink_exists(path)
+    exists?('L', path)
+  end
+
+  def test_file_exists(path)
+    exists?('f', path)
+  end
+
+  def exists?(type, path)
+    %{[ -#{type} "#{path}" ] && echo "#{path} exists." || echo "Error: #{path} does not exist."}
+  end
+end
+
+World(RemoteCommandHelpers)

data/lib/Capfile

@@ -0,0 +1,3 @@
+#!/usr/bin/env cap
+include Capistrano::DSL
+require 'capistrano/install'

data/lib/capistrano/all.rb

@@ -0,0 +1,16 @@
+require 'rake'
+require 'sshkit'
+require 'sshkit/dsl'
+
+Rake.application.options.trace = true
+
+require 'capistrano/version'
+require 'capistrano/version_validator'
+require 'capistrano/i18n'
+require 'capistrano/dsl'
+require 'capistrano/application'
+require 'capistrano/configuration'
+
+module Capistrano
+
+end