About Capistrano

Tuesday, 16/06/2020

Tram Ho

You all know that, to deploy an application to the server, we have to go through a lot of steps. Writing each command every time we need to deploy, update an application makes us tired, time-consuming, labor-intensive, as well as the potential for unnecessary errors.

So today I will introduce to everyone about Capistrano to deploy the application to the server. This is a very famous tool, we can deploy an application through 1 command!

Note: I will default when everyone reads this article that already knows about how to deploy a Ruby application. Capistrano only works when everyone understands about deploying, but if you do not know about deploying, please read through this tutorial !

A few basic concepts

Introduced via

Capistrano is a tool that allows you to automatically execute commands on a remote server using SSH. Capistrano works on your personal computer (not on the server) and then access one or several servers (we have configured) via SSH to execute the commands we have set. . Capistrano uses Ruby as a language to write scripts.

Capistrano will require us to provide at least the following:

A Capistrano script, which includes the Capistrano commands that must be executed, as well as which server needs to execute those statements. This script file uses Ruby to write.
One or several configuration files to provide information about the server, as well as how to log in to those servers.

Capistrano can also run commands simultaneously on different servers, which is beneficial when you deploy applications to many different servers.

Workflow

First, of course, we need to install and edit Capistrano on our personal computers (note that it’s a personal computer, not a server).
Every time we need to deploy a new version of the application, we need to:

Commit and push the whole code to git repo (which we provided in Capistrano)
Run the Capistrano deploy command

Recipes:

Capistrano is very useful, but its true strength lies in the recipes that the community builds for it.

For example, if we use capistrano/deploy recipe, it will contain commands that help us automatically git clone , git pull , as well as support for rollback very easily. All we need to do is give Capistrano the URL of git repo.

Or if you want to deploy a rails application, capistrano-rails will help you to run bundle install , compile Rails assets, run db migrate, etc.

Directory structure of Capistrano:

After deploying the app on the server using Capistrano, the directory will have the following structure:

myapp
 ├──  releases
 │       ├── <span class="token number">20150080072500</span>
 │       ├── <span class="token number">20150090083000</span>
 │       ├── <span class="token number">20150100093500</span>
 │       ├── <span class="token number">20150110104000</span>
 │       └── <span class="token number">20150120114500</span>
 │            ├── <span class="token operator">&lt;</span> checked out files from <span class="token constant">Git</span> repository <span class="token operator">&gt;</span>
 │            └── config
 │                 ├──  database <span class="token punctuation">.</span> yml <span class="token operator">-</span> <span class="token operator">&gt;</span> <span class="token operator">/</span> var <span class="token operator">/</span> www <span class="token operator">/</span> myapp <span class="token operator">/</span> shared <span class="token operator">/</span> config <span class="token operator">/</span> database <span class="token punctuation">.</span> yml
 │                 └──  secrets <span class="token punctuation">.</span> yml  <span class="token operator">-</span> <span class="token operator">&gt;</span> <span class="token operator">/</span> var <span class="token operator">/</span> www <span class="token operator">/</span> myapp <span class="token operator">/</span> shared <span class="token operator">/</span> config <span class="token operator">/</span> secrets <span class="token punctuation">.</span> yml
 │
 ├──  current <span class="token operator">-</span> <span class="token operator">&gt;</span> <span class="token operator">/</span> var <span class="token operator">/</span> www <span class="token operator">/</span> myapp <span class="token operator">/</span> releases <span class="token regex">/20150120114500/</span>
 ├──  repo
 │       └── <span class="token operator">&lt;</span> <span class="token constant">VCS</span> related data <span class="token operator">&gt;</span>
 └──  shared
         ├── <span class="token operator">&lt;</span> linked_files <span class="token keyword">and</span> linked_dirs <span class="token operator">&gt;</span>
         └── config
              ├── database <span class="token punctuation">.</span> yml
              └── secrets <span class="token punctuation">.</span> yml

myapp

├── releases

│ ├── 20150080072500

│ ├── 20150090083000

│ ├── 20150100093500

│ ├── 20150110104000

│ └── 20150120114500

│ ├── < checked out files from Git repository >

│ └── config

│ ├── database . yml - > / var / www / myapp / shared / config / database . yml

│ └── secrets . yml - > / var / www / myapp / shared / config / secrets . yml

│

├── current - > / var / www / myapp / releases /20150120114500/

├── repo

│ └── < VCS related data >

└── shared

├── < linked_files and linked_dirs >

└── config

├── database . yml

└── secrets . yml

releases contains all versions of the app, marked with timestamped folders. Every time you tell Capistrano to deploy a new version, Capistrano will clone from the Git repo and save it in a subdirectory of releases .
current a simple current it is a symlink pointing to the latest version contained in releases (based on the timestamp). This symlink only updates when the deploy process is complete, if the deploy process fails at any step, this symlink still points to the previous version.
repo stores a copy of the GIt repo, so that the next time we can pull it back faster.
shared here is a great folder of Capistrano, let me give you an example:

Because Capistrano works by cloning applications from Git, so only files we upload to Git can be cloned. So for example with a Rails application, there are files that we can only keep in the local environment (database.yml, secrets.yml, …), how can we use this? And Capistrano offers a solution, that is, users can configure files, even folders, that can be shared directly between development and production environments (personal computers and servers). These files will always exist no matter how many versions we put up.

To configure shared files and folders, Capistrano provides two configuration options, linked_files and linked_dirs

Install Capistrano

Initialization

First we need to install Capistrano on the Ruby application we are working on. Open Gemfile and add:

group <span class="token symbol">:development</span> <span class="token keyword">do</span>
  gem <span class="token string">'capistrano'</span>
  gem <span class="token string">'capistrano-bundler'</span>
  gem <span class="token string">'capistrano-passenger'</span> <span class="token punctuation">,</span> <span class="token string">'&gt;= 0.1.1'</span>

  <span class="token comment"># Remove the following if your app does not use Rails</span>
  gem <span class="token string">'capistrano-rails'</span>

  <span class="token comment"># Remove the following if your server does not use RVM</span>
  gem <span class="token string">'capistrano-rvm'</span>
<span class="token keyword">end</span>

group :development do

gem 'capistrano'

gem 'capistrano-bundler'

gem 'capistrano-passenger' , '>= 0.1.1'

# Remove the following if your app does not use Rails

gem 'capistrano-rails'

# Remove the following if your server does not use RVM

gem 'capistrano-rvm'

end

Then run 2 commands:

bundle <span class="token function">install</span>

bundle <span class="token function">exec</span> cap <span class="token function">install</span>

bundle install

bundle exec cap install

Edit Capfile:

Capfile is the first place that Capistrano reads, in this file it will define which recipes you want to use.

When you first open Capfile, it will look like this:

<span class="token comment"># Load DSL and set up stages</span>
<span class="token keyword">require</span> <span class="token string">'capistrano/setup'</span>

<span class="token comment"># Include default deployment tasks</span>
<span class="token keyword">require</span> <span class="token string">'capistrano/deploy'</span>

<span class="token comment"># Include tasks from other gems included in your Gemfile</span>
<span class="token comment">#</span>
<span class="token comment"># For documentation on these, see for example:</span>
<span class="token comment">#</span>
<span class="token comment">#   https://github.com/capistrano/rvm</span>
<span class="token comment">#   https://github.com/capistrano/rbenv</span>
<span class="token comment">#   https://github.com/capistrano/chruby</span>
<span class="token comment">#   https://github.com/capistrano/bundler</span>
<span class="token comment">#   https://github.com/capistrano/rails</span>
<span class="token comment">#   https://github.com/capistrano/passenger</span>
<span class="token comment">#</span>
<span class="token comment"># require 'capistrano/rvm'</span>
<span class="token comment"># require 'capistrano/rbenv'</span>
<span class="token comment"># require 'capistrano/chruby'</span>
<span class="token comment"># require 'capistrano/bundler'</span>
<span class="token comment"># require 'capistrano/rails/assets'</span>
<span class="token comment"># require 'capistrano/rails/migrations'</span>
<span class="token comment"># require 'capistrano/passenger'</span>

<span class="token comment"># Load custom tasks from `lib/capistrano/tasks' if you have any defined</span>
<span class="token builtin">Dir</span> <span class="token punctuation">.</span> <span class="token function">glob</span> <span class="token punctuation">(</span> <span class="token string">'lib/capistrano/tasks/*.rake'</span> <span class="token punctuation">)</span> <span class="token punctuation">.</span> <span class="token keyword">each</span> <span class="token punctuation">{</span> <span class="token operator">|</span> r <span class="token operator">|</span> import r <span class="token punctuation">}</span>

# Load DSL and set up stages

require 'capistrano/setup'

# Include default deployment tasks

require 'capistrano/deploy'

# Include tasks from other gems included in your Gemfile

#

# For documentation on these, see for example:

#

# https://github.com/capistrano/rvm

# https://github.com/capistrano/rbenv

# https://github.com/capistrano/chruby

# https://github.com/capistrano/bundler

# https://github.com/capistrano/rails

# https://github.com/capistrano/passenger

#

# require 'capistrano/rvm'

# require 'capistrano/rbenv'

# require 'capistrano/chruby'

# require 'capistrano/bundler'

# require 'capistrano/rails/assets'

# require 'capistrano/rails/migrations'

# require 'capistrano/passenger'

# Load custom tasks from `lib/capistrano/tasks' if you have any defined

Dir . glob ( 'lib/capistrano/tasks/*.rake' ) . each { | r | import r }

It can be seen that the most popular recipes have been commented back here, when we need to use any recipe, just uncomment is done.

Edit the file config / deploy.rb

When opened, this file looks like this:

<span class="token comment"># config valid only for current version of Capistrano</span>
lock <span class="token string">'3.3.5'</span>

set <span class="token symbol">:application</span> <span class="token punctuation">,</span> <span class="token string">'my_app_name'</span>
set <span class="token symbol">:repo_url</span> <span class="token punctuation">,</span> <span class="token string">' <a class="__cf_email__" href="/cdn-cgi/l/email-protection">[email protected]</a> :me/my_repo.git'</span>

<span class="token comment"># Default branch is :master</span>
<span class="token comment"># ask :branch, proc { `git rev-parse --abbrev-ref HEAD`.chomp }.call</span>

<span class="token comment"># Default deploy_to directory is /var/www/my_app_name</span>
<span class="token comment"># set :deploy_to, '/var/www/my_app_name'</span>

<span class="token comment"># Default value for :scm is :git</span>
<span class="token comment"># set :scm, :git</span>

<span class="token comment"># Default value for :format is :pretty</span>
<span class="token comment"># set :format, :pretty</span>

<span class="token comment"># Default value for :log_level is :debug</span>
<span class="token comment"># set :log_level, :debug</span>

<span class="token comment"># Default value for :pty is false</span>
<span class="token comment"># set :pty, true</span>

<span class="token comment"># Default value for :linked_files is []</span>
<span class="token comment"># set :linked_files, fetch(:linked_files, []).push('config/database.yml')</span>

<span class="token comment"># Default value for linked_dirs is []</span>
<span class="token comment"># set :linked_dirs, fetch(:linked_dirs, []).push('bin', 'log', 'tmp/pids', 'tmp/cache', 'tmp/sockets', 'vendor/bundle', 'public/system')</span>

<span class="token comment"># Default value for default_env is {}</span>
<span class="token comment"># set :default_env, { path: "/opt/ruby/bin:$PATH" }</span>

<span class="token comment"># Default value for keep_releases is 5</span>
<span class="token comment"># set :keep_releases, 5</span>

namespace <span class="token symbol">:deploy</span> <span class="token keyword">do</span>

  after <span class="token symbol">:restart</span> <span class="token punctuation">,</span> <span class="token symbol">:clear_cache</span> <span class="token keyword">do</span>
    on <span class="token function">roles</span> <span class="token punctuation">(</span> <span class="token symbol">:web</span> <span class="token punctuation">)</span> <span class="token punctuation">,</span> <span class="token keyword">in</span> <span class="token punctuation">:</span> <span class="token symbol">:groups</span> <span class="token punctuation">,</span> limit <span class="token punctuation">:</span> <span class="token number">3</span> <span class="token punctuation">,</span> wait <span class="token punctuation">:</span> <span class="token number">10</span> <span class="token keyword">do</span>
      <span class="token comment"># Here we can do anything such as:</span>
      <span class="token comment"># within release_path do</span>
      <span class="token comment">#   execute :rake, 'cache:clear'</span>
      <span class="token comment"># end</span>
    <span class="token keyword">end</span>
  <span class="token keyword">end</span>

<span class="token keyword">end</span>

# config valid only for current version of Capistrano

lock '3.3.5'

set :application , 'my_app_name'

set :repo_url , ' <a class="__cf_email__" href="/cdn-cgi/l/email-protection">[email protected]</a> :me/my_repo.git'

# Default branch is :master

# ask :branch, proc { `git rev-parse --abbrev-ref HEAD`.chomp }.call

# Default deploy_to directory is /var/www/my_app_name

# set :deploy_to, '/var/www/my_app_name'

# Default value for :scm is :git

# set :scm, :git

# Default value for :format is :pretty

# set :format, :pretty

# Default value for :log_level is :debug

# set :log_level, :debug

# Default value for :pty is false

# set :pty, true

# Default value for :linked_files is []

# set :linked_files, fetch(:linked_files, []).push('config/database.yml')

# Default value for linked_dirs is []

# set :linked_dirs, fetch(:linked_dirs, []).push('bin', 'log', 'tmp/pids', 'tmp/cache', 'tmp/sockets', 'vendor/bundle', 'public/system')

# Default value for default_env is {}

# set :default_env, { path: "/opt/ruby/bin:$PATH" }

# Default value for keep_releases is 5

# set :keep_releases, 5

namespace :deploy do

after :restart , :clear_cache do

on roles ( :web ) , in : :groups , limit : 3 , wait : 10 do

# Here we can do anything such as:

# within release_path do

# execute :rake, 'cache:clear'

# end

end

First, people will notice in the file that there are many commands that start with set , the set here is the configuration values of Capistrano, used to adjust the settings for Capistrano. It can be seen in the default file that there are many sample examples, explaining the meaning of the command line, you can try uncomment to see the effect of those set lines, or can learn more here .
The second thing we need to keep in mind is the namespace block inside this file. We can use this block to create more commands to handle during deploy. For simple applications, just follow the recipe mentioned above, but for complex applications, we have to add the commands ourselves is completely possible. When the application is deployed, it will have to run through the steps defined in the recipe capistrano/deploy , the steps are as follows:

Clone code about release directory
Install linked file and directory
Run commands like bundle install, db migrate, …
Convert current symlink
Restart the server

As in the example that exists in the file, it means we will create another task with the name :clear_cache after the application runs the restart step (step 5). In this block we can write whatever we want, it’s the same as the callback functions we usually write in the model.

Edit the file config / deploy / production.rb

<span class="token comment"># Simple Role Syntax</span>
<span class="token comment"># ==================</span>
<span class="token comment"># Supports bulk-adding hosts to roles, the primary server in each group</span>
<span class="token comment"># is considered to be the first unless any hosts have the primary</span>
<span class="token comment"># property set.  Don't declare `role :all`, it's a meta role.</span>

role <span class="token symbol">:app</span> <span class="token punctuation">,</span> <span class="token string">%w{ <a class="__cf_email__" href="/cdn-cgi/l/email-protection">[email protected]</a> }</span>
role <span class="token symbol">:web</span> <span class="token punctuation">,</span> <span class="token string">%w{ <a class="__cf_email__" href="/cdn-cgi/l/email-protection">[email protected]</a> }</span>
role <span class="token symbol">:db</span> <span class="token punctuation">,</span>  <span class="token string">%w{ <a class="__cf_email__" href="/cdn-cgi/l/email-protection">[email protected]</a> }</span>


<span class="token comment"># Extended Server Syntax</span>
<span class="token comment"># ======================</span>
<span class="token comment"># This can be used to drop a more detailed server definition into the</span>
<span class="token comment"># server list. The second argument is a, or duck-types, Hash and is</span>
<span class="token comment"># used to set extended properties on the server.</span>

server <span class="token string">'example.com'</span> <span class="token punctuation">,</span> user <span class="token punctuation">:</span> <span class="token string">'deploy'</span> <span class="token punctuation">,</span> roles <span class="token punctuation">:</span> <span class="token string">%w{web app}</span> <span class="token punctuation">,</span> my_property <span class="token punctuation">:</span> <span class="token symbol">:my_value</span>


<span class="token comment"># Custom SSH Options</span>
<span class="token comment"># ==================</span>
<span class="token comment"># You may pass any option but keep in mind that net/ssh understands a</span>
<span class="token comment"># limited set of options, consult[net/ssh documentation](http://net-ssh.github.io/net-ssh/classes/Net/SSH.html#method-c-start).</span>
<span class="token comment">#</span>
<span class="token comment"># Global options</span>
<span class="token comment"># --------------</span>
<span class="token comment">#  set :ssh_options, {</span>
<span class="token comment">#    keys: %w(/home/rlisowski/.ssh/id_rsa),</span>
<span class="token comment">#    forward_agent: false,</span>
<span class="token comment">#    auth_methods: %w(password)</span>
<span class="token comment">#  }</span>
<span class="token comment">#</span>
<span class="token comment"># And/or per server (overrides global)</span>
<span class="token comment"># ------------------------------------</span>
<span class="token comment"># server 'example.com',</span>
<span class="token comment">#   user: 'user_name',</span>
<span class="token comment">#   roles: %w{web app},</span>
<span class="token comment">#   ssh_options: {</span>
<span class="token comment">#     user: 'user_name', # overrides user setting above</span>
<span class="token comment">#     keys: %w(/home/user_name/.ssh/id_rsa),</span>
<span class="token comment">#     forward_agent: false,</span>
<span class="token comment">#     auth_methods: %w(publickey password)</span>
<span class="token comment">#     # password: 'please use keys'</span>
<span class="token comment">#   }</span>

# Simple Role Syntax

# ==================

# Supports bulk-adding hosts to roles, the primary server in each group

# is considered to be the first unless any hosts have the primary

# property set. Don't declare `role :all`, it's a meta role.

role :app , %w{ <a class="__cf_email__" href="/cdn-cgi/l/email-protection">[email protected]</a> }

role :web , %w{ <a class="__cf_email__" href="/cdn-cgi/l/email-protection">[email protected]</a> }

role :db , %w{ <a class="__cf_email__" href="/cdn-cgi/l/email-protection">[email protected]</a> }

# Extended Server Syntax

# ======================

# This can be used to drop a more detailed server definition into the

# server list. The second argument is a, or duck-types, Hash and is

# used to set extended properties on the server.

server 'example.com' , user : 'deploy' , roles : %w{web app} , my_property : :my_value

# Custom SSH Options

# ==================

# You may pass any option but keep in mind that net/ssh understands a

# limited set of options, consult[net/ssh documentation](http://net-ssh.github.io/net-ssh/classes/Net/SSH.html#method-c-start).

#

# Global options

# --------------

# set :ssh_options, {

# keys: %w(/home/rlisowski/.ssh/id_rsa),

# forward_agent: false,

# auth_methods: %w(password)

# }

#

# And/or per server (overrides global)

# ------------------------------------

# server 'example.com',

# user: 'user_name',

# roles: %w{web app},

# ssh_options: {

# user: 'user_name', # overrides user setting above

# keys: %w(/home/user_name/.ssh/id_rsa),

# forward_agent: false,

# auth_methods: %w(publickey password)

# # password: 'please use keys'

# }

This file is used to indicate which servers that Capistrano will run the command to deploy to. As you can see in the file, there are two main ways to specify servers as well as how to log into those servers.

The first is to use 1 global config for all servers. This means that our servers all use the same rsa code to log in via ssh from the local machine.
The second way is if any server uses a different rsa code from the rest of the servers, we can define that server separately.

References

https://www.phusionpassenger.com/library/deploy/standalone/automating_app_updates/ruby/

Share the news now

Source : Viblo