Introduction to configuring Passenger

Relevant selection for this article:

Passenger in its Standalone mode can be configured through several mechanisms.

You usually only deal with these three mechanisms:

1. The first is through command line arguments passed to the passenger start command.
2. The second is through environment variable (since 5.0.22).
3. The third is through the configuration file Passengerfile.json.

There is also a fourth, more powerful but also more complicated mechanism. Namely configuration through an Nginx configuration template. This is reserved for more advanced uses.

Table of contents

1. Loading...

Configuring through command line options, environment variables and Passengerfile.json

Here is an example which shows you how to configure Passenger Standalone to start on port 4000 instead of the default port 3000, through a command line option:

$ passenger start --port 4000

Here is an example which achieves the same, through the PASSENGER_PORT environment variable:

$ env PASSENGER_PORT=4000 passenger start

And here is an example which achieves the same, through Passengerfile.json.

• In Passengerfile.json:

  {
    "port": "4000"
  }
  

• Passenger command invocation (which automatically uses Passengerfile.json):

  $  passenger start

Empty environment variables are ignored

When configuring Passenger through environment variables, empty variables are ignored. So if you run this command…

$ env PASSENGER_PORT= passenger start

…then it as the same effect as:

$ passenger start

Location of Passengerfile.json

Passengerfile.json must be located in the application directory. This allows you to configure Passenger differently on a per-application basis.

However, if you are using the Mass deployment feature, then Passengerfile.json is handled differently.

Precedence

This information only applies to Passenger 5.0.0 and later.

Configuration sources are respected in the following precedence (ordered from most to least precedence):

• Command line options.
• Environment variables (only since 5.0.22).
• Passengerfile.json.

There is just one exception to this rule. In Mass deployment mode, per-app configuration overrides both command line options and environment variables.

Mass deployment configuration

If you are using the Mass deployment feature, then Passengerfile.json is handled differently than normal.

Main vs per-application configuration

In Mass deployment mode, there may be a main configuration file that configures the behavior of all served applications. Any options passed through command line options are considered part of the main configuration.

Each application may have its own Passengerfile.json, which we call the per-app configuration file. The per-app configuration file overrides configuration in the main configuration. Even command line options are overridden.

Context-specific configuration

Some configuration options can only be specified in the main configuration. They will have no effect when specified in the per-app configuration file. Examples include --log-file / "log_file" and --pid-file / "pid_file".

The reference documents whether a configuration option can only be specified in the main configuration file, or also in the per-app configuration file.

Locations of the configuration files

The main configuration file is also named Passengerfile.json and is looked up as follows:

• If a single directory argument is passed to passenger start, then Passenger looks for the configuration file in that directory.
• Otherwise (if no directory arguments are passed, or if two or more directory arguments are passed), Passenger looks for the main configuration file in the current working directory.

The per-app configuration file is looked up in the application directory.

Relative path handling

Since version 5.0.14, Passenger Standalone accepts relative paths for all its options. Relative paths are handled as follows:

• If the path is specified via a command line argument or environment variable, then it is considered relative to the current working directory.
• If the path is specified via Passengerfile.json, then the path is considered relative to that Passengerfile.json.

Relative path handling in earlier Passenger versions was inconsistent, so we recommend that you upgrade to 5.0.14 or later.

Configuration reference

To learn which command line and Passengerfile.json configuration options are available, please check the configuration reference and the configuration section index page. 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.

Nginx configuration template

Passenger Standalone is built on the same technology that powers Passenger for Nginx, so any configuration option supported by Passenger for Nginx can be applied to Passenger Standalone as well. You can do this by direct editing the Nginx configuration template that is used by Passenger Standalone.

First, create a copy of the default Passenger Nginx configuration template file:

cp $(passenger-config about resourcesdir)/templates/standalone/config.erb nginx.conf.erb

Then open nginx.conf.erb and modify it as you see fit. The file is a normal Nginx configuration file, in the ERB template format.

Every time you start Standalone, you must pass the --nginx-config-template parameter, which tells Standalone to use your specific Nginx configuration template file. For example:

passenger start --nginx-config-template nginx.conf.erb

Alternatively, if you don't want to pass this parameter every time, you can also set the nginx_config_template option in Passengerfile.json.

Debugging configuration file problems

If you run into any problems with your customized Nginx configuration template, then (starting from Passenger 5.0.22) you can debug this by passing the --debug-nginx-config option to passenger start. This will cause it to print the generated Nginx configuration file, then exit.