How to set up zero-downtime restarts with Puma?

Use the built-in rolling restart feature by sending the USR2 signal or configuring phased restarts via the control server. Note that preloading cannot be used with phased restarts, as they are incompatible.

Puma vs Unicorn: which is better for Ruby apps?

Puma excels in multi-threaded environments with built-in SSL and better parallelism for IO-bound tasks, while Unicorn is process-based and simpler for CPU-bound applications. Choose Puma for scalability and modern deployments.

Does Puma support HTTP/2 or just HTTP 1.1?

Puma only supports HTTP 1.1. For HTTP/2, you need to use a reverse proxy like NGINX or Caddy in front of Puma to handle the protocol upgrade.

How to optimize thread pool settings for Puma on MRI?

Use the -t flag to set min:max threads, starting with defaults like 0:5. Adjust based on traffic and IO patterns, but avoid high max threads to prevent GVL contention and resource exhaustion.

Can Puma run in cluster mode on Windows or JRuby?

No, cluster mode is not supported on Windows or JRuby due to lack of fork(2). You must use single-process mode on these platforms, which limits scalability and memory efficiency.

How to monitor Puma performance in production?

Use community extensions like puma-metrics for Prometheus or the built-in control server to query stats. Alternatively, integrate with systemd or third-party monitoring tools for real-time metrics.

Puma — Multi-Threaded Ruby HTTP Server

What is Puma?

Puma is a Ruby web server built for parallelism, designed to serve Rack applications with high performance. It uses a multi-threaded and multi-process architecture to handle more requests efficiently, making it the default server for Ruby on Rails. It solves the need for a fast, reliable, and scalable server in Ruby web development.

Target Audience

Ruby developers building web applications with frameworks like Rails or Sinatra who need a high-performance, production-ready web server. It's also suitable for DevOps engineers deploying Ruby applications in self-hosted or cloud environments.

Value Proposition

Developers choose Puma for its battle-tested reliability, built-in parallelism, and seamless integration with Ruby ecosystems. Its ability to run standalone with SSL and support zero-downtime restarts makes it a robust alternative to other Ruby servers.

A Ruby/Rack web server built for parallelism

Use Cases

Best For

Serving Ruby on Rails applications in production environments
High-traffic Ruby web applications requiring parallel request handling
Deploying Rack applications without a reverse proxy
Applications needing zero-downtime rolling restarts
Ruby developers using MRI, JRuby, or Rubinius who want optimized throughput
Self-hosted Ruby deployments with SSL support

Not Ideal For

Applications deployed on Windows that require forked worker processes for memory efficiency
Kubernetes-based deployments where smooth pod shutdowns are critical due to graceful termination issues
Projects needing seamless hot restarts on JRuby or Rubinius without socket downtime
Environments where OpenSSL development files are unavailable and SSL support is mandatory

Pros & Cons

Pros

High Parallelism & Performance

Uses multi-threaded and multi-process architecture to handle concurrent requests efficiently, with cluster mode reducing memory via copy-on-write for better throughput.

Battle-Tested Reliability

Inherits a robust HTTP parser from Mongrel with over 15 years of production use, making it the default and most popular server for Ruby on Rails.

Standalone Deployment Capabilities

Includes built-in SSL support, zero-downtime rolling restarts, and a request bufferer, allowing deployment without a reverse proxy and reducing infrastructure overhead.

Flexible Configuration & Control

Offers extensive setup via CLI, environment variables, or config files with lifecycle hooks, plus a control server for runtime management and monitoring.

Cons

Platform-Specific Limitations

Lacks seamless restarts and cluster mode support on JRuby and Windows, and has known issues with Kubernetes pod shutdowns, limiting deployment flexibility.

Configuration Complexity Risks

Advanced features like thread pool tuning require careful setup to avoid resource exhaustion; misconfigured thread counts can lead to GVL contention on MRI or system overload.

SSL Dependency Hurdles

Requires OpenSSL development files for SSL functionality; if missing, SSL connections are disabled, which can be a barrier in restricted or minimal environments.

What is Puma?

Target Audience

Value Proposition

Use Cases

Best For

Serving Ruby on Rails applications in production environments
High-traffic Ruby web applications requiring parallel request handling
Deploying Rack applications without a reverse proxy
Applications needing zero-downtime rolling restarts
Ruby developers using MRI, JRuby, or Rubinius who want optimized throughput
Self-hosted Ruby deployments with SSL support

Not Ideal For

Applications deployed on Windows that require forked worker processes for memory efficiency
Kubernetes-based deployments where smooth pod shutdowns are critical due to graceful termination issues
Projects needing seamless hot restarts on JRuby or Rubinius without socket downtime
Environments where OpenSSL development files are unavailable and SSL support is mandatory

Pros & Cons

Pros

High Parallelism & Performance

Uses multi-threaded and multi-process architecture to handle concurrent requests efficiently, with cluster mode reducing memory via copy-on-write for better throughput.

Battle-Tested Reliability

Inherits a robust HTTP parser from Mongrel with over 15 years of production use, making it the default and most popular server for Ruby on Rails.

Standalone Deployment Capabilities

Includes built-in SSL support, zero-downtime rolling restarts, and a request bufferer, allowing deployment without a reverse proxy and reducing infrastructure overhead.

Flexible Configuration & Control

Offers extensive setup via CLI, environment variables, or config files with lifecycle hooks, plus a control server for runtime management and monitoring.

Cons

Platform-Specific Limitations

Lacks seamless restarts and cluster mode support on JRuby and Windows, and has known issues with Kubernetes pod shutdowns, limiting deployment flexibility.

Configuration Complexity Risks

Advanced features like thread pool tuning require careful setup to avoid resource exhaustion; misconfigured thread counts can lead to GVL contention on MRI or system overload.

SSL Dependency Hurdles

Requires OpenSSL development files for SSL functionality; if missing, SSL connections are disabled, which can be a barrier in restricted or minimal environments.

Puma

What is Puma?

Overview

Use Cases

Best For

Not Ideal For

Pros & Cons

Pros

Cons

Frequently Asked Questions

Related Projects

Found a gem we're missing?

Puma

What is Puma?

Overview

Use Cases

Best For

Not Ideal For

Pros & Cons

Pros

Cons

Frequently Asked Questions

Related Projects

Found a gem we're missing?