Puma integration for Capistrano
Clone or download
Latest commit 09b11ca Oct 10, 2018
Failed to load latest commit information.
lib Fix restart task, pumactl don't call bundle exec on restart Aug 15, 2017
.gitignore initial import Oct 25, 2013
CHANGELOG.md release 3.1.0 Mar 24, 2017
CONTRIBUTORS.md Minor fixes Mar 24, 2017
Gemfile initial import Oct 25, 2013
LICENSE.txt V3.0.0 Mar 10, 2017
README.md fix port Oct 5, 2018
Rakefile initial import Oct 25, 2013
capistrano3-puma.gemspec release v3.1.1 Jul 4, 2017


Gem Version



Add this line to your application's Gemfile:

gem 'capistrano3-puma', github: "seuros/capistrano-puma"


gem 'capistrano3-puma' , group: :development

And then execute:

$ bundle


    # Capfile

    require 'capistrano/puma'
    install_plugin Capistrano::Puma  # Default puma tasks
    install_plugin Capistrano::Puma::Workers  # if you want to control the workers (in cluster mode)
    install_plugin Capistrano::Puma::Jungle # if you need the jungle tasks
    install_plugin Capistrano::Puma::Monit  # if you need the monit tasks
    install_plugin Capistrano::Puma::Nginx  # if you want to upload a nginx site template

To prevent loading the hooks of the plugin, add false to the load_hooks param.

    # Capfile

    require 'capistrano/puma'
    install_plugin Capistrano::Puma, load_hooks: false  # Default puma tasks without hooks
    install_plugin Capistrano::Puma::Monit, load_hooks: false  # Monit tasks without hooks


To list available tasks use cap -T

To upload puma config use:

cap production puma:config

By default the file located in shared/puma.rb

Ensure that tmp/pids and tmp/sockets log are shared (via linked_dirs):

This step is mandatory before deploying, otherwise puma server won't start


To upload a nginx site config (eg. /etc/nginx/sites-enabled/) use:

cap production puma:nginx_config

To customize these two templates locally before uploading use:

rails g capistrano:nginx_puma:config

if your nginx server configuration is not located in /etc/nginx, you may need to customize:

set :nginx_sites_available_path, "/etc/nginx/sites-available"
set :nginx_sites_enabled_path, "/etc/nginx/sites-enabled"

By default, nginx_config will be executed with :web role. But you can assign it to a different role:

set :puma_nginx, :foo

or define a standalone one:

role :puma_nginx, %w{root@example.com}


For Jungle tasks (beta), these options exist:

    set :puma_jungle_conf, '/etc/puma.conf'
    set :puma_run_path, '/usr/local/bin/run-puma'

Multi bind

Multi-bind can be set with an array in the puma_bind variable

  set :puma_bind, %w(tcp:// unix:///tmp/puma.sock)
* Listening on tcp://
* Listening on unix:///tmp/puma.sock

Active Record

For ActiveRecord the following line to your deploy.rb

    set :puma_init_active_record, true

Other configs

Configurable options, shown here with defaults: Please note the configuration options below are not required unless you are trying to override a default setting, for instance if you are deploying on a host on which you do not have sudo or root privileges and you need to restrict the path. These settings go in the deploy.rb file.

    set :puma_user, fetch(:user)
    set :puma_rackup, -> { File.join(current_path, 'config.ru') }
    set :puma_state, "#{shared_path}/tmp/pids/puma.state"
    set :puma_pid, "#{shared_path}/tmp/pids/puma.pid"
    set :puma_bind, "unix://#{shared_path}/tmp/sockets/puma.sock"    #accept array for multi-bind
    set :puma_control_app, false
    set :puma_default_control_app, "unix://#{shared_path}/tmp/sockets/pumactl.sock"
    set :puma_conf, "#{shared_path}/puma.rb"
    set :puma_access_log, "#{shared_path}/log/puma_access.log"
    set :puma_error_log, "#{shared_path}/log/puma_error.log"
    set :puma_role, :app
    set :puma_env, fetch(:rack_env, fetch(:rails_env, 'production'))
    set :puma_threads, [0, 16]
    set :puma_workers, 0
    set :puma_worker_timeout, nil
    set :puma_init_active_record, false
    set :puma_preload_app, false
    set :puma_daemonize, false
    set :puma_plugins, []  #accept array of plugins
    set :puma_tag, fetch(:application)
    set :puma_restart_command, 'bundle exec puma'

    set :nginx_config_name, "#{fetch(:application)}_#{fetch(:stage)}"
    set :nginx_flags, 'fail_timeout=0'
    set :nginx_http_flags, fetch(:nginx_flags)
    set :nginx_server_name, "localhost #{fetch(:application)}.local"
    set :nginx_sites_available_path, '/etc/nginx/sites-available'
    set :nginx_sites_enabled_path, '/etc/nginx/sites-enabled'
    set :nginx_socket_flags, fetch(:nginx_flags)
    set :nginx_ssl_certificate, "/etc/ssl/certs/#{fetch(:nginx_config_name)}.crt"
    set :nginx_ssl_certificate_key, "/etc/ssl/private/#{fetch(:nginx_config_name)}.key"
    set :nginx_use_ssl, false

Notes: If you are setting values for variables that might be used by other plugins, use append instead of set. For example:

append :rbenv_map_bins, 'puma', 'pumactl'


  1. Fork it
  2. Create your feature branch (git checkout -b my-new-feature)
  3. Commit your changes (git commit -am 'Add some feature')
  4. Push to the branch (git push origin my-new-feature)
  5. Create new Pull Request