Upgrading to 2.0
Capistrano 2.0 is the first significant update to Capistrano in a year. It represents a major refactoring of the tool's internals, as well as a complete reworking of the deployment recipes. It adds several new features:
- Namespaces. Tasks may be namespaced now, which means you can have your own "deploy" task without clobbering the version that Capistrano ships with.
- Improved online help. The command-line utility is friendlier than ever, with better ways to query the available tasks, and to discover what they do.
- Deployment strategies. Whereas Capistrano 1.x only supported "checkout" based deployments, Capistrano 2.0 lets gives you more options. You can now deploy by copying a tarball to the servers, or keep a cached repository on each target server. You can even write and distribute your own custom deployment strategies!
- Event framework for extending tasks. In Capistrano 1.x you extended tasks by creating new tasks whose names were prefixed with "before_" or "after_". In Capistrano 2 there is a new framework for defining and triggering events, allowing you to chain multiple tasks together.
- More ways to execute tasks. The "run" and "sudo" helpers got a lot more powerful; you can now pass a specific set of hosts to them, which means you can even call them outside of any task. You could conceivably write Capistrano scripts, basically making an entire file a single task!
Capification
Capify?
In Capistrano 1.x, "config/deploy.rb" was a file that Capistrano would automatically look for and load. In Capistrano 2, that is no longer the case. The only files that Capistrano 2 will autodetect are "capfile" and "Capfile".
It's extremely easy to keep things backwards compatible, though. You just need a "Capfile" in your root project directory which loads "config/deploy.rb". It's almost that simple.
However, Capistrano 1.x also would automatically load the deployment recipes for you. Capistrano 2 does not; the deployment recipes are now opt-in.
Fortunately, that's easy enough to manage, too. In your new "Capfile" file, just make sure and load "deploy" before loading "config/deploy.rb". The "capify" script provided by Capistrano 2.0 will do all this for you.
For brand-new applications, using Capistrano 2.0 is as easy as it ever was. However, the process of updating your existing Capistrano 1.x recipes and tasks may require a bit of effort.
First, you need to "capify" your project, since Capistrano 2.0 no longer recognizes "config/deploy.rb" automatically. (See the sidebar on the right for more information.)
Capistrano 2 comes with a script that does this for you; just change to your project's root directory and type:
capify .
It will automatically create a "Capfile" for you, and (if the config directory exists, and config/deploy.rb does not) it will also create a skeletal "config/deploy.rb" file, too. This is good for getting new projects "capified", as well as preexisting projects.
REVISION files
Capistrano 2.0 no longer uses the revisions.log file, which Capistrano 1.x used to maintain on each deploy. Instead, the new deployment tasks add a REVISION file to each deployed version, which contains the revision number that was deployed. If you're working with an existing project that has already been deployed many times, and you want to be able to use tasks like "deploy:pending" and "deploy:pending:diff" with versions that were deployed with Capistrano 1.x, you can easily update those previous deployments to use Capistrano 2's new per-deploy REVISION file:
cap -f upgrade -f Capfile upgrade:revisions
That will go through and reconstruct the REVISION file in each deployed revision, based on the history in the revisions.log file. It is safe, and non-destructive, so you can call this even if you might decide to go back to using Capistrano 1.x.
(Note that, in general, you don't need to explicitly do "-f Capfile". However, if you use the -f switch at all, Capistrano will not autoload the default recipe file, so you'll need to specify it explicitly.)