Capistrano::UnicornNginx

Capistrano tasks for automatic and sensible unicorn + nginx configuraion.

Goals of this plugin:

  • automatic unicorn and nginx configuration for Rails apps
  • no manual ssh to the server required
  • zero downtime deployments enabled

Specifics:

  • generates nginx config file on the server
  • generates unicorn initializer and config files
    application is started automatically after server restart
  • capistrano tasks for server management, example: unicorn:restart
    see below for all available tasks

capistrano-unicorn-nginx works only with Capistrano 3!

This project was based on capistrano-nginx-unicorn. I contributed a lot to Capistrano 3 version of that plugin. In the end I decided to create my own project to bring in additional improvements, without having to ask for permissions and wait for merging.

Installation

Add this to Gemfile:

group :development do
  gem 'capistrano', '~> 3.1'
  gem 'capistrano-unicorn-nginx'
end

And then:

$ bundle install

Setup and usage

Add this line to Capfile

require 'capistrano/unicorn-nginx'

If you already have a domain for your app, set nginx_server_name in stage file, example config/deploy/production.rb:

set :nginx_server_name, 'mydomain.com'

If you don't have a domain yet, you do not have to do anything (nginx_server_name will use the default value - server IP).

And you're all set!

Execute:

$ bundle exec cap deploy production

and enjoy watching your app being deployed!

Configuration

As described in the Usage section, this plugin works with minimal setup. However, configuration is possible.

You'll find the options and their defaults below.

In order to override the default, put the option in the stage file, for example:

# in config/deploy/production.rb
set :unicorn_workers, 4

Nginx options

Defaults are listed near option name in the first line.

  • set :nginx_server_name # defaults to
    Your application's domain. The default is your server's IP address.

  • set :nginx_pid, "/run/nginx.pid"
    Path for nginx process pid file.

SSL related options:

  • set :nginx_use_ssl, false
    If set to true, nginx will be configured to 443 port and port 80 will be auto routed to 443. Also, on nginx:setup, paths to ssl certificate and key will be configured. Certificate file and key will be uploaded to /etc/ssl/certs/ and /etc/ssl/private/ directories on the server.

  • set :nginx_upload_local_cert, true
    If true, certificates will be uploaded from a local path. Otherwise, it is expected for the certificate and key defined in the next 2 variables to be already on the server.

  • set :nginx_ssl_cert, "#{fetch(:nginx_server_name)}.crt"
    Remote file name of the certificate. Only makes sense if nginx_use_ssl is set.

  • set :nginx_ssl_cert_key, "#{fetch(:nginx_server_name)}.key"
    Remote file name of the certificate. Only makes sense if nginx_use_ssl is set.

  • set :nginx_ssl_cert_local_path # no default, required if nginx_use_ssl = true and nginx_upload_local_cert = true
    Local path to file with certificate. Only makes sense if nginx_use_ssl is set. This file will be copied to remote server. Example value: set :nginx_ssl_cert_local_path, "/home/user/ssl/myssl.cert"

  • set :nginx_ssl_cert_key_local_path # no default
    Local path to file with certificate key. Only makes sense if nginx_use_ssl is set. This file will be copied to remote server. Example value: set :nginx_ssl_cert_key_local_path, "/home/user/ssl/myssl.key"

Unicorn options

Defaults are listed near option name in the first line.

  • set :unicorn_service, "unicorn_#{fetch(:application)}_#{fetch(:stage)}
    Unicorn service name is unicorn_myapp_production by default.

  • set :unicorn_pid, shared_path.join("tmp/pids/unicorn.pid")
    Path for unicorn process pid file.

  • set :unicorn_config, shared_path.join("config/unicorn.rb")
    Path for unicorn config file.

  • set :unicorn_workers, 2
    Number of unicorn workers.

How it works

capistrano-unicorn-nginx integrates seamlessly with the capistrano deploy task. Here's what happens when you run bundle exec cap production deploy:

Nginx

  • after :started, "nginx:setup"
    Generates and uploads nginx config file. Symlinks config file to /etc/nginx/sites-enabled.
  • after :started, "nginx:setup_ssl"
    Performs SSL related tasks (false by default).
  • after :publishing, "nginx:reload"
    Reloads nginx.

Unicorn

  • after :updated, "unicorn:setup_initializer"
    Uploads unicorn initializer file.
  • after :updated, "unicorn:setup_app_config"
    Generates unicorn application config file
  • after :publishing, "unicorn:restart"
    Restarts unicorn after new release.

Template customization

If you want to change default templates, you can generate them using rails generator:

$ bundle exec rails g capistrano:unicorn_nginx:config

This will copy default templates to config/deploy/templates directory, so you can customize them as you like, and capistrano tasks will use this templates instead of default.

You can also provide path, where to generate templates:

$ bundle exec rails g capistrano:unicorn_nginx:config config/templates

More Capistrano automation?

If you'd like to streamline your Capistrano deploys, you might want to check these zero-configuration, plug-n-play plugins:

Bug reports and pull requests

...are very welcome!

Thanks

@kalys - for his capistrano-nginx-unicorn plugin.