What is the point of writing a Ruby on Rails application unless you are going to deploy it to a production environment? Capistrano by far is the easiest and best way to deploy code to a remote server (production or staging).

Capistrano Puma, until v5, supported daemon mode. If you are used to it, you will have to use Systemd. It comes out of the box and everything is just as easy.

Important

This blog post doesn't bring a complete deployment configuration. It merely covers the configuration of the Capistrano gem with puma. A deployment configuration is subjective to the requirements of the application and if you don't know what I am talking about, contact me.

• I assume you have a working RoR application with Capistrano installed and configured
• I assume you have a VPS server to deploy your code to (Heroku people, get out!😉)
• You have installed the necessary software in your VPS (ex: Nginx, PostgreSQL, Redis, Node JS, etc)

Note: If you don't have a VPS, DO is in my opinion the best provider to get one. Here is $100 credit on Digital Ocean for new signups.

Instructions

First of all, add Capistrano to your Gemfile. Do a bundle add capistrano3-puma and move the listings under group: :development and add require: false. The version you get might be different but your end result should look something like this:

group :development do
  gem 'capistrano-rails', '~> 1.6.1', require: false
  gem 'capistrano3-puma', '~> 5.2.0', require: false
end

Now open Capfile and add the following. This configuration should be below any rvm or rbenv configuration.

require 'capistrano/rvm'
# .
# ..
# ...

# Important: Puma configuration should come after rvm or rbenv
require 'capistrano/puma'
install_plugin Capistrano::Puma
install_plugin Capistrano::Puma::Systemd

An example Capfile will be placed below. Once you do this, you will have access to Systemd related puma commands.

Configure the remote server by running the following command. It will create Systemd related commands for starting, stopping and other related commands.

cap production puma:systemd:config

A full list of commands is as follows.

cap puma:config                           # Setup Puma config file
cap puma:reload                           # Reload Puma service via systemd
cap puma:restart                          # Restart Puma service via systemd
cap puma:smart_restart                    # Restarts or reloads Puma service via systemd
cap puma:start                            # Start Puma service via systemd
cap puma:status                           # Get Puma service status via systemd
cap puma:stop                             # Stop Puma service via systemd
cap puma:systemd:config                   # Config Puma systemd service
cap puma:systemd:disable                  # Disable Puma systemd service
cap puma:systemd:enable                   # Enable Puma systemd service
cap puma:systemd:generate_config_locally  # Generate service configuration locally
cap puma:systemd:restart_socket           # Restart Puma socket via systemd
cap puma:systemd:stop_socket              # Stop Puma socket via systemd

If you have configured the config/deploy/production.rb or config/deploy/staging.rb, you can now deploy to the server.

cap production deploy

Upgrade Error

If you are upgrading your Ruby on Rails application and when you deploy the code the app is no longer running, the chances are you have upgraded Puma from v3.x or v4.x to v5.x. Puma v5.x no longer supports daemon mode.

Run a cap -T and you will notice that your usual puma related tasks are missing.

⇒  cap -T | grep puma
cap puma:config                    # Setup Puma config file

Make sure to include Systemd and run the configuration will fix the issue.

require 'capistrano/puma'
install_plugin Capistrano::Puma
install_plugin Capistrano::Puma::Systemd

Then run

cap production puma:systemd:config
cap production deploy