skip to content

Puma Concurrency Settings

Puma runs each request on a thread inside one or more forked workers, set in config/puma.rb from RAILS_MAX_THREADS and WEB_CONCURRENCY. Interviewers probe sizing, forking and thread safety.

part ofRuby on Railsread it →
on this pageshow

explore

questions

4

In a new Rails 8.1 app, what does the generated config/puma.rb set up, and what does it leave to Puma's own defaults?

level: juniorimportance: must knowfreq 55%

answer

  1. an env var with a fallback of 3
  2. PORT falls back to 3000
  3. a plugin watching tmp/restart.txt
  4. no workers line in the file
  5. PIDFILE only when it is set

basics

~20 s

Rails 8.1's config/puma.rb sets threads per process from RAILS_MAX_THREADS (default 3), the port from PORT (default 3000), and loads plugin :tmp_restart. It has no workers line, so Puma reads WEB_CONCURRENCY itself and otherwise runs one process.

solid answer

~30 s

The file is Puma's configuration DSL, evaluated when `bin/rails server` boots Puma. It reads `threads_count = ENV.fetch("RAILS_MAX_THREADS", 3)` and calls `threads threads_count, threads_count`, so each process keeps a fixed pool of 3 request threads. `port ENV.fetch("PORT", 3000)` overrides Puma's own 9292. `plugin :tmp_restart` restarts Puma when `tmp/restart.txt` is touched, which is what `bin/rails restart` does. It also adds `plugin :solid_queue` when `SOLID_QUEUE_IN_PUMA` is set and a `pidfile` only if `PIDFILE` is. What it leaves out matters as much: there is **no `workers` line**. Puma reads `WEB_CONCURRENCY` from the environment on its own; unset, it runs in single mode, one process.

code

ruby · 11 lines
ruby
# config/puma.rb as generated by Rails 8.1 (comments trimmed)
threads_count = ENV.fetch("RAILS_MAX_THREADS", 3)
threads threads_count, threads_count

port ENV.fetch("PORT", 3000)

plugin :tmp_restart

plugin :solid_queue if ENV["SOLID_QUEUE_IN_PUMA"]

pidfile ENV["PIDFILE"] if ENV["PIDFILE"]

go deeper

for a junior

Recall the three lines that matter: threads from RAILS_MAX_THREADS (3), port from PORT (3000), plugin :tmp_restart. Know that WEB_CONCURRENCY is not in the file.

for a middle

Explain who reads each variable: the file reads RAILS_MAX_THREADS and PORT, Puma reads WEB_CONCURRENCY itself, and an unset value means single mode.

for a senior

Connect the file to production: the pool comment, Thruster in front of PORT, and why the process count is left to the environment of each host.

for a principal

Treat puma.rb as a contract between app and platform: which knobs live in code and which in deploy env, and who owns changing them.

## Where Puma sits in a Rails app **Puma** is the application server a new Rails app ships with: the generated Gemfile lists `gem "puma", ">= 5.0"`, and `bin/rails server` starts it. Puma accepts HTTP connections and hands each request to a **thread** from a pool inside a Ruby process. Optionally it forks several such processes, which it calls **workers**. Puma's configuration is Ruby code in its own DSL, and Rails generates it as `config/puma.rb`. Reading that file line by line is a common first question about running Rails, because every later sizing discussion starts from it. ## The generated file, line by line | Line in `config/puma.rb` | What it does | Default when the env var is unset | |---|---|---| | `threads_count = ENV.fetch("RAILS_MAX_THREADS", 3)` then `threads threads_count, threads_count` | fixes min and max request threads per process | 3 threads | | `port ENV.fetch("PORT", 3000)` | the TCP port Puma binds | 3000 (Puma alone would use 9292) | | `plugin :tmp_restart` | restarts Puma when `tmp/restart.txt` changes | always loaded | | `plugin :solid_queue if ENV["SOLID_QUEUE_IN_PUMA"]` | runs the job supervisor alongside Puma | off | | `pidfile ENV["PIDFILE"] if ENV["PIDFILE"]` | writes a PID file | none outside development | A few details are worth saying aloud in an interview: - **`RAILS_MAX_THREADS` is read by the file, not by Puma.** Puma's own environment defaults are `PUMA_MAX_THREADS` / `MAX_THREADS`, and its built-in default on CRuby is 0 to 5 threads. The generated file overrides that with an equal min and max of 3, so the pool never shrinks. - **3 is the default since Rails 7.2**, which lowered it from 5. The comment in the file explains why: more threads raise throughput but, because of CRuby's GVL, degrade latency. - **The comment above `threads` tells you to size connection pools** to at least the thread count. It still calls Active Record's setting `pool`, although Rails 8.1's generated database.yml names it `max_connections`. - **`PORT` matters behind Thruster.** In the generated Docker image Thruster listens on port 80 and starts Puma behind it on the port it exports as `PORT`. ## What the file deliberately leaves out: workers The Rails template has **no `workers` directive**. Its comment says you control the process count through `ENV["WEB_CONCURRENCY"]` and should set it only when you want 2 or more workers, and that `auto` starts one worker per available processor. That works because Puma itself reads `WEB_CONCURRENCY` while building its defaults: 1. Unset or empty: Puma's `workers` default is 0, which means **single mode**, one process with its thread pool. 2. A number: that many forked workers under a master process (**cluster mode**). 3. `auto`: `Concurrent.available_processor_count` from concurrent-ruby, which Rails already depends on. So a fresh app on a big server serves every request from one Ruby process until someone sets `WEB_CONCURRENCY`. ## Restarting through tmp/restart.txt `plugin :tmp_restart` creates `tmp/restart.txt` if it is missing and records its modification time. A background thread then checks the file every 2 seconds. When the mtime moves forward, it calls the launcher's `restart`, Puma's **hot restart**: the process re-execs and loads the app afresh. `bin/rails restart` is the matching command. It only touches `tmp/restart.txt`, so it does nothing unless a Puma with this plugin is watching. This is a deliberate restart, not code reloading: in development, Rails' reloader picks up edited files without any restart. ## Reading what Puma actually picked up The quickest check is Puma's boot banner, which `bin/rails server` prints before the first request. On a fresh app it reads, in order: 1. `Puma starting in single mode...`, the mode, decided by the worker count. 2. `* Puma version:` and `* Ruby version:`, useful when a lockfile or base image changed. 3. `* Min threads: 3` and `* Max threads: 3`, the values the `threads` line received. 4. `* Environment: production` (or development), from `RAILS_ENV` or `RACK_ENV`. If the banner says `cluster` and lists a `Master PID`, something in the environment set `WEB_CONCURRENCY`. If the thread counts are not what you expected, look for `RAILS_MAX_THREADS` in the deploy env before suspecting the file. ## Common misreadings - Expecting a `workers` line in the file. Rails 8.1's template has none; the process count comes from the environment. - Treating 5 as the thread default. That is Puma's own CRuby maximum and the pre-7.2 Rails value. - Assuming `plugin :tmp_restart` reacts to code edits. It watches one file's mtime. - Forgetting that `port` is ignored for traffic that never reaches it. In production the container's published port is Thruster's, not Puma's.

  • Which component actually reads RAILS_MAX_THREADS in a new Rails 8.1 app?
    Not Puma's defaults: Puma looks at `PUMA_MAX_THREADS` or `MAX_THREADS`. The generated `config/puma.rb` reads `RAILS_MAX_THREADS` with `ENV.fetch` (fallback 3) and passes it to `threads`. The generated database.yml reads the same variable for `max_connections`, with a fallback of 5, so one variable sizes both the thread pool and the connection pool.
  • What does bin/rails restart do to a running Puma, and when does it do nothing?
    It only touches `tmp/restart.txt`. A Puma that loaded `plugin :tmp_restart` notices the newer mtime within about 2 seconds and performs a hot restart, re-execing and booting the app again. If the plugin line was removed, or the app runs under another server, touching the file changes nothing.

  • The generated puma.rb has a workers line that turns on cluster mode by default.
  • Puma reads RAILS_MAX_THREADS on its own, so the puma.rb line is redundant.
  • A new Rails 8.1 app runs 5 threads per Puma process.
  • plugin :tmp_restart restarts Puma whenever application code is edited.
  • Without PORT set, the generated config makes Puma listen on 9292.

Assumes Rails 8.1's generated config/puma.rb on Puma 8.0; the 3-thread default replaced 5 in Rails 7.2, and the file has no workers line.

open as a page

A ticket-resale Rails 8.1 app on a 4-core server, running the generated config/puma.rb, keeps one core busy; why, and what do you change?

level: middleimportance: must knowfreq 60%

basics

~20 s

With WEB_CONCURRENCY unset, Puma runs a single process, and its 3 threads take turns running Ruby under the GVL, so roughly one core works. Setting WEB_CONCURRENCY=4 (or auto) forks four workers, each with its own threads.

open as a page

In a Rails app on Puma, how should Active Record's connection pool relate to threads and workers, and what breaks when it is too small?

level: middleimportance: should knowfreq 50%

basics

~20 s

Each Puma process has its own Active Record pool, which must hold at least as many connections as that process has threads. Smaller, and threads wait 5 seconds, then raise ActiveRecord::ConnectionTimeoutError; the server's total is workers times pool.

open as a page

In Puma cluster mode for a Rails app, what does preload_app! change, and why can a preloaded cluster not do a phased restart?

level: seniorimportance: should knowfreq 38%

basics

~20 s

preload_app! boots the Rails app once in Puma's master and forks workers from it, sharing memory and speeding worker start. A phased restart re-forks workers from that master, which still holds old code, so Puma falls back to a hot restart.

open as a page