Puma server configuration in Ruby on Rails - Deep Dive

Overview - Puma server configuration

What is it?

Puma is a web server designed to run Ruby on Rails applications efficiently. It handles incoming web requests and sends responses back to users. Configuring Puma means setting up how it manages threads, workers, and connections to optimize performance and reliability.

Why it matters

Without proper Puma configuration, a Rails app can become slow, unresponsive, or crash under load. Good configuration ensures the app can handle many users at once, use system resources wisely, and recover gracefully from errors. This improves user experience and keeps the app stable in real-world use.

Where it fits

Before learning Puma configuration, you should understand basic Ruby on Rails app structure and how web servers work. After mastering Puma setup, you can explore advanced deployment techniques, monitoring, and scaling Rails apps in production.

Mental Model

Core Idea

Puma configuration controls how many threads and worker processes handle web requests to balance speed, resource use, and reliability.

Think of it like...

Imagine a restaurant kitchen where chefs (workers) and assistants (threads) prepare meals. Configuring Puma is like deciding how many chefs and assistants work together to serve customers quickly without overcrowding the kitchen.

┌───────────────┐
│   Puma Server │
├───────────────┤
│ Workers (processes) │
│  ┌───────────┐  │
│  │ Thread 1  │  │
│  │ Thread 2  │  │
│  │ ...       │  │
│  └───────────┘  │
│ Workers handle requests in parallel
│ Threads inside workers handle multiple requests concurrently
└───────────────┘

Build-Up - 7 Steps

1

Foundation

What is Puma and its role

Concept: Introducing Puma as a web server for Rails apps and its basic function.

Puma is a server that listens for web requests and sends back responses. It runs your Rails app code when users visit your site. Unlike simpler servers, Puma can handle many requests at once using threads and workers.

Result

You understand Puma is the middleman between users and your Rails app, managing multiple requests efficiently.

Knowing Puma's role helps you see why configuring it affects your app's speed and stability.

2

Foundation

Basic Puma configuration file

Concept: How to write a simple Puma config file to set threads and port.

A Puma config file is a Ruby script named 'puma.rb' or similar. It sets options like: threads 5, 5 # minimum and maximum threads port 3000 # port Puma listens on This tells Puma to use 5 threads per worker and listen on port 3000 for requests.

Result

You can create a minimal config file that controls how Puma runs your app locally.

Understanding the config file syntax is key to customizing Puma behavior.

3

Intermediate

Threads vs Workers explained

🤔Before reading on: do you think threads and workers do the same thing or different things? Commit to your answer.

Concept: Introducing the difference between threads (lightweight tasks) and workers (separate processes).

Workers are separate processes that run copies of your app. Threads are smaller units inside each worker that handle requests concurrently. More workers mean better CPU use and fault isolation. More threads mean better concurrency inside each worker.

Result

You can decide how many workers and threads to configure based on your server's CPU cores and memory.

Knowing the difference helps you balance concurrency and resource use to avoid crashes or slowdowns.

4

Intermediate

Configuring Puma for production

🤔Before reading on: should production Puma use more or fewer threads than development? Commit to your answer.

Concept: How to set Puma options for a real production environment, including workers and preload_app.

In production, you often set: workers 2 # number of worker processes threads 5, 5 # threads per worker preload_app! # loads app before forking workers Preloading saves memory by sharing code between workers. Workers improve CPU usage and fault tolerance.

Result

Your app can handle more users simultaneously and recover better from worker crashes.

Understanding production settings prevents common performance bottlenecks and memory waste.

5

Intermediate

Using environment variables in config

Concept: How to make Puma config flexible by reading settings from environment variables.

Instead of hardcoding numbers, use ENV variables: threads_count = ENV.fetch('RAILS_MAX_THREADS') { 5 }.to_i threads threads_count, threads_count This lets you change Puma settings without editing code, useful for different environments.

Result

You can easily tune Puma by changing environment variables during deployment.

Using environment variables makes your config adaptable and easier to manage across environments.

6

Advanced

Handling Puma worker restarts gracefully

🤔Before reading on: do you think Puma restarts workers instantly or waits for requests to finish? Commit to your answer.

Concept: How Puma manages worker restarts without dropping requests using phased restarts and hooks.

Puma supports phased restarts that reload code without downtime. You can add hooks like: on_worker_boot do ActiveRecord::Base.establish_connection end This reconnects the database after a worker restarts, preventing errors.

Result

Your app updates smoothly without losing user requests or crashing database connections.

Knowing restart hooks avoids downtime and common bugs during deployments.

7

Expert

Puma internal threading and event loop

🤔Before reading on: does Puma use a single event loop or multiple? Commit to your answer.

Concept: Deep dive into Puma's internal use of threads and its Reactor pattern for handling IO efficiently.

Puma uses a Reactor pattern where one thread waits for IO events (like network requests) and dispatches them to worker threads. This design allows Puma to handle many connections efficiently without blocking. Each worker process runs its own Reactor and thread pool.

Result

You understand why Puma scales well with many concurrent connections and how it avoids blocking operations.

Understanding Puma's internals helps diagnose performance issues and optimize configuration for high traffic.

Under the Hood

Puma runs as one or more worker processes. Each worker has a thread pool. When a request arrives, Puma's Reactor thread detects it and assigns it to a free worker thread. This allows multiple requests to be processed in parallel without waiting. Preloading the app before forking workers shares memory pages, saving RAM. Worker restarts use hooks to reconnect resources like databases.

Why designed this way?

Puma was designed to be fast and concurrent for Ruby apps, which are often single-threaded. Using multiple workers and threads allows better CPU and IO utilization. The Reactor pattern avoids blocking on slow network calls. Preloading reduces memory use. Alternatives like single-threaded servers or multi-threaded only servers had limitations in concurrency or stability.

┌───────────────┐
│   Master Process   │
│  (Preloads app)   │
└───────┬─────────┘
        │ forks
┌───────▼─────────┐
│   Worker Process │
│ ┌─────────────┐ │
│ │ Reactor     │ │
│ │ Thread      │ │
│ └─────┬───────┘ │
│       │ assigns │
│ ┌─────▼───────┐ │
│ │ Worker      │ │
│ │ Threads     │ │
│ └─────────────┘ │
└─────────────────┘

Myth Busters - 4 Common Misconceptions

Quick: Does increasing threads always improve Puma performance? Commit to yes or no.

Common Belief: More threads always make Puma faster because it can handle more requests.

Reality: Too many threads cause overhead and can exhaust memory or CPU, slowing the app down.

Why it matters: Over-threading leads to crashes or slow response times under load.

Quick: Does setting workers to 1 mean Puma is single-threaded? Commit to yes or no.

Common Belief: One worker means Puma runs only one thread and can't handle multiple requests at once.

Reality: Even one worker can have multiple threads handling requests concurrently.

Why it matters: Misunderstanding this leads to underutilizing Puma's concurrency capabilities.

Quick: Does preload_app! always reduce memory usage? Commit to yes or no.

Common Belief: Using preload_app! always saves memory by sharing code between workers.

Reality: Preloading helps only if your app and Ruby version support copy-on-write memory optimizations.

Why it matters: Assuming preload_app! always saves memory can cause unexpected high memory use.

Quick: Can Puma restart workers instantly without affecting users? Commit to yes or no.

Common Belief: Puma restarts workers immediately, dropping any ongoing requests.

Reality: Puma uses phased restarts to wait for requests to finish before restarting workers.

Why it matters: Knowing this prevents unnecessary downtime and user errors during deployments.

Expert Zone

1

Puma's thread pool size should consider Ruby's Global Interpreter Lock (GIL) which limits true parallel Ruby code execution but allows IO concurrency.

2

Preloading the app before forking workers can cause issues if your app holds connections or state that must be reinitialized per worker.

3

Puma's Reactor thread is single-threaded and must not block; blocking operations should be offloaded to worker threads to maintain responsiveness.

When NOT to use

Puma is not ideal for CPU-heavy Ruby tasks because Ruby's GIL limits parallel execution. For such cases, background job processors like Sidekiq or multi-process architectures are better. Also, for simple apps with very low traffic, simpler servers like WEBrick may suffice.

Production Patterns

In production, Puma is often run behind a reverse proxy like Nginx for SSL termination and load balancing. Configurations use environment variables for flexibility. Workers are set to match CPU cores, threads tuned for expected concurrency, and preload_app! enabled for memory efficiency. Restart hooks ensure database connections are fresh after worker restarts.

Connections

Operating System Processes and Threads

Puma's workers map to OS processes and threads map to OS threads.

Understanding OS-level processes and threads clarifies how Puma manages concurrency and resource isolation.

Event-driven Programming

Puma uses an event loop (Reactor pattern) to handle IO efficiently.

Knowing event-driven design helps understand how Puma handles many connections without blocking.

Restaurant Kitchen Workflow

Puma's workers and threads are like chefs and assistants managing meal orders.

This analogy helps grasp resource allocation and concurrency in server design.

Common Pitfalls

#1 Setting too many threads causing memory exhaustion

Wrong approach:

threads 16, 16
workers 4

Correct approach:

threads 5, 5
workers 4

Root cause:

Misunderstanding that more threads always improve performance without considering memory limits.

#2 Not reconnecting database after worker restart

Wrong approach:

on_worker_boot do
# no database reconnect
end

Correct approach:

on_worker_boot do
ActiveRecord::Base.establish_connection
end

Root cause:

Ignoring that worker processes need fresh DB connections after forking.

#3 Hardcoding port and threads without environment variables

Wrong approach:

port 3000
threads 5, 5

Correct approach:

port ENV.fetch('PORT') { 3000 }
threads_count = ENV.fetch('RAILS_MAX_THREADS') { 5 }.to_i
threads threads_count, threads_count

Root cause:

Lack of flexibility for different deployment environments.

Key Takeaways

Puma is a multi-threaded, multi-worker web server that efficiently handles concurrent Rails requests.

Configuring threads and workers properly balances performance and resource use based on your server and app needs.

Preloading the app before forking workers saves memory but requires careful handling of connections.

Phased restarts and worker boot hooks ensure smooth deployments without downtime or errors.

Understanding Puma's internal Reactor pattern and concurrency model helps optimize and troubleshoot production apps.

Practice

1. What is the main purpose of configuring the threads setting in a Puma server for a Rails app?

easy

A. To control how many requests Puma can handle concurrently within a single worker

B. To set the number of worker processes Puma will spawn

C. To specify the port number Puma listens on

D. To define the Rails environment (development, production, etc.)

Solution

1. Step 1: Understand the role of threads in Puma

   Threads allow Puma to handle multiple requests at the same time inside one worker process.

2. Step 2: Differentiate threads from workers and ports

   Workers are separate processes, ports define network access, threads are about concurrency inside a worker.

3. Final Answer:

   To control how many requests Puma can handle concurrently within a single worker -> Option A

4. Quick Check:

   Threads = concurrent requests per worker [OK]

Hint: Threads = concurrent requests per worker process [OK]

Common Mistakes:

• Confusing threads with workers
• Thinking threads set the port
• Mixing threads with environment settings

2. Which of the following is the correct syntax to set Puma to listen on port 3000 in the configuration file?

easy

A. bind 'tcp://3000'

B. set_port 3000

C. listen 3000

D. port 3000

Solution

1. Step 1: Recall Puma configuration syntax for port

   Puma uses the simple directive port followed by the port number.

2. Step 2: Check other options for correctness

   set_port and listen are not valid Puma config commands; bind requires a full URL, not just a port number.

3. Final Answer:

   port 3000 -> Option D

4. Quick Check:

   Use port to set listening port [OK]

Hint: Use 'port' keyword followed by number [OK]

Common Mistakes:

• Using 'listen' instead of 'port'
• Omitting quotes in 'bind' URL
• Using non-existent 'set_port' command

3. Given this Puma config snippet:

threads 5, 5
workers 2
port 4000

How many total threads can Puma handle at once across all workers?

medium

A. 5

B. 10

C. 2

D. 20

Solution

1. Step 1: Understand threads and workers relationship

   Each worker runs with 5 threads, and there are 2 workers.

2. Step 2: Calculate total threads

   Total threads = threads per worker * number of workers = 5 * 2 = 10. But note the config uses 'threads 5, 5' which means min and max threads are 5, so max threads per worker is 5.

3. Step 3: Re-examine the question carefully

   Actually, the question asks total threads Puma can handle at once across all workers. Since each worker has 5 threads, and there are 2 workers, total is 5 * 2 = 10.

4. Final Answer:

   10 -> Option B

5. Quick Check:

   Threads per worker * workers = 10 [OK]

Hint: Multiply threads by workers for total concurrency [OK]

Common Mistakes:

• Confusing min and max threads
• Ignoring number of workers
• Assuming threads is total, not per worker

4. You added preload_app! in your Puma config but your Rails app crashes on worker boot with a database connection error. What is the most likely fix?

medium

A. Increase the number of workers

B. Remove preload_app! from the config

C. Add a on_worker_boot block to reconnect ActiveRecord

D. Change the port number to 8080

Solution

1. Step 1: Understand what preload_app! does

   It loads the app before workers fork, so connections like database must be re-established in each worker.

2. Step 2: Fix database connection error on worker boot

   Use on_worker_boot block to reconnect ActiveRecord to the database after forking.

3. Final Answer:

   Add a on_worker_boot block to reconnect ActiveRecord -> Option C

4. Quick Check:

   Use on_worker_boot to fix DB connections [OK]

Hint: Reconnect DB in on_worker_boot after preload_app! [OK]

Common Mistakes:

• Removing preload_app! instead of fixing connections
• Changing unrelated settings like port
• Increasing workers without fixing connections

5. You want Puma to run with 3 workers and a thread pool between 2 and 6 threads per worker. You also want to ensure your Rails app reconnects to the database properly after forking. Which Puma config snippet correctly achieves this?

hard

A. threads 2, 6\nworkers 3\npreload_app!\non_worker_boot do\n ActiveRecord::Base.establish_connection\nend

B. workers 3\nthreads 6, 2\npreload_app!\non_worker_boot do\n ActiveRecord::Base.connection.disconnect!\nend

C. threads 2, 6\nworkers 3\nport 3000\non_worker_boot do\n ActiveRecord::Base.establish_connection\nend

D. workers 3\nthreads 2, 6\npreload_app!\non_worker_boot do\n ActiveRecord::Base.connection.reconnect!\nend

Solution

1. Step 1: Set threads and workers correctly

   Threads should be set as threads 2, 6 for min and max, and workers as 3.

2. Step 2: Use preload_app! and reconnect DB properly

   preload_app! must be present, and on_worker_boot should call ActiveRecord::Base.establish_connection to reconnect DB.

3. Step 3: Check each option for correctness

   threads 2, 6\nworkers 3\npreload_app!\non_worker_boot do\n ActiveRecord::Base.establish_connection\nend matches all requirements. workers 3\nthreads 6, 2\npreload_app!\non_worker_boot do\n ActiveRecord::Base.connection.disconnect!\nend reverses thread min/max and disconnects DB incorrectly. threads 2, 6\nworkers 3\nport 3000\non_worker_boot do\n ActiveRecord::Base.establish_connection\nend misses preload_app!. workers 3\nthreads 2, 6\npreload_app!\non_worker_boot do\n ActiveRecord::Base.connection.reconnect!\nend uses a non-existent reconnect! method.

4. Final Answer:

   threads 2, 6 workers 3 preload_app! on_worker_boot do ActiveRecord::Base.establish_connection end -> Option A

5. Quick Check:

   Correct threads, workers, preload_app!, and DB reconnect [OK]

Hint: Use preload_app! with on_worker_boot to reconnect DB [OK]

Common Mistakes:

• Swapping min and max threads
• Omitting preload_app!
• Using wrong DB reconnect method