Before we start lets create minimal recipe.<\/p>\n\n\n\n
Bootstrap<\/h3>\n\n\n\n$ gem install capistrano\n$ mkdir test\n$ cd test\n$ capify .<\/pre>\n\n\n\nCapistrano loads only two standard recipes by default:<\/p>\n\n\n\n
$ cap -T\ncap invoke # Invoke a single command on the remote servers.\ncap shell # Begin an interactive Capistrano session.<\/pre>\n\n\n\nLet’s create our own simple configuration from scratch. Before we choose good server names! :)
![\"servers\"](\"\/\/upload.wikimedia.org\/wikipedia\/en\/thumb\/9\/9f\/Reservoirdog.jpg\/300px-Reservoirdog.jpg\")
<\/p>\n\n\n\n
Assume we have several servers with following DNS names:<\/p>\n\n\n\n
- mr-white.reservoir.dogs<\/li>
- mr-orange.reservoir.dogs<\/li>
- mr-blonde.reservoir.dogs<\/li><\/ul>\n\n\n\n
Lets give our servers some roles at config\/deploy.rb<\/em>:<\/p>\n\n\n\n role :dog, 'mr-white.reservoir.dogs', 'mr-orange.reservoir.dogs', 'mr-blonde.reservoir.dogs'\n role :boss, 'mr-white.reservoir.dogs'\n role :nerd, 'mr-orange.reservoir.dogs', 'mr-blonde.reservoir.dogs'<\/pre>\n\n\n\nAlternatively you may declare it with server<\/em> option:<\/p>\n\n\n\n server 'mr-white.reservoir.dogs', :dog, :boss\n server 'mr-orange.reservoir.dogs', :dog, :nerd\n server 'mr-blonde.reservoir.dogs', :dog, :nerd<\/pre>\n\n\n\n\n\n\n\nCommand invocation<\/h3>\n\n\n\n
Capistrano has a simple recipe:<\/p>\n\n\n\n
cap invoke # Invoke a single command on the remote servers.<\/pre>\n\n\n\nLet’s ask servers about current date:<\/p>\n\n\n\n
$ cap invoke COMMAND=date\n * executing `invoke'\n * executing \"date\"\n servers: [\"mr-white.reservoir.dogs\", \"mr-orange.reservoir.dogs\", \"mr-blonde.reservoir.dogs\"]\n [mr-white.reservoir.dogs] executing command\n [mr-orange.reservoir.dogs] executing command\n [mr-blonde.reservoir.dogs] executing command\n ** [out :: mr-white.reservoir.dogs] Fri Oct 28 10:23:50 EDT 2011\n ** [out :: mr-orange.reservoir.dogs] Fri Oct 28 10:23:50 EDT 2011\n ** [out :: mr-blonde.reservoir.dogs] Fri Oct 28 10:23:50 EDT 2011\n command finished in 614ms<\/pre>\n\n\n\nRunning a task<\/h3>\n\n\n\n
Let’s create dead simple task that will show the date. Add following to your config\/deploy.rb<\/em>:<\/p>\n\n\n\n desc \"Show server' date\"\n task :show_date do\n run('date')\n end<\/pre>\n\n\n\nLook for our newly created task in the tasks list:<\/p>\n\n\n\n
$ cap -T\ncap invoke # Invoke a single command on the remote servers.\ncap shell # Begin an interactive Capistrano session.\ncap show_date # Show server' date<\/pre>\n\n\n\nLet’s play:<\/p>\n\n\n\n
$ cap show_date\n * executing `show_date'\n * executing \"date\"\n servers: [\"mr-white.reservoir.dogs\", \"mr-orange.reservoir.dogs\", \"mr-blonde.reservoir.dogs\"]\n ** [out :: mr-white.reservoir.dogs] Fri Oct 28 10:23:50 EDT 2011\n ** [out :: mr-orange.reservoir.dogs] Fri Oct 28 10:23:50 EDT 2011\n ** [out :: mr-blonde.reservoir.dogs] Fri Oct 28 10:23:50 EDT 2011<\/pre>\n\n\n\nSo with such configuration task will be executed on all defined servers.<\/p>\n\n\n\n
But what if we want to run the task always only for specific role? Configure it as:<\/p>\n\n\n\n
desc \"Show server' date\"\n task :show_date, :roles => [:nerd] do\n run('date')\n end<\/pre>\n\n\n\nAnd it will be executed as expected:<\/p>\n\n\n\n
$ cap show_date\n * executing `show_date'\n * executing \"date\"\n servers: [\"mr-orange.reservoir.dogs\", \"mr-blonde.reservoir.dogs\"]\n ** [out :: mr-orange.reservoir.dogs] Fri Oct 28 10:23:50 EDT 2011\n ** [out :: mr-blonde.reservoir.dogs] Fri Oct 28 10:23:50 EDT 2011<\/pre>\n\n\n\nEnvironment Variables<\/h3>\n\n\n\n
Capistrano reacts on four special environment variables that allow you to change server definitions temporary. Let’s read about it from capistrano help:<\/p>\n\n\n\n
$ cap -H\n\n HOSTS\n Execute the tasks against this comma-separated list of hosts.\n Effectively, this makes the host(s) part of every roles.\n\n HOSTFILTER\n Execute tasks against this comma-separated list of host, but only if the\n host has the proper role for the task.\n\n HOSTROLEFILTER\n Execute tasks against the hosts in this comma-separated list of roles,\n but only if the host has the proper role for the task.\n\n ROLES\n Execute tasks against this comma-separated list of roles. Hosts which\n do not have the right roles will be skipped.<\/pre>\n\n\n\nLet’s define task that should be executed on servers with :nerd<\/em> role<\/p>\n\n\n\n desc \"Show server' date\"\n task :show_date, :roles => [:nerd] do\n run('date')\n end<\/pre>\n\n\n\nHOSTS Variable<\/h4>\n\n\n\n
Let’s run task with following HOSTS:<\/p>\n\n\n\n
$ cap show_date HOSTS=mr-white.reservoir.dogs,mr-orange.reservoir.dogs\n * executing `show_date'\n * executing \"date\"\n servers: [\"mr-white.reservoir.dogs\", \"mr-orange.reservoir.dogs\"]\n...<\/pre>\n\n\n\nSo command is executed on explicitly specified servers.<\/p>\n\n\n\n
But it’s not limited to hosts specified in configuration:<\/p>\n\n\n\n
cap show_date HOSTS=mr-white.reservoir.dogs,google.com\n * executing `show_date'\n * executing \"date\"\n servers: [\"mr-white.reservoir.dogs\", \"google.com\"]\n...<\/pre>\n\n\n\nSo HOSTS variable overrides<\/em> server definitions.<\/p>\n\n\n\nROLES Variable<\/h4>\n\n\n\n
Let’s run a task with another role:<\/p>\n\n\n\n
$ cap show_date ROLES=boss\n * executing `show_date'\n * executing \"date\"\n servers: [\"mr-white.reservoir.dogs\"]\n...<\/pre>\n\n\n\nSo ROLES variable also overrides<\/em> server definitions.<\/p>\n\n\n\nHOSTFILTER Variable<\/h4>\n\n\n\n
Hosts from HOSTFILTER variable are excluded from servers list for certain task:<\/p>\n\n\n\n
$ cap show_date HOSTFILTER=mr-orange.reservoir.dogs,google.com\n * executing `show_date'\n * executing \"date\"\n servers: [\"mr-orange.reservoir.dogs\"]\n...<\/pre>\n\n\n\nSo it filters<\/em> servers, but does not override<\/em> servers configured for task.<\/p>\n\n\n\nHOSTROLEFILTER Variable<\/h4>\n\n\n\n
Let’s try to filter servers with another role:<\/p>\n\n\n\n
$ cap show_date HOSTROLEFILTER=boss\n * executing `show_date'\n * executing \"date\"\n`show_date' is only run for servers matching {:roles=>:nerd}, but no servers matched<\/pre>\n\n\n\nSo it also excludes hosts from the servers list for certain task.<\/p>\n\n\n\n
For example if we have following task configuration:<\/p>\n\n\n\n
task :show_date, :roles => [:app, :db, :www, :backup] do\n ...\n end<\/pre>\n\n\n\nThen the command<\/p>\n\n\n\n
$ cap show_date HOSTROLEFILTER=db,www,another_role<\/pre>\n\n\n\nwill be executed only<\/em> on servers that have :db<\/em> and :www<\/em> role.<\/p>\n\n\n\nSo let’s summarize:<\/p>\n\n\n\n
- HOSTS and ROLES variables override<\/em> server definitions.<\/li>
- HOSTFILTER and HOSTROLEFILTER variables filter<\/em> servers.<\/li><\/ul>\n\n\n\n
Thus it’s safe to use HOSTFILTER and HOSTROLEFILTER variables.<\/p>\n\n\n\n
Advanced Server Definitions<\/h3>\n\n\n\nRunning command with custom options<\/h4>\n\n\n\n
Probably you don’t know that run<\/em> command accepts the same options as that task itself. So it’s possible to write complex things like this:<\/p>\n\n\n\ntask :shoot do\n run \"date\"\n run \"uname\", :roles => :boss\n run \"whoami\", :roles => :nerd\nend<\/pre>\n\n\n\n$ cap shoot\n * executing `shoot'\n * executing \"date\"\n servers: [\"mr-white.reservoir.dogs\", \"mr-orange.reservoir.dogs\", \"mr-blonde.reservoir.dogs\"]\n [mr-orange.reservoir.dogs] executing command\n [mr-white.reservoir.dogs] executing command\n [mr-blonde.reservoir.dogs] executing command\n ** [out :: mr-white.reservoir.dogs] Fri Oct 28 12:00:19 EDT 2011\n ** [out :: mr-orange.reservoir.dogs] Fri Oct 28 12:00:19 EDT 2011\n ** [out :: mr-blonde.reservoir.dogs] Fri Oct 28 12:00:19 EDT 2011\n command finished in 737ms\n * executing \"uname\"\n servers: [\"mr-white.reservoir.dogs\"]\n [mr-white.reservoir.dogs] executing command\n ** [out :: mr-white.reservoir.dogs] Linux\n command finished in 479ms\n * executing \"whoami\"\n servers: [\"mr-orange.reservoir.dogs\", \"mr-blonde.reservoir.dogs\"]\n [mr-orange.reservoir.dogs] executing command\n [mr-blonde.reservoir.dogs] executing command\n ** [out :: mr-orange.reservoir.dogs] mongrel\n ** [out :: mr-blonde.reservoir.dogs] mongrel\n command finished in 746ms<\/pre>\n\n\n\nSo date<\/code> is executed on all servers. And uname<\/code> and whoami<\/code> only on corresponding servers.<\/p>\n\n\n\nTask :roles and :hosts options<\/h4>\n\n\n\n
If you’ve read Capistrano source code, you may find yet another nifty option called :hosts<\/em> there.
How does it differ from :roles options? Firstly, :hosts option have higher priority over :roles. Secondary, you always create new server definition object that is not in global<\/em> server list by specifying server via :hosts options. It means such server won’t be affected with tasks that does not have a role.
It’s really nice option because sometimes you want to execute some commands (notifications for example) on certain hosts that are actually not a target for the code delivery.<\/p>\n\n\n\ntask :log_deploy, :hosts => ['history.reservoir.dogs'] do\n run \"cat '#{Time.now},#{real_revision}' >> deploy.log\"\nend<\/pre>\n\n\n\nSpecifying alternative server options<\/h4>\n\n\n\n
Sometimes you need to specify special server options like username, port, ssh key for each of your servers. And it’s pretty easy when your servers are defined globally:<\/p>\n\n\n\n
role :app, 'app1.reservoir.dogs', 'app2.reservoir.dogs', {\n :user => 'nerd',\n :ssh_options => {\n :keys => '.\/keys\/nerd.pem'\n }\n}\n\nrole :db, 'db.reservoir.dogs', {\n :user => 'boss',\n :ssh_options => {\n :keys => '.\/keys\/boss.pem'\n }\n}<\/pre>\n\n\n\nalternatively you may declare it with server<\/em> option:<\/p>\n\n\n\nserver 'app1.reservoir.dogs', :app, {\n :user => 'nerd1',\n :ssh_options => {\n :keys => '.\/keys\/nerd.pem'\n }\n}\n\nserver 'app2.reservoir.dogs', :app {\n :user => 'nerd2',\n :ssh_options => {\n :keys => '.\/keys\/nerd.pem'\n }\n}\n\nserver 'db.reservoir.dogs', :db {\n :user => 'boss',\n :ssh_options => {\n :keys => '.\/keys\/boss.pem'\n }\n}<\/pre>\n\n\n\nSpecifying some server options in task<\/h4>\n\n\n\n
There is no problem if you use :roles in your task or run<\/em> method. But what about :hosts task\/run options?
At the first look there is an issue because :hosts option is an array of servers name.
But there is a trick available! Look at Capistrano::ServerDefinition<\/a><\/p>\n\n\n\nmodule Capistrano\n class ServerDefinition\n def initialize(string, options={})\n @user, @host, @port = string.match(\/^(?:([^;,:=]+)@|)(.*?)(?::(\\d+)|)$\/)[1,3]\n ...\n end\n end\nend<\/pre>\n\n\n\nSo solution is simple:<\/p>\n\n\n\n
run(\"date\", :hosts => ['nerd1@app1.reservoir.dogs:2201', 'nerd2@app1.reservoir.dogs:2201'])\n\ntask(:show_date, :hosts => ['nerd1@app1.reservoir.dogs:2201', 'nerd2@app1.reservoir.dogs:2201']) do\n run(\"date\")\nend\n<\/pre>\n\n\n\nSo you know how to specify alternative :user<\/em> and :port<\/em> options. But what about another server definition options e.g. ssh_options ?<\/p>\n\n\n\nSpecifying any server options in task<\/h4>\n\n\n\n
Do we need to hack find_servers<\/a> to pass specific :ssh_options for server defined in task? No! recently we found simple solution without hacking: look at server_list_from<\/a><\/p>\n\n\n\n def server_list_from(hosts)\n hosts = hosts.split(\/,\/) if String === hosts\n hosts = build_list(hosts)\n hosts.map { |s| String === s ? ServerDefinition.new(s.strip) : s }\n end<\/pre>\n\n\n\nSo we can pass in :hosts<\/em> options array of ServerDefinition<\/em> objects! So solution looks like this:<\/p>\n\n\n\nrun(\"date\", :hosts => [\n Capistrano::ServerDefinition.new('app1.reservoir.dogs', {\n :user => 'nerd1',\n :port => 2201,\n :ssh_options => {\n :keys => '.\/keys\/nerd.pem'\n }\n }),\n Capistrano::ServerDefinition.new('app2.reservoir.dogs', {\n :user => 'nerd2',\n :port => 2202,\n :ssh_options => {\n :keys => '.\/keys\/nerd.pem'\n }\n })\n])\n\ntask(:show_date, :hosts => [\n Capistrano::ServerDefinition.new('app1.reservoir.dogs', {\n :user => 'nerd1',\n :port => 2201,\n :ssh_options => {\n :keys => '.\/keys\/nerd.pem'\n }\n }),\n Capistrano::ServerDefinition.new('app2.reservoir.dogs', {\n :user => 'nerd2',\n :port => 2202,\n :ssh_options => {\n :keys => '.\/keys\/nerd.pem'\n }\n })\n]) do\n run(\"date\")\nend\n<\/pre>\n\n\n\nIt is better to define servers as task\/run options:<\/p>\n\n\n\n
set(:boss_host, {\n Capistrano::ServerDefinition.new('boss.reservoir.dogs', {\n :user => 'boss',\n :port => 2222,\n :ssh_options => {\n :keys => '.\/keys\/boss.pem'\n }\n})\n\nrun(\"date\", :hosts => [ :boss_host ]<\/pre>\n\n\n\nCapistrate the world!<\/h3>\n\n\n\n
We hope this article will help you to use Capistrano more efficiently.<\/p>\n","protected":false},"excerpt":{"rendered":"
What if you have several servers with different users, ssh-keys, and even port numbers? How to manage all this stuff flexibly ? This tutorial covers poorly documented Capistrano features for advanced servers and roles configuration. Many of them obtained via digging into Capistrano sources. This article covers following Capistrano topics: roles configurationserver configurationThe way HOSTS,…<\/p>\n","protected":false},"author":19,"featured_media":9438,"comment_status":"open","ping_status":"open","sticky":false,"template":"","format":"standard","meta":{"_acf_changed":false,"footnotes":""},"categories":[3],"tags":[],"coauthors":["Andriy Yanko"],"class_list":["post-887","post","type-post","status-publish","format-standard","has-post-thumbnail","hentry","category-development"],"acf":[],"aioseo_notices":[],"categories_data":[{"name":"Engineering","link":"https:\/\/railsware.com\/blog?category=development"}],"post_thumbnails":"\/\/upload.wikimedia.org\/wikipedia\/en\/thumb\/9\/9f\/Reservoirdog.jpg\/300px-Reservoirdog.jpg","amp_enabled":true,"_links":{"self":[{"href":"https:\/\/railsware.com\/blog\/wp-json\/wp\/v2\/posts\/887","targetHints":{"allow":["GET"]}}],"collection":[{"href":"https:\/\/railsware.com\/blog\/wp-json\/wp\/v2\/posts"}],"about":[{"href":"https:\/\/railsware.com\/blog\/wp-json\/wp\/v2\/types\/post"}],"author":[{"embeddable":true,"href":"https:\/\/railsware.com\/blog\/wp-json\/wp\/v2\/users\/19"}],"replies":[{"embeddable":true,"href":"https:\/\/railsware.com\/blog\/wp-json\/wp\/v2\/comments?post=887"}],"version-history":[{"count":53,"href":"https:\/\/railsware.com\/blog\/wp-json\/wp\/v2\/posts\/887\/revisions"}],"predecessor-version":[{"id":14016,"href":"https:\/\/railsware.com\/blog\/wp-json\/wp\/v2\/posts\/887\/revisions\/14016"}],"wp:featuredmedia":[{"embeddable":true,"href":"https:\/\/railsware.com\/blog\/wp-json\/wp\/v2\/media\/9438"}],"wp:attachment":[{"href":"https:\/\/railsware.com\/blog\/wp-json\/wp\/v2\/media?parent=887"}],"wp:term":[{"taxonomy":"category","embeddable":true,"href":"https:\/\/railsware.com\/blog\/wp-json\/wp\/v2\/categories?post=887"},{"taxonomy":"post_tag","embeddable":true,"href":"https:\/\/railsware.com\/blog\/wp-json\/wp\/v2\/tags?post=887"},{"taxonomy":"author","embeddable":true,"href":"https:\/\/railsware.com\/blog\/wp-json\/wp\/v2\/coauthors?post=887"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}
Capistrano loads only two standard recipes by default:<\/p>\n\n\n\n
$ cap -T\ncap invoke # Invoke a single command on the remote servers.\ncap shell # Begin an interactive Capistrano session.<\/pre>\n\n\n\nLet’s create our own simple configuration from scratch. Before we choose good server names! :)
Assume we have several servers with following DNS names:<\/p>\n\n\n\n
Lets give our servers some roles at config\/deploy.rb<\/em>:<\/p>\n\n\n\n Alternatively you may declare it with server<\/em> option:<\/p>\n\n\n\n Capistrano has a simple recipe:<\/p>\n\n\n\n Let’s ask servers about current date:<\/p>\n\n\n\n Let’s create dead simple task that will show the date. Add following to your config\/deploy.rb<\/em>:<\/p>\n\n\n\n Look for our newly created task in the tasks list:<\/p>\n\n\n\n Let’s play:<\/p>\n\n\n\n So with such configuration task will be executed on all defined servers.<\/p>\n\n\n\n But what if we want to run the task always only for specific role? Configure it as:<\/p>\n\n\n\n And it will be executed as expected:<\/p>\n\n\n\n Capistrano reacts on four special environment variables that allow you to change server definitions temporary. Let’s read about it from capistrano help:<\/p>\n\n\n\n Let’s define task that should be executed on servers with :nerd<\/em> role<\/p>\n\n\n\n Let’s run task with following HOSTS:<\/p>\n\n\n\n So command is executed on explicitly specified servers.<\/p>\n\n\n\n But it’s not limited to hosts specified in configuration:<\/p>\n\n\n\n So HOSTS variable overrides<\/em> server definitions.<\/p>\n\n\n\n Let’s run a task with another role:<\/p>\n\n\n\n So ROLES variable also overrides<\/em> server definitions.<\/p>\n\n\n\n Hosts from HOSTFILTER variable are excluded from servers list for certain task:<\/p>\n\n\n\n So it filters<\/em> servers, but does not override<\/em> servers configured for task.<\/p>\n\n\n\n Let’s try to filter servers with another role:<\/p>\n\n\n\n So it also excludes hosts from the servers list for certain task.<\/p>\n\n\n\n For example if we have following task configuration:<\/p>\n\n\n\n Then the command<\/p>\n\n\n\n will be executed only<\/em> on servers that have :db<\/em> and :www<\/em> role.<\/p>\n\n\n\n So let’s summarize:<\/p>\n\n\n\n Thus it’s safe to use HOSTFILTER and HOSTROLEFILTER variables.<\/p>\n\n\n\n Probably you don’t know that run<\/em> command accepts the same options as that task itself. So it’s possible to write complex things like this:<\/p>\n\n\n\n So If you’ve read Capistrano source code, you may find yet another nifty option called :hosts<\/em> there. Sometimes you need to specify special server options like username, port, ssh key for each of your servers. And it’s pretty easy when your servers are defined globally:<\/p>\n\n\n\n alternatively you may declare it with server<\/em> option:<\/p>\n\n\n\n There is no problem if you use :roles in your task or run<\/em> method. But what about :hosts task\/run options? So solution is simple:<\/p>\n\n\n\n So you know how to specify alternative :user<\/em> and :port<\/em> options. But what about another server definition options e.g. ssh_options ?<\/p>\n\n\n\n Do we need to hack find_servers<\/a> to pass specific :ssh_options for server defined in task? No! recently we found simple solution without hacking: look at server_list_from<\/a><\/p>\n\n\n\n So we can pass in :hosts<\/em> options array of ServerDefinition<\/em> objects! So solution looks like this:<\/p>\n\n\n\n It is better to define servers as task\/run options:<\/p>\n\n\n\n We hope this article will help you to use Capistrano more efficiently.<\/p>\n","protected":false},"excerpt":{"rendered":" What if you have several servers with different users, ssh-keys, and even port numbers? How to manage all this stuff flexibly ? This tutorial covers poorly documented Capistrano features for advanced servers and roles configuration. Many of them obtained via digging into Capistrano sources. This article covers following Capistrano topics: roles configurationserver configurationThe way HOSTS,…<\/p>\n","protected":false},"author":19,"featured_media":9438,"comment_status":"open","ping_status":"open","sticky":false,"template":"","format":"standard","meta":{"_acf_changed":false,"footnotes":""},"categories":[3],"tags":[],"coauthors":["Andriy Yanko"],"class_list":["post-887","post","type-post","status-publish","format-standard","has-post-thumbnail","hentry","category-development"],"acf":[],"aioseo_notices":[],"categories_data":[{"name":"Engineering","link":"https:\/\/railsware.com\/blog?category=development"}],"post_thumbnails":"\/\/upload.wikimedia.org\/wikipedia\/en\/thumb\/9\/9f\/Reservoirdog.jpg\/300px-Reservoirdog.jpg","amp_enabled":true,"_links":{"self":[{"href":"https:\/\/railsware.com\/blog\/wp-json\/wp\/v2\/posts\/887","targetHints":{"allow":["GET"]}}],"collection":[{"href":"https:\/\/railsware.com\/blog\/wp-json\/wp\/v2\/posts"}],"about":[{"href":"https:\/\/railsware.com\/blog\/wp-json\/wp\/v2\/types\/post"}],"author":[{"embeddable":true,"href":"https:\/\/railsware.com\/blog\/wp-json\/wp\/v2\/users\/19"}],"replies":[{"embeddable":true,"href":"https:\/\/railsware.com\/blog\/wp-json\/wp\/v2\/comments?post=887"}],"version-history":[{"count":53,"href":"https:\/\/railsware.com\/blog\/wp-json\/wp\/v2\/posts\/887\/revisions"}],"predecessor-version":[{"id":14016,"href":"https:\/\/railsware.com\/blog\/wp-json\/wp\/v2\/posts\/887\/revisions\/14016"}],"wp:featuredmedia":[{"embeddable":true,"href":"https:\/\/railsware.com\/blog\/wp-json\/wp\/v2\/media\/9438"}],"wp:attachment":[{"href":"https:\/\/railsware.com\/blog\/wp-json\/wp\/v2\/media?parent=887"}],"wp:term":[{"taxonomy":"category","embeddable":true,"href":"https:\/\/railsware.com\/blog\/wp-json\/wp\/v2\/categories?post=887"},{"taxonomy":"post_tag","embeddable":true,"href":"https:\/\/railsware.com\/blog\/wp-json\/wp\/v2\/tags?post=887"},{"taxonomy":"author","embeddable":true,"href":"https:\/\/railsware.com\/blog\/wp-json\/wp\/v2\/coauthors?post=887"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}} role :dog, 'mr-white.reservoir.dogs', 'mr-orange.reservoir.dogs', 'mr-blonde.reservoir.dogs'\n role :boss, 'mr-white.reservoir.dogs'\n role :nerd, 'mr-orange.reservoir.dogs', 'mr-blonde.reservoir.dogs'<\/pre>\n\n\n\n
server 'mr-white.reservoir.dogs', :dog, :boss\n server 'mr-orange.reservoir.dogs', :dog, :nerd\n server 'mr-blonde.reservoir.dogs', :dog, :nerd<\/pre>\n\n\n\n\n\n\n\n
Command invocation<\/h3>\n\n\n\n
cap invoke # Invoke a single command on the remote servers.<\/pre>\n\n\n\n
$ cap invoke COMMAND=date\n * executing `invoke'\n * executing \"date\"\n servers: [\"mr-white.reservoir.dogs\", \"mr-orange.reservoir.dogs\", \"mr-blonde.reservoir.dogs\"]\n [mr-white.reservoir.dogs] executing command\n [mr-orange.reservoir.dogs] executing command\n [mr-blonde.reservoir.dogs] executing command\n ** [out :: mr-white.reservoir.dogs] Fri Oct 28 10:23:50 EDT 2011\n ** [out :: mr-orange.reservoir.dogs] Fri Oct 28 10:23:50 EDT 2011\n ** [out :: mr-blonde.reservoir.dogs] Fri Oct 28 10:23:50 EDT 2011\n command finished in 614ms<\/pre>\n\n\n\n
Running a task<\/h3>\n\n\n\n
desc \"Show server' date\"\n task :show_date do\n run('date')\n end<\/pre>\n\n\n\n$ cap -T\ncap invoke # Invoke a single command on the remote servers.\ncap shell # Begin an interactive Capistrano session.\ncap show_date # Show server' date<\/pre>\n\n\n\n
$ cap show_date\n * executing `show_date'\n * executing \"date\"\n servers: [\"mr-white.reservoir.dogs\", \"mr-orange.reservoir.dogs\", \"mr-blonde.reservoir.dogs\"]\n ** [out :: mr-white.reservoir.dogs] Fri Oct 28 10:23:50 EDT 2011\n ** [out :: mr-orange.reservoir.dogs] Fri Oct 28 10:23:50 EDT 2011\n ** [out :: mr-blonde.reservoir.dogs] Fri Oct 28 10:23:50 EDT 2011<\/pre>\n\n\n\n
desc \"Show server' date\"\n task :show_date, :roles => [:nerd] do\n run('date')\n end<\/pre>\n\n\n\n$ cap show_date\n * executing `show_date'\n * executing \"date\"\n servers: [\"mr-orange.reservoir.dogs\", \"mr-blonde.reservoir.dogs\"]\n ** [out :: mr-orange.reservoir.dogs] Fri Oct 28 10:23:50 EDT 2011\n ** [out :: mr-blonde.reservoir.dogs] Fri Oct 28 10:23:50 EDT 2011<\/pre>\n\n\n\n
Environment Variables<\/h3>\n\n\n\n
$ cap -H\n\n HOSTS\n Execute the tasks against this comma-separated list of hosts.\n Effectively, this makes the host(s) part of every roles.\n\n HOSTFILTER\n Execute tasks against this comma-separated list of host, but only if the\n host has the proper role for the task.\n\n HOSTROLEFILTER\n Execute tasks against the hosts in this comma-separated list of roles,\n but only if the host has the proper role for the task.\n\n ROLES\n Execute tasks against this comma-separated list of roles. Hosts which\n do not have the right roles will be skipped.<\/pre>\n\n\n\n
desc \"Show server' date\"\n task :show_date, :roles => [:nerd] do\n run('date')\n end<\/pre>\n\n\n\nHOSTS Variable<\/h4>\n\n\n\n
$ cap show_date HOSTS=mr-white.reservoir.dogs,mr-orange.reservoir.dogs\n * executing `show_date'\n * executing \"date\"\n servers: [\"mr-white.reservoir.dogs\", \"mr-orange.reservoir.dogs\"]\n...<\/pre>\n\n\n\n
cap show_date HOSTS=mr-white.reservoir.dogs,google.com\n * executing `show_date'\n * executing \"date\"\n servers: [\"mr-white.reservoir.dogs\", \"google.com\"]\n...<\/pre>\n\n\n\n
ROLES Variable<\/h4>\n\n\n\n
$ cap show_date ROLES=boss\n * executing `show_date'\n * executing \"date\"\n servers: [\"mr-white.reservoir.dogs\"]\n...<\/pre>\n\n\n\n
HOSTFILTER Variable<\/h4>\n\n\n\n
$ cap show_date HOSTFILTER=mr-orange.reservoir.dogs,google.com\n * executing `show_date'\n * executing \"date\"\n servers: [\"mr-orange.reservoir.dogs\"]\n...<\/pre>\n\n\n\n
HOSTROLEFILTER Variable<\/h4>\n\n\n\n
$ cap show_date HOSTROLEFILTER=boss\n * executing `show_date'\n * executing \"date\"\n`show_date' is only run for servers matching {:roles=>:nerd}, but no servers matched<\/pre>\n\n\n\n task :show_date, :roles => [:app, :db, :www, :backup] do\n ...\n end<\/pre>\n\n\n\n
$ cap show_date HOSTROLEFILTER=db,www,another_role<\/pre>\n\n\n\n
Advanced Server Definitions<\/h3>\n\n\n\n
Running command with custom options<\/h4>\n\n\n\n
task :shoot do\n run \"date\"\n run \"uname\", :roles => :boss\n run \"whoami\", :roles => :nerd\nend<\/pre>\n\n\n\n
$ cap shoot\n * executing `shoot'\n * executing \"date\"\n servers: [\"mr-white.reservoir.dogs\", \"mr-orange.reservoir.dogs\", \"mr-blonde.reservoir.dogs\"]\n [mr-orange.reservoir.dogs] executing command\n [mr-white.reservoir.dogs] executing command\n [mr-blonde.reservoir.dogs] executing command\n ** [out :: mr-white.reservoir.dogs] Fri Oct 28 12:00:19 EDT 2011\n ** [out :: mr-orange.reservoir.dogs] Fri Oct 28 12:00:19 EDT 2011\n ** [out :: mr-blonde.reservoir.dogs] Fri Oct 28 12:00:19 EDT 2011\n command finished in 737ms\n * executing \"uname\"\n servers: [\"mr-white.reservoir.dogs\"]\n [mr-white.reservoir.dogs] executing command\n ** [out :: mr-white.reservoir.dogs] Linux\n command finished in 479ms\n * executing \"whoami\"\n servers: [\"mr-orange.reservoir.dogs\", \"mr-blonde.reservoir.dogs\"]\n [mr-orange.reservoir.dogs] executing command\n [mr-blonde.reservoir.dogs] executing command\n ** [out :: mr-orange.reservoir.dogs] mongrel\n ** [out :: mr-blonde.reservoir.dogs] mongrel\n command finished in 746ms<\/pre>\n\n\n\n
date<\/code> is executed on all servers. And uname<\/code> and whoami<\/code> only on corresponding servers.<\/p>\n\n\n\nTask :roles and :hosts options<\/h4>\n\n\n\n
How does it differ from :roles options? Firstly, :hosts option have higher priority over :roles. Secondary, you always create new server definition object that is not in global<\/em> server list by specifying server via :hosts options. It means such server won’t be affected with tasks that does not have a role.
It’s really nice option because sometimes you want to execute some commands (notifications for example) on certain hosts that are actually not a target for the code delivery.<\/p>\n\n\n\ntask :log_deploy, :hosts => ['history.reservoir.dogs'] do\n run \"cat '#{Time.now},#{real_revision}' >> deploy.log\"\nend<\/pre>\n\n\n\nSpecifying alternative server options<\/h4>\n\n\n\n
role :app, 'app1.reservoir.dogs', 'app2.reservoir.dogs', {\n :user => 'nerd',\n :ssh_options => {\n :keys => '.\/keys\/nerd.pem'\n }\n}\n\nrole :db, 'db.reservoir.dogs', {\n :user => 'boss',\n :ssh_options => {\n :keys => '.\/keys\/boss.pem'\n }\n}<\/pre>\n\n\n\nserver 'app1.reservoir.dogs', :app, {\n :user => 'nerd1',\n :ssh_options => {\n :keys => '.\/keys\/nerd.pem'\n }\n}\n\nserver 'app2.reservoir.dogs', :app {\n :user => 'nerd2',\n :ssh_options => {\n :keys => '.\/keys\/nerd.pem'\n }\n}\n\nserver 'db.reservoir.dogs', :db {\n :user => 'boss',\n :ssh_options => {\n :keys => '.\/keys\/boss.pem'\n }\n}<\/pre>\n\n\n\nSpecifying some server options in task<\/h4>\n\n\n\n
At the first look there is an issue because :hosts option is an array of servers name.
But there is a trick available! Look at Capistrano::ServerDefinition<\/a><\/p>\n\n\n\nmodule Capistrano\n class ServerDefinition\n def initialize(string, options={})\n @user, @host, @port = string.match(\/^(?:([^;,:=]+)@|)(.*?)(?::(\\d+)|)$\/)[1,3]\n ...\n end\n end\nend<\/pre>\n\n\n\nrun(\"date\", :hosts => ['nerd1@app1.reservoir.dogs:2201', 'nerd2@app1.reservoir.dogs:2201'])\n\ntask(:show_date, :hosts => ['nerd1@app1.reservoir.dogs:2201', 'nerd2@app1.reservoir.dogs:2201']) do\n run(\"date\")\nend\n<\/pre>\n\n\n\n
Specifying any server options in task<\/h4>\n\n\n\n
def server_list_from(hosts)\n hosts = hosts.split(\/,\/) if String === hosts\n hosts = build_list(hosts)\n hosts.map { |s| String === s ? ServerDefinition.new(s.strip) : s }\n end<\/pre>\n\n\n\nrun(\"date\", :hosts => [\n Capistrano::ServerDefinition.new('app1.reservoir.dogs', {\n :user => 'nerd1',\n :port => 2201,\n :ssh_options => {\n :keys => '.\/keys\/nerd.pem'\n }\n }),\n Capistrano::ServerDefinition.new('app2.reservoir.dogs', {\n :user => 'nerd2',\n :port => 2202,\n :ssh_options => {\n :keys => '.\/keys\/nerd.pem'\n }\n })\n])\n\ntask(:show_date, :hosts => [\n Capistrano::ServerDefinition.new('app1.reservoir.dogs', {\n :user => 'nerd1',\n :port => 2201,\n :ssh_options => {\n :keys => '.\/keys\/nerd.pem'\n }\n }),\n Capistrano::ServerDefinition.new('app2.reservoir.dogs', {\n :user => 'nerd2',\n :port => 2202,\n :ssh_options => {\n :keys => '.\/keys\/nerd.pem'\n }\n })\n]) do\n run(\"date\")\nend\n<\/pre>\n\n\n\nset(:boss_host, {\n Capistrano::ServerDefinition.new('boss.reservoir.dogs', {\n :user => 'boss',\n :port => 2222,\n :ssh_options => {\n :keys => '.\/keys\/boss.pem'\n }\n})\n\nrun(\"date\", :hosts => [ :boss_host ]<\/pre>\n\n\n\nCapistrate the world!<\/h3>\n\n\n\n