[Awesome Ruby Gem] Use capistrano gem to make scripts on reemote multi-server automated deployment

Posted on Edited on In , , Views: Word count in article: 5.9k Reading time ≈ 5 mins.

capistrano

Capistrano: A deployment automation tool built on Ruby, Rake, and SSH

Capistrano is a framework for building automated deployment scripts. Although Capistrano itself is written in Ruby, it can easily be used to deploy projects of any language or framework, be it Rails, Java, or PHP.

Once installed, Capistrano gives you a cap tool to perform your deployments from the comfort of your command line.

1
2
$ cd my-capistrano-enabled-project
$ cap production deploy

When you run cap, Capistrano dutifully connects to your server(s) via SSH and executes the steps necessary to deploy your project. You can define those steps yourself by writing Rake tasks, or by using pre-built task libraries provided by the Capistrano community.

Tasks are simple to make. Here’s an example:

1
2
3
4
5
6
task :restart_sidekiq do
  on roles(:worker) do
    execute :service, "sidekiq restart"
  end
end
after "deploy:published", "restart_sidekiq"

Features

There are many ways to automate deployments, from simple rsync bash scripts to complex containerized toolchains. Capistrano sits somewhere in the middle: it automates what you already know how to do manually with SSH, but in a repeatable, scalable fashion. There is no magic here!

Here’s what makes Capistrano great:

Strong conventions

Capistrano defines a standard deployment process that all Capistrano-enabled projects follow by default. You don’t have to decide how to structure your scripts, where deployed files should be placed on the server, or how to perform common tasks: Capistrano has done this work for you.

Multiple stages

Define your deployment once, and then easily parameterize it for multiple stages (environments), e.g. qa, staging, and production. No copy-and-paste necessary: you only need to specify what is different for each stage, like IP addresses.

Parallel execution

Deploying to a fleet of app servers? Capistrano can run each deployment task concurrently across those servers and uses connection pooling for speed.

Server roles

Your application may need many different types of servers: a database server, an app server, two web servers, and a job queue work server, for example. Capistrano lets you tag each server with one or more roles, so you can control what tasks are executed where.

Community driven

Capistrano is easily extensible using the rubygems package manager. Deploying a Rails app? Wordpress? Laravel? Chances are, someone has already written Capistrano tasks for your framework of choice and has distributed it as a gem. Many Ruby projects also come with Capistrano tasks built-in.

It’s just SSH

Everything in Capistrano comes down to running SSH commands on remote servers. On the one hand, that makes Capistrano simple. On the other hand, if you aren’t comfortable SSH-ing into a Linux box and doing stuff on the command-line, then Capistrano is probably not for you.

Gotchas

While Capistrano ships with a strong set of conventions that are common for all types of deployments, it needs help understanding the specifics of your project, and there are some things Capistrano is not suited to do.

Project specifics

Out of the box, Capistrano can deploy your code to server(s), but it does not know how to execute your code. Does foreman need to be run? Does Apache need to be restarted? You’ll need to tell Capistrano how to do this part by writing these deployment steps yourself, or by finding a gem in the Capistrano community that does it for you.

Key-based SSH

Capistrano depends on connecting to your server(s) with SSH using key-based (i.e. password-less) authentication. You’ll need this working before you can use Capistrano.

Provisioning

Likewise, your server(s) will likely need supporting software installed before you can perform a deployment. Capistrano itself has no requirements other than SSH, but your application probably needs database software, a web server like Apache or Nginx, and a language runtime like Java, Ruby, or PHP. These server provisioning steps are not done by Capistrano.

sudo, etc.

Capistrano is designed to deploy using a single, non-privileged SSH user, using a non-interactive SSH session. If your deployment requires sudo, interactive prompts, authenticating as one user but running commands as another, you can probably accomplish this with Capistrano, but it may be difficult. Your automated deployments will be much smoother if you can avoid such requirements.

Shells

Capistrano 3 expects a POSIX shell like Bash or Sh. Shells like tcsh, csh, and such may work, but probably will not.

Quick start

Requirements

  • Ruby version 2.0 or higher on your local machine (MRI or Rubinius)

  • A project that uses source control (Git, Mercurial, and Subversion support is built-in)

  • The SCM binaries (e.g. git, hg) needed to check out your project must be installed on the server(s) you are deploying to

  • Bundler, along with a Gemfile for your project, are recommended

Install the Capistrano gem

You can install it as a gem:

1
$ gem install capistrano

or add it into a Gemfile (Bundler):

1
2
3
4
5
6
7
# Gemfile

group :development do
  # capistrano/capistrano: Remote multi-server automation tool
  # https://github.com/capistrano/capistrano
  gem "capistrano", "3.16.0 ", require: false
end

Then, run bundle install.

1
$ bundle install

“Capify” your project

Make sure your project doesn’t already have a Capfile or capfile present. Then run:

1
$ bundle exec cap install

This creates all the necessary configuration files and directory structure for a Capistrano-enabled project with two stages, staging and production:

1
2
3
4
5
6
7
8
9
├── Capfile
├── config
│   ├── deploy
│   │   ├── production.rb
│   │   └── staging.rb
│   └── deploy.rb
└── lib
    └── capistrano
            └── tasks

To customize the stages that are created, use:

1
$ bundle exec cap install STAGES=local,sandbox,qa,production

Note that the files that Capistrano creates are simply templates to get you started. Make sure to edit the deploy.rb and stage files so that they contain values appropriate for your project and your target servers.

Command-line usage

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
# 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

# lists all config variable before deployment tasks
$ bundle exec cap production deploy --print-config-variables

References

[1] capistrano/capistrano: Remote multi-server automation tool - https://github.com/capistrano/capistrano

[2] A remote server automation and deployment tool written in Ruby. - https://capistranorb.com/

[3] capistrano | RubyGems.org | your community gem host - https://rubygems.org/gems/capistrano/