Edit page

How Passenger + Apache 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(DocumentRoot). For example, if you set DocumentRoot /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
    passenger_wsgi.py Python

Note that Passenger does not resolve any symlinks in the DocumentRoot path by default since version 2.2.0. This is in contrast to versions earlier than 2.2.0, which do resolve symlinks.

So for example, suppose that your DocumentRoot points to /home/www/example.com, which in turn is a symlink to /webapps/example.com/public. In versions earlier than 2.2.0, Passenger will check whether /webapps/example.com/config.ru exists because it resolves all symlinks. Passenger 2.2.0 and later however will check for /home/www/config.ru. This file of course doesn't exist, and as a result Passenger will not activate itself for this virtual host, and you'll most likely see an Apache mod_dirindex directory listing.

If you need the old symlink-resolving behavior for whatever reason, then you can turn on PassengerResolveSymlinksInDocumentRoot.

Another way to solve this situation is to explicitly tell Passenger what the correct application root is through the PassengerAppRoot option.

What happens if autodetection fails

If Passenger does not detect an application inside the application root, then Passenger will let Apache serve the virtual host root as if Passenger is not activated. This usually means that the Apache will show a mod_dirindex directory listing and that it will serve static files, but not much else.

So if you see a directory listing 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: