Puma server configuration in Ruby on Rails - Step-by-Step Execution

Concept Flow - Puma server configuration

Start Puma Server

↓

Load config/puma.rb

↓

Set Threads min and max

↓

Set Worker count

↓

Bind to port or socket

↓

Preload app if enabled

↓

Start workers and threads

↓

Listen for requests

↓

Handle requests concurrently

↓

Shutdown gracefully on signal

Puma server starts by loading its configuration, sets threads and workers, binds to a port or socket, preloads the app if configured, then runs workers and threads to handle requests concurrently until shutdown.

Execution Sample

Ruby on Rails

threads_count = ENV.fetch("RAILS_MAX_THREADS") { 5 }
threads threads_count, threads_count
port ENV.fetch("PORT") { 3000 }
workers ENV.fetch("WEB_CONCURRENCY") { 2 }
preload_app!
plugin :tmp_restart

This Puma config sets thread count, port, worker count, preloads the app, and enables restart plugin.

Execution Table

Step	Action	Value/Setting	Effect
1	Fetch RAILS_MAX_THREADS	5 (default)	Set min and max threads to 5
2	Set threads	5, 5	Puma will use 5 threads per worker
3	Fetch PORT	3000 (default)	Puma binds to port 3000
4	Fetch WEB_CONCURRENCY	2 (default)	Puma will start 2 worker processes
5	Call preload_app!	Enabled	App code loaded before workers fork
6	Enable plugin :tmp_restart	Enabled	Allows restart via rails restart command
7	Start workers and threads	2 workers x 5 threads	Server ready to handle requests concurrently
8	Listen for requests	Port 3000	Server accepts incoming HTTP requests
9	Shutdown signal received	SIGTERM or SIGINT	Server stops workers and threads gracefully

💡 Server stops when shutdown signal is received

Variable Tracker

Variable	Initial	After Fetch	Final
threads_count	undefined	5	5
port	undefined	3000	3000
workers	undefined	2	2
preload_app	false	true	true

Key Moments - 3 Insights

Why do we set both minimum and maximum threads to the same number?

Setting min and max threads equal fixes the thread pool size, ensuring consistent concurrency as shown in execution_table step 2.

What does preload_app! do and why is it important?

preload_app! loads the app before workers fork, saving memory and speeding worker startup, as seen in step 5.

How does Puma handle multiple requests at the same time?

Puma uses multiple workers and threads (step 7) to handle requests concurrently, improving performance.

Visual Quiz - 3 Questions

Look at the execution_table, what is the thread count set to after fetching RAILS_MAX_THREADS?

A 5

B 2

C 3000

D Undefined

💡 Hint

Check execution_table row 1 under Value/Setting column

At which step does Puma bind to the port to listen for requests?

A Step 3

B Step 6

C Step 8

D Step 5

💡 Hint

Look for 'Listen for requests' in execution_table

If WEB_CONCURRENCY is changed to 4, how does the final worker count change?

A Workers remain 2

B Workers become 4

C Workers become 5

D Workers become 3000

💡 Hint

See variable_tracker row for workers and execution_table step 4

Concept Snapshot

Puma server config sets threads and workers for concurrency.
Use ENV variables with defaults for flexibility.
preload_app! loads app before forking workers.
Bind to port or socket to accept requests.
plugin :tmp_restart enables easy server restart.
Graceful shutdown on signals ensures clean exit.

Full Transcript

Puma server configuration starts by reading environment variables or defaults to set thread counts and worker processes. Threads control concurrency within each worker, while workers allow multiple processes for better performance. The preload_app! directive loads the application code before workers fork, saving memory and speeding startup. Puma binds to a specified port or socket to listen for incoming requests. The plugin :tmp_restart enables restarting Puma with the rails restart command. When a shutdown signal is received, Puma gracefully stops all workers and threads. This setup allows Puma to handle many requests efficiently and reliably.

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