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 >= 1.9.3 (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.3.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

Testing

Capistrano has two test suites: an RSpec suite and a Cucumber suite. The RSpec suite handles quick feedback unit specs. The Cucumber features are 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

Metrics

Since version 3.3.3 Capistrano includes anonymous metrics. The metric server, gem collection, and when it exists, the HTML/d3 page to view the metrics are all open-source and available for inspection and audit at https://github.com/capistrano/stats

Notes for CI: If you commit the file .capistrano/metrics to your source control, you will not be prompted again, this is what we expect you to do, and it should also avoid breaking your CI server by blocking waiting for an answer on standard in. The metric prompt is also disabled when standard in is not a tty (when using Capistrano from scripts, or from some well behaved CI services)

• The gem invites users to opt-into metrics collection when the task load:defaults is called. A project-specific hash derived from the output of git config remote.origin.url is written to a file .capistrano/metrics to allow us to differentiate between many members of the same team deploying the same project vs. many people on many projects.

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)

Copyright (c) 2012-2015 Tom Clements, Lee Hambley

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.