Ruby capistrano

From wikinotes

Capistrano is a framework for managing server deployments over SSH (in parallel).
It is commonly used to deploy rails apps to production.

It combines the ruby rake Rakefile DSL, with ruby sshkit to configure deploy instructions.

Documentation

github https://github.com/capistrano/capistrano
homepage https://capistranorb.com/
set options https://capistranorb.com/documentation/getting-started/configuration/
rubygems https://rubygems.org/gems/capistrano/versions/3.14.1

Source

deploy.rake https://github.com/capistrano/capistrano/blob/master/lib/capistrano/tasks/deploy.rake

Tutorials

guide https://docs.lucee.org/guides/Various/deploy-with-capistrano.html

Locations

${project}/Capfile ?
${project}/deploy.rb config (shared by all environments)
${project}/config/deploy/{production,staging}.rb per-environment configs

Extensions

Capistrano SSHkit https://github.com/capistrano/sshkit
Capistrano rails https://github.com/capistrano/rails

Usage

cap production deploy           # deploy a server
cap production deploy:rollback  # revert a deployment

Basics

The general workflow for capistrano is to encapsulate your configuration in a plugin,
then require/configure it in your capfile.

The available SSHKit CommandMaps etc. will be configured by the plugins that you decide to include.

Capfile

The capfile initializes capistrano,
defines capistrano plugins that will be in scope,
project-specific rakefiles you'd like to make available,
etc.

# ${PROJECT}/Capfile

# load DSL
require 'capistrano/setup'

# include/configure plugins
require 'capistrano/rails'

require 'capistrano/setup'
install_plugin Capistrano::Sidekiq
install_plugin Capistrano::Sidekiq::Systemd

# define available rakefiles
Dir.glob('lib/capistrano/tasks/*.rake').each { |rakefile| import rakefile }

Deployment Rakefiles

Deployments are described using ruby rake Rakefiles.
At the root of your project, a deploy.rb contains tasks executed within your deployment.

  • Configure capistrano options using set
  • The target environment of a deployment tasks is defined by the namespace (?).
  • Deployment is configured in rake tasks
  • Tasks use execute(), which uses SSHKit on the backend (map of process, to it's absolute path on the remote server)
# ${PROJECT}/deploy.rb

# configure capistrano options
set(:application, "my-project")
set(:deploy_to, "/usr/local/www/#{fetch(:application)}")

# commands executed over SSH using SSHKit
namespace :deploy do
  desc "Start Webserver"
  task :start_nginx do
    execute("service nginx start")  # executed over SSH
  end

  desc "Start Rails App"
  task :start_rails do
    execute("service rails start")
  end
end

# before/after deployment-stage hooks
before(...)
after(...)

Deployment

Version Locks

Syntax

Options

Capistrano allows you to configure your deployment using options.

# ${project}/deploy.rb

set(:application, "my-awesome-project")
set(:deploy_to, "/usr/local/www/#{fetch(:application)}"

Ask

You can get user input using ask.

Tasks

These are the ruby rake tasks that are performed as during deployment.
Typically, they are expressed as ruby sshkit execute functions.

desc "do thing"
task :thing do
  execute(:bundle, :install)
  execute('bundle install')
end

Roles/Servers

TODO:

What do these do?

server 'example.com', 
  roles [:web], 
  user: 'me', 
  port: 1234

Rollbacks