Edit page

Introduction to configuring Passenger + Apache

Passenger in its Apache integration mode is to be configured via the Apache configuration file. There is no configuration file that is specific to Passenger only.

If you have used Passenger Standalone, then you may be familiar with Passengerfile.json. Passenger for Apache does not consult Passengerfile.json, only the Apache configuration file.

Configuring Passenger for Apache works as follows:

  1. During the Passenger installation process, Apache is setup to load the Passenger Apache module.
  2. The Passenger Apache module registers Passenger-specific configuration options inside Apache.
  3. You, the administrator, configure Passenger by adding Passenger-specific configuration options to the Apache configuration file.
  4. Restart or reload Apache to apply any configuration changes.

Here is an example of an Apache configuration file which also configures Passenger:

PassengerRuby /usr/bin/ruby2.0

<VirtualHost *:80>
    ServerName yourserver.com
    DocumentRoot /var/www/myapp/code/public
    PassengerStickySessions on

    <Directory /var/www/myapp/code/public>
        Allow from all
        Options -MultiViews
        Require all granted
    </Directory>
</VirtualHost>

Essential configuration

For Passenger to work, only a few configuration options need to be setup in Apache. If you have already gone through the installation process, then these configuration options are already set.

  1. The LoadModule passenger_module ... option must exist in the Apache configuration. This option tells Apache to load the Passenger module from the given filename. If this option does not exist, then Passenger is not loaded into Apache at all, and Apache will complain about syntax errors whenever it encounters Passenger configuration options.
  2. The PassengerRoot option must exist in the Apache configuration. This option tells Passenger where to find its own resource files. Without this option, Passenger is still loaded, but will not be able to operate.
  3. The PassengerDefaultRuby option does not have to exist, but it is strongly recommended that you set it.

Global, per-application, and per-request options

When configuring Passenger it is important to realize that there are three different types of options that each make sense in different contexts:

  1. Global options. These should be set only once (at the global level). For example, there is one Passenger instance per Apache, so it only makes sense to set the PassengerRoot once in the Apache configuration. Apache will show warnings if you try to declare global options at a lower level such as the <VirtualHost>, because the value will become ambiguous: the first <VirtualHost> section to receive a request would determine the final value.

  2. Per-application options. Options such as PassengerRuby may be different for each application in the Apache config, but not for each request, because the value is needed during application process spawning. Once the process is spawned, changing the value makes no real sense, so per-application options cannot be declared in sections like <Files>, <FilesMatch>, <If>, and files like .htaccess.

  3. Per-request options. This type of option can be set at any level, for any path. For example, Passenger can be enabled or disabled with PassengerEnabled for any <Location>.

Note: the warnings for global options and the concept of per-application options were introduced as part of the work in Passenger version 5.2.0 to make configuration more deterministic.

Start configuring Passenger

Passenger provides a wide range of features and customization options. Some of them are for improving or tweaking the application's performance characteristics, some of them influence application or connection handling behavior, etc. Please visit the configuration index page to learn what you can configure.