Capistrano

Documentation

Check out the online documentation of Capistrano 3 hosted via this repository.

Support

Need help with getting Capistrano up and running? Got a code problem you want to get solved quickly?

Get Capistrano support on CodersClan.

Requirements

Ruby >= 2.0.0 (JRuby and C-Ruby/YARV are supported)

Capistrano support these source code version control systems out of the box:

Git 1.8 or higher
Mercurial
SVN

Binaries for these VCS might be required on the local and/or the remote systems.

Installation

Add this line to your application's Gemfile:

gem 'capistrano', '~> 3.4.0'

And then execute:

$ bundle install

Capify: make sure there's no "Capfile" or "capfile" present

$ bundle exec cap install

This creates the following files:

├── Capfile
├── config
│   ├── deploy
│   │   ├── production.rb
│   │   └── staging.rb
│   └── deploy.rb
└── lib
    └── capistrano
            └── tasks

To create different stages:

$ bundle exec cap install STAGES=local,sandbox,qa,production

Usage

# list all available tasks
$ bundle exec cap -T

# deploy to the staging environment
$ bundle exec cap staging deploy

# deploy to the production environment
$ bundle exec cap production deploy

# simulate deploying to the production environment
# does not actually do anything
$ bundle exec cap production deploy --dry-run

# list task dependencies
$ bundle exec cap production deploy --prereqs

# trace through task invocations
$ bundle exec cap production deploy --trace

Validation of variables

To validate a variable, each time before it is set, define a validation:

validate :some_key do |key, value|
  if value.length < 5
    raise Capistrano::ValidationError, "Length of #{key} is too short!"
  end
end

Multiple validation can be assigned to a single key. Validations will be executed in the order of registration.

Validations can be used to ensure certain properties of user-supplied values, e.g. from ask or ENV. ``

Testing

Capistrano has two test suites: an RSpec suite and a Cucumber suite. The RSpec suite handles quick feedback unit specs. The Cucumber suite features an integration suite that uses Vagrant to deploy to a real virtual server. In order to run the Cucumber suite you will need to install Vagrant and Vagrant supported virtualization software like VirtualBox.

# To run the RSpec suite
$ rake spec

# To run the Cucumber suite
$ rake features

# To run the Cucumber suite and leave the VM running (faster for subsequent runs)
$ rake features KEEP_RUNNING=1

SSHKit

SSHKit is the driver for SSH connections behind the scenes in Capistrano. Depending on how deep you dig, you might run into interfaces that come directly from SSHKit (the configuration is a good example).

License

MIT License (MIT)

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.

Amakata/capistrano