Lightweight command line server selection for capistrano. Rather than having to blast a task across all servers with a given role or as with multistage having to group all of your servers into separate files ahead of time. With this package you can pick groups or sub groups of servers or even individual servers to execute tasks on via the command line. For example:

$ cap @:projectx:production:app:1 app:install_bundler
$ cap @:projectx:all server:deploy_authorized_keys USERS='john_doe jane_doe'
$ cap @:all nagios:nrpe:deploy

From a config file perspective the only new functionality is the scope.server and scope.role methods. From a command line persective all that has been added is the @: namespace which contains all the server scope tasks.

require 'capistrano/scope'

# Optional variable.  It'll use this one if none is specified on the command line.
set :default_scope, '@:projectx:staging:all'

The order you specify servers or roles doesn’t matter, you can define scope.role for a server before you define scope.server or visa versa. You can give servers any name you like but they are broken into logical groups by using the “:” separator.

scope.server 'projectx:staging:lb:1', '123.456.567.1'
scope.server 'projectx:staging:app:1', '123.456.567.3'
scope.server 'projectx:staging:app:2', '123.456.567.4'
scope.server 'projectx:staging:db:1', '123.456.567.5'

scope.server 'projectx:production:lb:1', '123.456.567.7'
scope.server 'projectx:production:app:1', '123.456.567.9'
scope.server 'projectx:production:app:2', '123.456.567.10'
scope.server 'projectx:production:app:3', '123.456.567.10'
scope.server 'projectx:production:db:1', '123.456.567.12'

scope.role :load_balancer, 'projectx:staging:lb:1'
scope.role :load_balancer, 'projectx:production:lb:1'

scope.role :app, 'projectx:staging:app:1'
scope.role :app, 'projectx:staging:app:2'
scope.role :app, 'projectx:production:app:1'
scope.role :app, 'projectx:production:app:2'

scope.role :db, 'projectx:staging:db:1', :primary => true
scope.role :db, 'projectx:production:db:1', :primary => true

For the sake of demonstration lets assume we also have the following tasks defined and included from somewhere else.

namespace :server do
  desc "Concatenate Keys and upload new authorized_keys file to the server."
  task :authorized_keys do
    ...
  end

  desc "Install Subversion"
  task :install_subversion do
    ...
  end
end

namespace :mysql do
  desc "Backup Database"
  task :backup, :roles => :db do
    ...
  end
end

namespace :app do
  desc "Install bundler"
  task :install_bundler, :roles => :app do
    ...
  end

  desc "Install nginx"
  task :install_nginx, :roles => :app do
    ...
  end

  desc "Install imagemagick"
  task :install_imagemagick, :roles => :app do
    ...
  end
end

namespace :nagios do
  desc "Update nagios config on the admin server and restart nagios service"
  task :deploy, :roles => :admin do
    ...
  end

  desc "Restart the nagios SMF Service"
  task :restart, :roles => :admin do
    ...
  end

  namespace :nrpe do
    desc "Install NRPE"
    task :install, :roles => :server do
      ...
    end

    desc "Update NRPE Configuration"
    task :deploy, :roles => :server do
      ...
    end
  end

  namespace :plugins do
    desc "Copy plugins to servers"
    task :deploy, :roles => :server do
      ...
    end
  end
end

# end of recipes.rb

Now on the command line you can see the tasks that you normally would by listing out tasks with descriptions.

$ cap -T

cap @:all                                       # Scope all defined servers
cap @:show                                      # Show the roles and servers ...
cap app:install_bundler
cap app:install_nginx
cap app:install_image_magick
cap mysql:backup
cap nagios:deploy
cap nagios:restart
cap nagios:nrpe:install
cap nagios:nrpe:deploy
cap nagios:plugins:deploy
cap server:authorized_keys
cap server:install_subversion

And if you want to see a list of all the server scopes that you have defined use the verbose flag. Since we used the ‘@’ as the top level namespace for our scoping tasks they should all sort to the top of the list and then be followed by your normal capistrano tasks.

$ cap -vT

cap @:all                                       # Scope all defined servers
cap @:clienta:all                               # 
cap @:clienta:projectx:all                      # 
cap @:clienta:projectx:production:all           # 
cap @:clienta:projectx:production:app:1         # 
cap @:clienta:projectx:production:app:2         # 
cap @:clienta:projectx:production:app:all       # 
cap @:clienta:projectx:production:db:1          # 
cap @:clienta:projectx:production:db:2          # 
cap @:clienta:projectx:production:db:all        # 
cap @:clienta:projectx:production:lb:1          # 
cap @:clienta:projectx:production:lb:2          # 
cap @:clienta:projectx:production:lb:all        # 
cap @:clienta:projectx:staging:all              # 
cap @:clienta:projectx:staging:app:1            # 
cap @:clienta:projectx:staging:app:2            # 
cap @:clienta:projectx:staging:app:all          # 
cap @:clienta:projectx:staging:db:1             # 
cap @:clienta:projectx:staging:db:2             # 
cap @:clienta:projectx:staging:db:all           # 
cap @:clienta:projectx:staging:lb:1             # 
cap @:clienta:projectx:staging:lb:2             # 
cap @:clienta:projectx:staging:lb:all           # 
cap @:create_role_tasks                         # 
cap @:show                                      # Show the roles and servers ...
cap app:install_bundler
cap app:install_nginx
cap app:install_image_magick
cap mysql:backup
cap nagios:deploy
cap nagios:restart
cap nagios:nrpe:install
cap nagios:nrpe:deploy
cap nagios:plugins:deploy
cap server:authorized_keys
cap server:install_subversion

Now to execute a task on a single server you can precede the task with the scope task for that server.

$ cap @:clienta:projectx:production:app:1 app:install_bundler

Or if you want to execute that task on a group of servers you can use the all task that is defined for you at each level.

$ cap @:clienta:projectx:production:app:all

Since we have added roles to our tasks and servers we can still execute tasks on larger groups of servers that include servers that we don’t want the command to run on. Because the task is role based it will only execute the task on the correct servers.

For example if we wanted to install nginx on all app servers of clientx but not clienty we could do this:

$ cap @:clientx:all app:install_nginx

And if we really wanted to go global we can execute something across all servers with the @:all scope. Lets say we want to deploy they updated nrpe config file and a new plugin we wrote to all our servers.

$ cap @:all nagios:nrpe:deploy nagios:plugins:deploy

Included with this package is a @:show task that will list out all the servers and roles that are defined for a given scope.

$ cap @:clienta:projectx:all @:show

    triggering load callbacks
  * executing `@:create_role_tasks'
  * executing `@:clienta:projectx:all'
  * executing `@:show'
Roles:
         app
         db
         load_balancer
Servers:
         clienta:projectx:production:app:1
         clienta:projectx:production:app:2
         clienta:projectx:production:db:1
         clienta:projectx:production:db:2
         clienta:projectx:staging:app:1
         clienta:projectx:staging:app:2
         clienta:projectx:staging:db:2

$ cap @:clienta:projectx:staging:db:all @:show

    triggering load callbacks
  * executing `@:create_role_tasks'
  * executing `@:clienta:projectx:staging:db:all'
  * executing `@:show'
Roles:
         db
Servers:
         clienta:projectx:staging:db:2

Note: if you’re using this with multi-stage, include capistrano-scope after the multi-stage include. A nifty way to give you the individual server functionality of capistrano-scope and the easy stage deployment of multi-stage would be to put all your server definitions into a globally included config file and then put your variable definitions and set a :default_scope in each multi-stage config file.

The implementation behind this is simple. When the configuration is loaded it generates tasks for each server and server group in memory. Each of these tasks is not much more than a list of capistrano server and role method calls. When you call one of the scope tasks from the command line the task executes and the roles and servers are defined just in time for the next task on the command line to execute on them.