Fezzik
Fezzik (or fez) is a slim and snappy way to run commands on servers. This is useful for many tasks, including deployment.
It wraps a rake-based rsync workflow and tries to keep things simple.
If upgrading to 0.8 from an earlier version of Fezzik, see Upgrading.
Install
gem install fezzik
Basic setup
Require Fezzik in your project Rakefile and define a destination:
require "fezzik"
include Fezzik::DSL
destination :prod do
set :user, "root"
set :domain, "myapp.com"
end
A host task is similar to a normal Rake task, but will run once for every host defined by :domain
. The body
of a host task exposes two methods:
run <command> Run a shell command on the remote host
host The domain that the currently running host task is targeting
Write some host tasks that will execute on the specified destination:
namespace :fezzik do
host_task :echo do
run "echo 'Running on #{host}'"
end
end
Run your host tasks with fezzik by passing a destination and list of tasks to run:
$ fez prod echo
host_task
The host_task
method is similar to Rake's task
in functionality, but has a slightly different API due to
its additional options. A host task is defined with a name and some (optional) options. The three primary ones
are :args
, :deps
, and :roles
. :args
and :deps
correspond to Rake's task arguments and task
dependencies, and :roles
is a Fezzik-specific option explained later. There are also three additional
options which can be passed to Weave, Fezzik's underlying ssh library, by
specifying them in a :weave_options
hash. They control how host tasks run concurrently:
-
:num_threads
: The number of threads used to run this task in parallel, or:unlimited
to use a thread for every host. Defaults to 10. -
:serial
: Whether to process the command for each connection one at a time. Defaults to false. -
:batch_by
: If set, group the connections into batches of no more than this value.
A Rake task that looks like this:
task :echo, [:arg1, :arg2] => [:dep1, :dep2] do |t, args|
...
end
would look like this as a host task:
host_task :echo, :args => [:arg1, :arg2],
:deps => [:dep1, :dep2] do |t, args|
...
end
And with Weave options:
host_task :echo, :args => [:arg1, :arg2],
:deps => [:dep1, :dep2],
:weave_options => {:num_threads => 20} do |t, args|
...
end
To avoid repeating the same weave_options
on every host_task, set Fezzik.default_weave_options
, which
will be merged with the :weave_options
hash of a host_task
.
Fezzik.default_weave_options = { :num_threads => :unlimited }
Deployments
One of the more useful things you can use Fezzik for is handling deployments.
require "fezzik"
include Fezzik::DSL
# Fezzik will automatically load any .rake files it finds in this directory.
Fezzik.init(:tasks => "config/tasks")
# The only special settings are `:domain` and `:user`. The rest are purely convention. All settings can be
# retrieved in your tasks with `get` (e.g., `get :current_path`).
set :app, "myapp"
set :user, "root"
set :deploy_to, "/opt/#{get :app}"
set :release_path, "#{get :deploy_to}/releases/#{Time.now.strftime("%Y%m%d%H%M")}"
set :current_path, "#{get :deploy_to}/current"
destination :staging do
set :domain, "myapp-staging.com"
end
destination :prod do
set :domain, "myapp.com"
end
Fezzik comes bundled with some useful tasks for common things like deployment. You can download the ones you need:
$ cd config/tasks
$ fez get deploy
[new] deploy.rake
You'll need to edit the fezzik:start
and fezzik:stop
tasks in deploy.rake since those are specific to your
project.
namespace :fezzik do
...
desc "runs the executable in project/bin"
host_task :start do
puts "starting from #{(run "readlink #{get :current_path}", :output => capture)[:stdout] }}"
run "cd #{get :current_path} && ./bin/run_app.sh"
end
desc "kills the application by searching for the specified process name"
Fezzik.host_task :stop do
puts "stopping app"
run "(kill `ps aux | grep 'myapp' | grep -v grep | awk '{print $2}'` || true)"
end
...
end
Deploy win!
$ fez prod deploy
...
[out|myapp.com] myapp deployed!
[success]
Environments
Configuration often changes when you deploy your project. Fezzik lets you set environments for your hosts.
$ cd config/tasks
$ fez get deploy
[new] deploy.rake
destination :prod do
set :domain, "myapp.com"
env :rack_env, "production"
end
This will be exposed in the form of an environment.sh file and an environment.rb file in your project root directory when you deploy. You can source the .sh file before running your app or require the .rb file in your project directly.
desc "runs the executable in project/bin"
host_task :start do
run "cd #{get :current_path} && (source environment.sh || true) && ./bin/run_app.sh"
end
You can assign different environments to subsets of hosts:
destination :prod do
set :domain, ["myapp1.com", "myapp2.com"]
env :rack_env, "production"
env :is_canary, "true", :hosts => ["myapp1.com"]
end
Fezzik accepts multiple destinations in the call to destination
.
This can be useful if you have common environment variables shared across destinations.
destination :staging, :prod do
env :unicorn_workers, 4
end
You can access the environment settings in your tasks, if you like. It's a hash.
task :inspect_all_environments do
puts Fezzik.environments.inspect
end
To access the environment for the currently targeted host:
host_task :inspect_environment do
puts Fezzik.environments[host].inspect
end
Roles
Fezzik supports role deployments. Roles allow you to assign host tasks different configurations according to their purpose. For example, you might want to perform your initial package installations as root, but run your app as an unprivileged user.
destination :prod do
set :domain, "myapp.com"
role :root_user, :user => "root"
role :run_user, :user => "app"
end
host_task :install, :roles => :root_user
# Install all the things.
end
host_task :run, :roles => :run_user
# Run all the things.
end
Or, you might have different domains for database deployment and app deployment.
destination :prod do
set :user, "root"
role :db, :domain => "db.myapp.com"
role :app, :domain => "myapp.com"
end
Roles in destination blocks can override global role settings.
role :app, :domain => "localhost"
destination :prod do
role :app, :domain => "myapp.com"
end
The role
method accepts a role name and a hash of values that you want assigned with the
set :var, value
syntax. These will override the global or destination settings when a host task is
run.
Utilities
Fezzik exposes some functions that can be useful when running host tasks.
Override hosts from command line
$ domain="example1.com,example2.com" fez prod deploy
Set the "domain" environment variable to override the domains set in your destination block. Useful for running one-off tasks against a subset of your hosts.
Capture or modify output
The output of run
can be captured or modified instead of printing directly with the host prefix.
It can return a hash of :stdout, :stderr
, or it can stream the raw output without prefixing each host.
# prints "[out|myapp.com] hi"
run "echo 'hi'"
# prints "hi"
run "echo 'hi'", :output => :raw
# output == { :stdout => "hi" :stderr => "" }
output = run "echo 'hi'", :output => :capture
A note on puts
Ruby's puts
is not thread-safe. In particular, running multiple puts
in parallel can result in the
newlines being separated from the rest of the string.
As a helper, any puts
used from within a host task will call an overridden thread-safe version of puts
. If
$stdout.puts
or $stderr.puts
is used instead, the normal thread-unsafe method will be called.
DSL
Fezzik comes with a DSL module that you can optionally include in the top level of your Rakefiles with
include Fezzik::DSL
. It exposes the following functions:
destination
host_task
set
get
env
role
capture_output
If you don't want to include these functions in your top-level namespace they can all be called directly on
the Fezzik module, e.g., Fezzik.destination
.
Included Tasks
Fezzik has a number of useful tasks other than those defined in deploy.rake. These can also be downloaded
with $ fez get <task>
and placed in the directory you specify with Fezzik.init(:tasks => "config/tasks")
.
These tasks are meant to be starting points. For example, if you want to save your environment files in a place that's not your project root you can simply edit the task in deploy.rake.
If you write a recipe that would be useful to other developers, please submit a pull request!
Command
$ cd config/tasks
$ fez get command
[new] command.rake
Sometimes you just need to get your hands dirty and run a shell on your servers. The command.rake tasks give you a prompt that lets you execute shell code on each of your hosts.
$ fez prod command
Targeting hosts:
root@myapp.com
run command (or "quit"): tail www/myapp/log.txt -n 1
[2011-07-01 00:01:23] GET / 200
You can also run a single command:
$ fez prod "command_execute[ls]"
Rollback
$ cd config/tasks
$ fez get rollback
[new] rollback.rake
Emergency! Rollback! Every deployment you make is saved on the server if you use the default tasks defined in deploy.rake. You can move between these deployments (to roll back, for example), with rollback.rake.
$ fez prod rollback
configuring for root@myapp.com
=== Releases ===
0: Abort
1: 201107051328 (current)
2: 201106231408
3: 201106231352
Rollback to release (0):
Rake passthroughs
Because Fezzik is built on Rake it passes through some options directly to Rake. You can use these with the
fez
command as if you were running rake
directly:
--trace Turn on invoke/execute tracing, enable full backtrace.
--dry-run Do a dry run without executing actions.
Upgrading
0.8.0
Fezzik 0.8 replaces much of its internal piping with Weave, an excellent parallel SSH library. This allows for cleaner output and faster task execution due to using a shared connection pool, but necessarily introduces a few breaking changes. These are detailed below.
Breaking changes
-
The method
target_host
is gone and has been replaced by usinghost
in a host task. The old methodhost
has been removed and there should no longer be a reason to use it. -
The
current_path
setting is no longer set automatically. To continue using it in your deployments, define it manually:set :current_path, "#{get :deploy_to}/current`.
-
The helper method
rsync
no longer exists. Instead ofrsync "..."
usesystem("rsync -az ...")
-
The helper method
sudo
no longer exists. Instead ofsudo "..."
userun "sudo ..."
Deprecations
-
The
remote_task
method is deprecated. Usehost_task
instead. -
Using settings defined by
set
as top-level method calls is deprecated. For example, useget :domain
instead ofdomain
. -
Fezzik::Util.capture_output is deprecated. Pass options directly to
run
instead:run "echo 'hi'", :output => :capture run "echo 'hi'", :output => :raw