Puma integration for Capistrano 3

gem install capistrano3-puma -v 3.1.1


Abdelkader Boudih ruohan.chen molfar Hnat Kubov fang duan Michael C. Beck Cyril Rohr Jun Lin Fabian Winkler Aleksey Ivanov not-a-patch Jordan Hollinger Feña Agar Huang Bin Lonre Wang soylent Simon Males Eric Guo SHIMADA Koji ayaya Eric Bryan Liles Rafael Goulart Suraj Shirvankar

See all contributors


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.config

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 :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