Puma は Ruby/Rack アプリケーションのための HTTP サーバです。Rails の場合に関する使用方法をまとめます。

事前準備

JRuby のインストール

rbenv による ruby インストールを行います。公式ページによると、パフォーマンスを最大限に引き出すためには正式にスレッドをサポートしている Rubinius または JRuby を使用することを推奨しています。

In order to get the best throughput, it is highly recommended that you use a Ruby implementation with real threads like Rubinius or JRuby.

必須ではありませんが、本ページでは JRuby をインストールして利用してみます。ビルドに必要な RPM をインストールしておきます。

$ sudo yum install java-1.8.0-openjdk-devel
$ sudo yum install gcc-c++

ビルドを実行します。

$ rbenv install jruby-1.7.20
$ rbenv rehash

bundler もインストールしておきます。

$ rbenv global jruby-1.7.20
$ rbenv exec gem install bundler
$ rbenv rehash

Rails アプリの作成

先程と同様に、bundler を用いた rails のインストールを行います。2015/06/05 時点で JRuby をサポートしている 4.1.8 をインストールしました。

$ bundle exec rails server

別ターミナルで動作検証を行います。JRuby ですので JVM が起動しています。jps で確認します。JRuby の場合は起動のためにやや時間がかかります。

$ jps -m
15413 Main bin/rails server
15566 Jps -m

アクセスしてみます。

$ curl http://localhost:3000/

Puma の導入

インストール

puma を Gemfile に追記します。

$ vi Gemfile
gem 'puma'

インストールおよび検証を行います。

$ bundle install --path vendor/bundle
$ bundle exec puma -h
$ bundle exec rails server puma

設定ファイルの記述

config/puma.rb (新規作成)

environment 'production'
port 8080
daemonize true
state_path 'tmp/pids/puma.state'
pidfile 'tmp/pids/puma.pid'
threads 0,16
workers 2

config/secrets.yml

production:
  #secret_key_base: <%= ENV["SECRET_KEY_BASE"] %>
  secret_key_base: 9b2ca2d49d440d8f4472cd71a1a5c414faf598e45459

上記ファイルを直接編集するか、あるいは export しておくなど何らかの手段で環境変数を提供できるようにしておきます。

$ export SECRET_KEY_BASE=9b2ca2d49d440d8f4472cd71a1a5c414faf598e45459

起動

$ bundle exec pumactl -F config/puma.rb start

停止

処理中のリクエストがあった場合、通信を切断して終了します。

$ bundle exec pumactl -F config/puma.rb stop

再起動

• クラスターモード (設定項目 workers を 1 以上に設定) の場合は preload_app と併用することで worker 数が多い場合の再起動の高速化が可能
• 処理中のリクエストが完了するのを待ってから全ての worker を一斉に再起動 (ダウンタイムが 0 ではない)
  • DB スキーマがデプロイ前後で頻繁に変更になる場合にも対応

unicorn や nginx のように "hot restart" 機能が実装されており、処理中のリクエストがあった場合、処理が完了するのを待ってから再起動します。worker 群のマスタープロセスが複数存在する cluster mode で実行中の場合は、後述の preload_app との併用も可能です。worker 数が多い場合は preload_app と併用するとデプロイに要する時間が短縮できます。ダウンタイムは厳密には 0 ではありませんが、DB スキーマが頻繁に変更される場合は phased-restart ではなくこちらを使用します。

$ bundle exec pumactl -F config/puma.rb restart

段階的な再起動 (phased-restart)

• クラスターモード (設定項目 workers を 1 以上に設定) の場合に使用可能。ただし preload_app との併用はできない
• 処理中のリクエストが完了するのを待ってから全ての worker を 1 つずつに再起動 (ダウンタイム 0)
  • DB スキーマがデプロイ前後で頻繁に変更になる場合には非推奨

worker が複数いるときに使用可能です。worker を一つずつ再起動します。リクエストを処理中の worker については処理が完了するのを待ってから再起動します。多少の時間はかかりますが、少なくとも 1 worker がリクエストを処理できるため、ダウンタイム 0 で再起動できます。ただし、DB スキーマが変更されるデプロイ時の再起動では、古い再起動前の設定の worker でも処理できるスキーマがデプロイ後も維持されていることが必要です。また、worker の設定を worker 群のマスタープロセスに予めロードしておき、それを新 worker にコピーして起動する preload_app 機能は、複数の設定をロードしなければならなくなる phased-restart の性質上、使用できません。ダウンタイム 0 を実現するためにはこちらを使用します。

$ bundle exec pumactl -F config/puma.rb phased-restart

Capistrano 3 デプロイ設定

Apache Passenger 用の Capistrano 3 設定を puma 向けに変更するためには以下のようにします。

Gemfile に

gem 'capistrano-passenger'

の代わりに

gem 'capistrano3-puma'

を記載します。Capfile に

require 'capistrano/passenger'

の代わりに

require 'capistrano/puma'

を記載します。config/deploy/{production|staging}.rb に

# puma の設定ファイル (shared_path: deploy_to + 'shared')
set :puma_conf, "#{shared_path}/config/puma.rb"

を追記します。config/deploy.rb の set :linked_files に

config/puma.rb

を追記します。config/deploy.rb に

# capistrano3-puma の既定の再起動処理を無効化
set :puma_default_hooks, false

# puma を capistrano で利用するための設定
set :puma_preload_app, false
set :prune_bundler, true

を追記します。config/deploy.rb の task :restart do を以下のように変更します。

task :restart do
  on roles(:app) do
    # Your restart mechanism here, for example:
    # execute :touch, release_path.join('tmp/restart.txt')
    invoke 'puma:phased-restart'
  end
end