Capistrano – Server Automation and Deployment Tool

What it is ?

Capistrano is an open source tool for running scripts on multiple servers; its main use is deploying web applications. It automates the process of making a new version of an application available on one or more web servers, including supporting tasks such as changing databases.
It’s written in Ruby, but it can easily be used to deploy any language. If your application or the framework has any special deployment requirements, Capistrano can be easily extended to accommodate any such tasks.

Why use it ?

So here are some use cases that may inspire you to use it :

• Capistrano becomes quite handy while Automating a distributed environment.
• You can easily deploy your application in parallel on multiple machines without any downtime.
• It can also perform database related tasks associated with the release deployment.
• It can also integrate with SCM like GIT and SVN to deploy the pull code from the your repository
• Due to its clean directory structure , reverting to any previous release becomes quick and easy.
• You can also perform pre and post-deploy functions like restarting a webserver, purging cache, renaming files and so on.
• It can perform all the tasks in a single transaction, such that if any step fails during the deployment all the changes done will be rolled back automatically.

How to use it ?

In order to install Capistrano you will need Ruby and RubyGems installed on your computer, you can use this reference to learn how to install Ruby and RubyGems.

Then run the follwing command :

[shell]
gem install capistrano-ext
[/shell]

Preparing for Project Deployment

Navigate to your application’s root directory in Terminal and run the following command:

[shell]
capify .
[/shell]

This will create a file called capfile in your project and add default deployment recipe at config/deploy.rb in your project. Delete everything from the deploy.rb file.

How to create a Capistrano Recipe

In your empty deploy.rb file, let’s enter the name of your app :

[shell]
set :application, “your_app_name”
[/shell]

Now lets add a Git repository :

[shell]
set :scm, :git
set :repository, "git@intelligrape.com:/repository.git"
set :scm_passphrase, ""
[/shell]

Lets add the user that will ssh into the servers

[shell]
set :user, "server-user-name"
[/shell]

In this example we’ll deploy to Pre-Production and Production environment. For that we’ll require mutistage at the top of the deploy.rb file :

[shell]
require ‘capistrano/ext/multistage’
[/shell]

Then specify your environments, or “stages”:

[shell]
set :stages, ["pre-prod", "production"]
set :default_stage, "pre-prod"
[/shell]

Next, create a directory deploy inside your app’s config directory, and then add production.rb and pre-prod.rb files to it. You’ll need per file per stage and also make sure that you naming the files same.
Now let’s populate our production.rb settings:

[shell]
server "IP_ADDR-OR-FQND", :app, :web
set :deploy_to, "/var/www/my_WebApp"
[/shell]

And then staging.rb:

[shell]
server "IP_ADDR-OR-FQND", :app, :web
set :deploy_to, "/var/www/my_WebApp-preProd"
[/shell]

Validating your recipe

Capistrano needs to create it’s directory structure on the server in the deploy_to directory. Run the following command from the root of your application :

[shell]
cap deploy:setup
[/shell]

If something goes wrong with the permission or the SSH, you’ll get an error.

Now before we do actual deployment make sure everything is setup correctly , to test that run the following command :

[shell]
cap deploy:check
[/shell]

Deploying

Once you have verified and tested everything , run the following command :

[shell]
cap deploy
[/shell]

To deploy to any specific stage/environment , suppose production, run the following command :

[shell]
cap production deploy
[/shell]

Further Reading

Idea of this blog was to give a brief introduction to Capistrano , in order to use it fully on a production scale, we suggest you to read the official Wiki of Capistrano.