Capistrano 3.x integration for Unicorn!
Clone or download
Pull request Compare This branch is 2 commits ahead, 2 commits behind sepastian:master.
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Failed to load latest commit information.

Capistrano Unicorn

Capistrano 3.x plugin that integrates Unicorn tasks into capistrano deployment script. Taken from and adapted to work with Capistrano 3.x.

Note: this code is not well tested, if anything fails, please report it. Use at your own risk.

Developers: Please consider contributing your forked changes, or opening an issue if there is no existing relevant one. There are a lot of forks--we'd love to reabsorb some of the issues/solutions the community has encountered.

Gem Version


If you are upgrading from a previous version, please see the NEWS file.


Add the library to your Gemfile:

group :development do
  gem 'sepastian-capistrano3-unicorn', :require => false

And require it in your Capfile:

require 'capistrano/unicorn'

Add unicorn restart task hook:

after 'deploy:restart', 'unicorn:reload'    # app IS NOT preloaded
after 'deploy:restart', 'unicorn:restart'   # app preloaded
after 'deploy:restart', 'unicorn:duplicate' # before_fork hook implemented (zero downtime deployments)

Create a new configuration file config/unicorn.rb or config/unicorn/STAGE.rb, where stage is your deployment environment.

Example config - examples/rails3.rb. Please refer to Unicorn documentation for more examples and configuration options.


First, make sure you're running the latest release:

cap deploy

Then you can test each individual task:

cap unicorn:start
cap unicorn:stop
cap unicorn:reload


You can modify any of the following Capistrano variables in your deploy.rb config. You can use the unicorn:show_vars task to check that the values you have specified are set correctly.

Environment parameters

  • unicorn_env - Set basename of unicorn config .rb file to be used loaded from unicorn_config_path. Defaults to rails_env variable if set, otherwise production.
  • unicorn_rack_env - Set the value which will be passed to unicorn via the -E parameter as the Rack environment. Valid values are development, deployment, and none. Defaults to development if rails_env is development, otherwise deployment.

Execution parameters

  • unicorn_user - Launch unicorn master as the specified user via sudo. Defaults to nil, which means no use of sudo, i.e. run as the user defined by the user variable.
  • unicorn_roles - Define which roles to perform unicorn recipes on. Defaults to :app.
  • unicorn_bundle - Set bundler command for unicorn. Defaults to bundle.
  • unicorn_bin - Set unicorn executable file. Defaults to unicorn.
  • unicorn_options - Set any additional options to be passed to unicorn on startup.
  • unicorn_restart_sleep_time - Number of seconds to wait for (old) pidfile to show up when restarting unicorn. Defaults to 2.

Relative path parameters

  • app_subdir - If your app lives in a subdirectory 'rails' (say) of your repository, set this to /rails (the leading slash is required).
  • unicorn_config_rel_path - Set the directory path (relative to app_path - see below) where unicorn config files reside. Defaults to config.
  • unicorn_config_filename - Set the filename of the unicorn config file loaded from unicorn_config_path. Should not be present in multistage installations. Defaults to unicorn.rb.

Absolute path parameters

  • app_path - Set path to app root. Defaults to current_path + app_subdir.
  • unicorn_pid - Set unicorn PID file path. By default, attempts to auto-detect from unicorn config file. On failure, falls back to value in unicorn_default_pid
  • unicorn_default_pid - See above. Defaults to #{current_path}/tmp/pids/
  • bundle_gemfile - Set path to Gemfile. Defaults to #{app_path}/Gemfile
  • unicorn_config_path - Set the directory where unicorn config files reside. Defaults to #{current_path}/config.

Zero Downtime Deployment Options

Available Tasks

To get a list of all capistrano tasks, run cap -T:

cap unicorn:add_worker                # Add a new worker
cap unicorn:remove_worker             # Remove amount of workers
cap unicorn:reload                    # Reload Unicorn
cap unicorn:restart                   # Restart Unicorn
cap unicorn:show_vars                 # Debug Unicorn variables
cap unicorn:shutdown                  # Immediately shutdown Unicorn
cap unicorn:start                     # Start Unicorn master process
cap unicorn:stop                      # Stop Unicorn


To execute test suite run:

bundle exec rake test


See LICENSE file for details.