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?
answer
- an env var with a fallback of 3
- PORT falls back to 3000
- a plugin watching tmp/restart.txt
- no workers line in the file
- PIDFILE only when it is set
basics
~20 sRails 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 sThe 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# 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
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.
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.
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.
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.