Ruby – Deploy to only one role / server with capistrano

I ended up posting a question on the capistrano users list here, and got the following response from Jamis (edited a bit by me here for clarity):

Try the HOSTS environment variable:

cap HOSTS=app2.example.com production deploy

Note that doing this will treat app2 as being in every role, not just whichever role(s) it happens to be declared in.

If what you want is to do a regular deploy, but only act on app2, and only as app2 is declared in your recipe file, you can use the HOSTFILTER variable instead:

cap HOSTFILTER=app2.example.com production deploy 

[...]

Consider this concrete example. Suppose your script defines three servers, A, B, and C. And it defines a task, "foo", that (by default) wants to run on A and B, but not C. Like this:

role :app, "A", "B"
role :web, "C"

task :foo, :roles => :app do
  run "echo hello"
end

Now, if you do cap foo, it will run the echo command on both A and B.

If you do cap HOSTS=C foo, it will run the echo command on C, regardless of the :roles parameter to the task.

If you do cap HOSTFILTER=C foo, it will not run the echo command at all, because the intersection of (A B) and (C) is an empty set. (There are no hosts in foo's host list that match C.)

If you do cap HOSTFILTER=A foo, it will run the echo command on only A, because (A B) intersected with (A) is (A).

Lastly, if you do cap HOSTFILTER=A,B,C foo, it will run the echo command on A and B (but not C), because (A B) intersected with (A B C) is (A B).

To summarize: HOSTS completely overrides the hosts or roles declaration of the task, and forces everything to run against the specified host(s). The HOSTFILTER, on the other hand, simply filters the existing hosts against the given list, choosing only those servers that are already in the tasks server list.