Passenger + Ruby on Rails integration

Passenger integrates with many Ruby on Rails features automatically, without requiring any action from you. A few features require manual integration. Learn how to get the most of out Passenger's integration with Rails.

Table of contents

Automatic integrations

Static assets serving

Passenger automatically serves static assets located in the public subdirectory. Passenger serves these assets through the web server (Apache or Nginx). This offloads Rails from having to serve them, which improves performance.

Caveats

This feature is not available if you use Passenger Standalone with the 'builtin' engine. In all other cases (e.g. Passenger + Nginx, Passenger + Apache and Passenger Standalone with the default 'nginx' engine), this feature is available.

Asset pipeline

Passenger Standalone integrates with the Rails asset pipeline by serving precompiled dynamic assets (such as Javascripts and CSS) located in the public/assets subdirectory. Passenger serves them directly through the web server (Apache or Nginx) which improves performance. Passenger also automatically sets proper caching headers for these assets and turns on gzip compression.

The following caching headers are set:

Cache-Control is set to public.
Expires is set to a date far in the future.

Caveats

This feature is only available in the Standalone integration mode, using the 'nginx' engine.

If you use any of the other integration mode, or if you use Passenger Standalone with the 'builtin' engine, then this asset pipeline integration is not done automatically for you. You will have to configure your web server to achieve the same effect.

If you use Passenger's Nginx integration mode, then you can use the following Nginx configuration snippet in your server block:

# Rails asset pipeline support.
location ~ "^/assets/.+-([0-9a-f]{32}|[0-9a-f]{64})\..+" {
    error_page 490 = @static_asset;
    error_page 491 = @dynamic_request;
    recursive_error_pages on;

    if (-f $request_filename) {
        return 490;
    }
    if (!-f $request_filename) {
        return 491;
    }
}
location @static_asset {
    gzip_static on;
    expires max;
    add_header Cache-Control public;
    add_header ETag "";
}
location @dynamic_request {
    passenger_enabled on;
}

ActionPack page caching

Passenger integrates with ActionPack page caching by checking, for every request, whether there is a corresponding .html file in the public directory. If so, Passenger will serve that HTML file directly through the web server, instead of letting the Rails application handle it.

For example, if the client makes a request to /foo, and there is a foo.html in the public directory, then Passenger will serve foo.html to satisfy the request.

Caveats

This integration only works if you did not customize the page_cache_directory option.

Also note that this feature is not available if you use Passenger Standalone with the 'builtin' engine. In all other cases (e.g. Passenger + Nginx, Passenger + Apache and Passenger Standalone with the default 'nginx' engine), this feature is available.

ActiveRecord and smart spawning

Passenger's smart spawning feature – which is on by default – allows more efficient process management and lowers the application's memory usage. This feature comes with a few caveats, such as the need to reestablish socket connections and other file descriptors after spawning child processes. Fortunately, Passenger can sometimes do this automatically for you.

ActiveRecord establishes a connection with the database, which is a socket connection. So this too needs to be reestablished after Passenger spawns a child process. Passenger is smart enough to reestablish the default ActiveRecord database connection for you automatically.

If your application, or any of the libraries you use, establish any other socket connections (e.g. if you configured ActiveRecord to establish multiple database connections, or if you have Redis connections) then you need to use the Passenger API to reestablish them upon spawning a new child process. Please refer to the spawning methods guide to learn more.

Integrations that require manual action

'rails server' integration

The rails server command is a tool for starting the Rails application in an application server. rails server is not an application server by itself, but is merely a wrapper that delegates control to one of the many application servers available for Ruby, such as Passenger.

Passenger – through its Standalone mode – is able to integrate with the rails server command. This integration happens through the Gemfile:

The Gemfile must load the passenger gem (or for Passenger Enterprise users, the passenger-enterprise-server gem).
The Passenger Gemfile entry must require phusion_passenger/rack_handler.

Here is an example Gemfile entry (for Passenger open source):

gem "passenger", ">= 5.0.25", require: "phusion_passenger/rack_handler"

Caveats

This integration requires Passenger 5.0.25 or higher.

Action Cable integration

Passenger >= 5.0.24 is fully compatible with Action Cable. Please choose a guide depending on your integration mode:

Action Cable is currently not supported on Passenger + Apache. Please use Passenger Standalone or Passenger + Nginx instead. If you cannot move away from Apache, please consider putting Passenger Standalone behind an Apache reverse proxy.