Capistrano Unicorn

Capistrano 3.x plugin that integrates Unicorn tasks into capistrano deployment script. Taken from https://github.com/sosedoff/capistrano-unicorn 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.

Usage

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

Setup

Add the library to your Gemfile:

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

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.

Deploy

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

Configuration

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/unicorn.pid
• 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

• unicorn:restart: 👎 This can sort of support it with a configurable timeout, which may not be reliable.
• unicorn:reload: ❓ Can anyone testify to its zero-downtime support?
• unicorn:duplicate: 👍 If you install the Unicorn before_fork hook, then yes! See: sosedoff#40 (comment)

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

Tests

To execute test suite run:

bundle exec rake test

License

See LICENSE file for details.