How Passenger Standalone autodetects applications

If you have follows the deployment instructions then you may have noticed that in many cases, just by running passenger start, Passenger is able to automatically infer how to start the application and where your static assets are. 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...


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 application directory is a Passenger-supported application by checking whether one of the following file(s) exist:

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

What happens if autodetection fails

If Passenger Standalone does not detect an application inside the application directory, then it will try to serve static files. Since Passenger Standalone does not show directory listings, it will display a "404 Not Found" error of some sort on the root URL.

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

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:

passenger start --app-type node --startup-file server.js

Static assets

Passenger Standalone automatically serves static assets from the public directory in the application directory. This can be overridden with the --static-files-dir / "static_files_dir" option.