Need help with capistrano-unicorn?
Click the “chat” button below for chat support from the developer who created it, or find similar developers for support.

About the developer

sosedoff
406 Stars 153 Forks MIT License 148 Commits 20 Opened issues

Description

Capistrano integration for Unicorn! - NEEDS MAINTAINER

Services available

!
?

Need anything else?

Contributors list

Capistrano Unicorn

Capistrano plugin that integrates Unicorn tasks into capistrano deployment script.

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.

Build Status Gem Version Code Climate

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 'capistrano-unicorn', :require => false
end

And load it into your deployment script

config/deploy.rb
:
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
    : :-1: This can sort of support it with a configurable timeout, which may not be reliable.
  • unicorn:reload
    : :question: Can anyone testify to its zero-downtime support?
  • unicorn:duplicate
    : :+1: If you install the Unicorn
    before_fork
    hook, then yes! See: https://github.com/sosedoff/capistrano-unicorn/issues/40#issuecomment-16011353

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

Multistage

The issue here is that capistrano loads default configuration and then executes your staging task and overrides previously defined variables. The default environment before executing your stage task is set to

:production
, so it will use a wrong environment unless you take steps to ensure that
:rails_env
and
:unicorn_env
are set correctly.

Let's say you have a scenario involving two deployment stages: staging and production. You’ll need to add

config/deploy/staging.rb
and
config/deploy/production.rb
files. However, it makes sense to adhere to DRY and avoid duplicating lines between the two files. So it would be nicer to keep common settings in
config/deploy.rb
, and only put stuff in each staging definition file which is really specific to that staging environment. Fortunately this can be done using the lazy evaluation form of
set
.

So

config/deploy.rb
file would contain something like:
set :stages, %w(production staging)
set :default_stage, "staging"
require 'capistrano/ext/multistage'

set(:unicorn_env) { rails_env }

role(:web) { domain } role(:app) { domain } role(:db, :primary => true) { domain }

set(:deploy_to) { "/home/#{user}/#{application}/#{fetch :rails_env}" } set(:current_path) { File.join(deploy_to, current_dir) }

Then

config/deploy/production.rb
would contain something like:
set :domain,      "app.mydomain.com"
set :rails_env,   "production"

and

config/deploy/staging.rb
would only need to contain something like:
set :domain,      "app.staging.mydomain.com"
set :rails_env,   "staging"

Nice and clean!

License

See LICENSE file for details.

We use cookies. If you continue to browse the site, you agree to the use of cookies. For more information on our use of cookies please see our Privacy Policy.