Thursday, 10 April 2014

Capistrano Details

Capistrano is a Ruby gem or we can say a set of Ruby programs that gives you a set
of advanced tools to deploy web applications to web servers. In other
words, Capistrano allows you to copy code from your source control
repository (SVN/Git) to your server via SSH, and perform pre and
post-deploy functions like restarting a web server, renaming files,
running database migrations and so on. With Capistrano you can also
deploy to many machines at once.
  • Capistrano
    offers many advanced options but for the purpose of this introductory
    blog, we will focus only on the essential things that need to be taken
    care of while deploying a simple app. We will setup a simple
    recipe(fancy name for capistrano scripts) for deploying a Rails
    application to a single server from either SVN or Git repositories. We
    will cover a common workflow that allows you to deploy multiple
    environments: in this case, staging and production.
  • This tutorial has three steps for deployment
  • Installing Capistrano
  • Configure
  • Deployment
So Let’s start with the steps:-
1. Installing Capistrano:- In order to install Capistrano you will need Ruby and RubyGems
installed on your computer. Then, just open the Gemfile of your Rails
application and add the following line to include the capistrano gem:-

gem 'capistrano'
After configuring the gemfile, run ‘bundle install‘ command.
2. Configure:
2.1. Capification
:- Capification refers to generating the necessary files in your Rails
application needed for the deployment and this can be done by firing the
following command in your rails app directory:-
ubuntu:~/app_directory$ capify
This command will create two files:
  • Capfile:
    this is the “main” file that Capistrano needs. Capistrano looks for and
    loads “Capfile” by default. All it does is load “config/deploy.rb”.
  • config/deploy.rb:
    this is the file that contains your Rails application’s deployment
    configuration. Rails prefers that all configuration go under the config
    directory, and so Capistrano tries to abide by that as much as it can by
    just pointing the Capfile to config/deploy.rb.
2.2. Configuration
:- In general, you’ll leave the Capfile alone and do all your tweaking
in config/deploy.rb. So for now just leave the Capfile and start working
with the deploy.rb file. The following are the essential elements which
are needed to be include for basic deployment:-
  • set :application, “App_Name” /* The name of your application to be deployed*/
  • set
    :repository, “repository_address” /*address of the repository where the
    application resides. This repository must be accessible to the
    server(where we are deploying) as well as the local machine*/
  • set
    :scm, :git /*we need to tell capistrano about which SCM we are using
    e.g. GIT, SVN or any other SCM. In above example we are using GIT. if we
    don’t write the SCM then by default it takes it as SVN. if you use
    username and password to access your repository then you need to mention
    that also by using the following two attributes also*/
  • set :scm_username, ‘your_scm_username’
  • set :scm_password, ‘your_scm_password’
  • set :deploy_to, “/data/#{application}” /*the address on the server where you want to deploy your application*/
  • set :user, “username” /*username for ssh login into remote server where you want to deploy your application*/
  • set
    :password, “password” /* for ssh login into remote server where you
    want to deploy your application. If you are not having the password you
    can you your public key to login into the server by giving the following
  • ssh_options[:keys] = ["Your ssh key full path and name"]
  • server
    “”, :app, :web, :db, :primary => true /*name or IP address
    of server where we want to deploy our application. But if we want to
    deploy the application on mltiple servers, then we need to add the
    following */
  • role :app, “”
  • role :web, “”
  • role :db, “”, :primary => true
three roles (app, web, and db) are the three that Capistrano needs for
Rails deployment. You can always add your own roles, too, for tasks of
your own, but make sure you declare at least one server in each of app,
web, and db when you’re deploying Rails applications.
  • web:
    this is where your web server software runs. Requests from the web go
    straight here. For sites with lots of traffic, you might have two or
    three (or more!) web servers running behind a load balancer.
  • app:
    this is where your application layer runs. You might need only a single
    web server, and have it send requests to any of four or five different
    app servers, via a load balancer.
  • db:
    this is where migrations are run. Some prefer not to actually run code
    on the server where the database lives, so you can just set this to one
    of the app servers if you prefer. Capistrano will deploy your
    application to servers in this role. The “:primary => true” bit just
    says that this is our “primary” database server—you can have as many as
    you want (for database slaves and so forth), but Capistrano will only
    run migrations on the one you designate as “primary”.
The addresses you place in each role are the addresses that Capistrano will SSH to, in order to execute the commands you give.
using these parameters one can easily deploy a simple app to server.
And there are some parameter which gives you additional options like:
  • use_sudo:
    Defines for the default Rails deployment recipes whether we want to use
    sudo or not. Sudo is a unix tool for executing commands as the
    root_user . To use it, your user must have passwordless sudo access
    enabled. If you’re using shared hosting where sudo access may not be
    enabled for your user, you should set :use_sudo to false. In general, if
    you can get away without using sudo, you should avoid it.
  • keep_releases:
    The number of old releases to keep, defaults to 5, can be overridden
    with any positive integer, negative values will produce undefined
    behavior. 0 means zero.
  • git_enable_submodules:
    If you’re using git submodules you must tell cap to fetch them or not.
    You can set its value 1 to include it and 0 to not include it.
  • branch:-
    You need to tell cap the branch to checkout during deployment. For
    example we have two branches i.e master and production and you want to
    check out from master branch, then you will be write it as:
  • set :branch, “master”
  • deploy_via:-
    This option is used to tell capistrano that which deployment strategy
    we are using for deployment. There are various options available with
    deploy_via and we can chose between them as our convenience.
  • :checkout will do a full SCM checkout.
  • :copy will checkout locally, then tar and gzip the copy and sftp it to the remote servers.
  • :remote_cache
    will keep a local git repo on the server you’re deploying to and simply
    run a fetch from that rather than an entire clone. This is probably the
    best option as it will only fetch the changes since the last deploy.
  • Deployment
  • Everything
    is ready to try our recipe for the first time and let Capistrano create
    the initial directory structure on your server for future deployments.
    Run the following command from the root directory of your application:
  • cap deploy:setup cap deploy:setup
  • When
    you run this command, Capistrano will SSH to your server, enter the
    directory that you specified in the deploy_to variable, and create a
    special directory structure that’s required for Capistrano to work
    properly. If something is wrong with the permissions or SSH access, you
    will get error messages. Look closely at the output Capistrano gives you
    while the command is running.
  • The
    last step before we can do an actual deployment with Capistrano is to
    make sure that everything is set up correctly on the server from the
    setup command. There’s a simple way to verify, with the command:
  • cap deploy:check cap deploy:check
  • This
    command will check your local environment and your server and locate
    likely problems. If you see any error messages, fix them and run the
    command again. Once you can run without errors, you can proceed!Once
    you’ve verified your local and server configuration, run the following
  • cap production deploy:migrations
  • This command just log in to production and deploy the latest code from the master branch and run all the pending migrations.
  • cap deploy
  • This
    will perform a deployment to your default stage, which is staging. If
    you want to deploy to production, you’d run the following:
  • cap production deploy production deploy
  • While
    these commands are performed, you will see a lot of output. Capistrano
    print all commands it runs on your server as well as their output,
    making it possible for you to debug any problems. Enjoy the dynamic
    deployments using capistrano !!