Introduction to Capistrano

lolmaus edited this page Dec 15, 2010 · 3 revisions

This article is intended to give an understanding of how Capistrano works for people completely unfamiliar with it. The article is clear of Ruby on Rails specificity. It is a good source of basic information useful prior to reading all those uncoordinated Capistrano documents.

What Capistrano is

Capistrano is used to deploy, update and maintain your web application.

Version control your app

The best idea is to store you app's code in a VCS repository, either your own like Subversion and git, or an online service like GitHub.

You should only put the CakePHP application's app folder under version control. The rest of CakePHP should not be included. CakePHP itself is a separate piece of software. By leaving it out of your version control repo, you're able to update CakePHP separately from it's own repo. As for other libraries and dependencies used in your project, they should also be deployed separately.

Capification and deploy.rb

To let your application be deployed with Capistrano, you should capify it by running the capify command inside your app folder. This creates two files in app/config: capfile (similiar to makefile, executed with every Capistrano command, it launches the second file) and deploy.rb.

Deploy.rb is written in Ruby and its own Ruby-based language. It stores your app's Capistrano configuration and recipes. As long as its inside the app/config folder, it is carried with every app instance, so that even when several people work with your project, every one of them has the same deploy.rb file.

The recipes

Recipes are scripts performed on your servers. Each recipe is designed for a certain task. The most common case is a recipe that:

  • downloads your app's code into your repository;
  • saves the code into a directory named after current date and/or version;
  • creates/updates a symlink called current that points to the fresh code directory.

Other recipes might do the following:

  • restarting the webserver;
  • creating a database and it's scheme;
  • filling a fresh database with starting data;
  • installing and updating CakePHP;
  • installing and updating your app's dependencies;
  • updating the database scheme to conform to a new version of your app;
  • ...

Servers and roles

You may have more than one server that work for your project. The servers might be similiar (each running a webserver, a database, etc) and be parts of the development-staging-production environment. Or your servers might be parts of a platform: one server for a database, a number of servers running webservers and a server for load balancing.

Capistrano lets you work with all of those.

First of all, you name each of your servers. Then you assign them roles according to servers' capabilities.

In each recipe you mention what roles the recipe is designed for. When you run a recipe, it is executed on all the servers of that role. Also, when running a recipe you can add a server name or a role to the command line and the recipe will be executed only on mentioned servers.

Running Capistrano

Capistrano is installed to and runs from your working computer. When you command Capistrano to do something on a server, it connects to the server via SSH and works there using shell commands.

You run Capistrano with your current user. But when Capistrano connects to a server, it logins into its shell with a user defined in your app's deploy.rb.

The server user's password should not be defined. Instead, you should use SSH public key authorization. You create a set of keys for your local user and upload the public key to a certain folder inside the remote user's home directory. After that, logging into a remote user with your local user won't require a password. By the way, GitHub also supports that.


Capcake is installed over Capistrano. It is designed to remove Rails specificity from Capistrano and adds some CakePHP-specific Capistrano commands.

Further reading