How Passenger + Nginx autodetects applications

If you have followed the deployment instructions then you may have noticed that in many cases, just by pointing the virtual host root to an application's static assets directory, Passenger is able to automatically infer how to start the application. You may wonder how this works, and how Passenger knows what kind of web application it is (Ruby, Python, Node.js, etc). After all, many other polyglot application servers expect you write configuration in which you specify what kind of application it is. You may also wonder what happens if Passenger is not able to autodetect the application.

Table of contents

• Loading...

Rationale

The reason why Passenger tries to autodetect the application, is because it strives to save you from needless work as much as possible. Passenger follows the "convention over configuration" philosophy. If it can reasonably use sane defaults, it will. Having said that, it still allows you to provide configuration if autodetection fails.

Autodetection algorithm

Passenger checks whether the virtual host is a Passenger-supported application through a two-step algorithm:

1. First, it extracts the directory name from the virtual host root, like this: dirname(root). For example, if you set root /webapps/foo/public , then Passenger extracts the /webapps/foo portion of it. We call this the "application root".

2. Passenger checks whether one of the following file(s) exist inside the application root in order to autodetect the application type.

   File	Inferred application type
   app.js	Node.js or Meteor JS in bundled/packaged mode

What happens if autodetection fails

If Passenger does not detect an application inside the application root, then Passenger will let Nginx serve the virtual host root as if Passenger is not activated. This means that Nginx will serve static files, that that it will display a "404 Not Found" error of some sort on the root URL (because Nginx is not configured to show directory listings by default), but not much else.

So if you see an Nginx "404 Not Found" response page instead of your application, then it usually means that Passenger failed to autodetect your application. Try overriding the autodetection as documented below.

Overriding autodetection

If Passenger's autodetection has failed you, or if your application uses directory structure that does not match Passenger's autodetection defaults, then you can add a few configuration options to tell Passenger how your application looks like. The relevant configuration options are:

• passenger_app_root – Tells Passenger where your application root is.
• passenger_app_type – Tells Passenger what kind of application it is.
• passenger_startup_file – Tells Passenger where your application's entry point file is.

Suppose that you have a Node.js application whose entry point file is server.js instead of app.js. Here is an example that shows you how to configure Passenger:

server {
    server_name example.com;
    root /webapps/example.com/public;
    passenger_enabled on;
    # Use server.js as the startup file (entry point file) for
    # your Node.js application, instead of the default app.js
    passenger_startup_file server.js;
    passenger_app_type node;
}