Scaling: horizontal Puma
This course covers how to size and run a Rails application on Puma, first on one machine and then across several. It explains workers and threads, the GVL, and how cores, memory and database connections limit the worker count. It covers connection pools and PgBouncer, preload_app! and copy-on-write, memory leaks versus fragmentation, and the kinds of Puma restarts. It then looks at statelessness, load balancer routing and health checks, and ends with a full configuration for a 4-core, 8GB host.
What you'll learn
- ✓How Puma workers and threads differ, and how the GVL affects each
- ✓Choosing worker and thread counts from cores, memory, connections and request queue time
- ✓Calculating database connections across hosts, workers and pools
- ✓How preload_app!, copy-on-write and allocator settings affect memory
- ✓Hot restarts, phased restarts, SIGTERM draining and worker_timeout
- ✓What an application needs to run on more than one machine
The two dials: workers and threads
Open config/puma.rb in this repository. Its comments already explain the model, and the file is short enough to read in full:
Read the full lesson free →Curriculum
7 lessonsThe two dials: workers and threads
Explains Puma workers as processes and threads inside them, and why the GVL limits threads to I/O waiting.
Sizing workers and threads
Picks workers from the minimum of cores, memory and connections, and threads from the I/O share of requests.
The connection pool, and other pools
Shows that pools are per process, how total connections multiply across hosts, and when a pooler like PgBouncer helps.
Preload, copy-on-write, and memory
Covers copy-on-write sharing, preload_app! and its trade-off, leaks versus fragmentation, jemalloc and worker killers.
Restarts at the process level
Compares hot restart, phased restart and refork, and explains SIGTERM draining, grace periods and worker_timeout.
Horizontal: beyond one machine
Lists the shared state a second machine needs, the problems with sticky sessions, and load balancer routing choices.
Putting it together: a configuration
Builds a full Puma and Kamal configuration for three 4-core hosts and explains where each value came from.