1. Support information

1.1. Supported operating systems and languages

1.2. Where to get support

  • Community discussion forum - post a message here if you’re experiencing problems. Support on this forum is provided by the community on a best-effort basis, so a (timely) response is not guaranteed.

  • Issue tracker - report bugs here.

  • Email support@phusion.nl if you are a Phusion Passenger Enterprise customer. Please mention your order reference. If you are not an Enterprise customer, we kindly redirect you to the community discussion forum instead.

  • Commercial support contracts are also available.

  • Report security vulnerabilities to security@phusion.nl. We will do our best to respond to you as quickly as we can, so please do not disclose the vulnerability until then.

Please consult the Phusion Passenger website for a full list of support resources.

2. Installation

2.1. Synopsis

This documentation has moved. Please visit https://www.phusionpassenger.com/library/install/

2.2. Installing or upgrading on Mac OS X with Homebrew

This documentation has moved. Please visit https://www.phusionpassenger.com/library/install/

2.3. Installing or upgrading on Debian or Ubuntu

This documentation has moved. Please visit https://www.phusionpassenger.com/library/install/apt_repo/

2.3.1. Adding our APT repository

This documentation has moved. Please visit https://www.phusionpassenger.com/library/install/apt_repo/

2.3.2. Installing packages

This documentation has moved. Please visit https://www.phusionpassenger.com/library/install/apt_repo/

2.4. Installing or upgrading on Red Hat or CentOS

This documentation has moved. Please visit https://www.phusionpassenger.com/library/install/yum_repo/

2.4.1. Adding our YUM repository

This documentation has moved. Please visit https://www.phusionpassenger.com/library/install/yum_repo/

2.4.2. Installing packages

This documentation has moved. Please visit https://www.phusionpassenger.com/library/install/yum_repo/

2.5. Installing or upgrading on Heroku

Please refer to our Heroku Ruby demo for installation and upgrade instructions for Heroku.

2.6. Generic installation, upgrade and downgrade method: via RubyGems

This documentation has moved. Please visit https://www.phusionpassenger.com/library/install/

2.7. Generic installation, upgrade and downgrade method: via tarball

This documentation has moved. Please visit https://www.phusionpassenger.com/library/install/

2.8. Upgrading from open source to Enterprise

2.9. Cryptographic verification of installation files

2.9.1. Synopsis

2.9.2. Importing the Phusion Software Signing key

2.9.3. Verifying the Phusion Software Signing key

2.9.4. Verifying the gem and tarball

2.9.5. Verifying Git signatures

2.9.6. Verifying Debian packages

2.9.7. Verifying RPM packages

2.9.8. Revocation

2.10. Non-interactive, automatic, headless installs or upgrades

2.11. Customizing the compilation process

2.11.1. Setting the compiler

2.11.2. Adding additional compiler or linker flags

2.11.3. Forcing location of command line tools and dependencies

2.12. Dealing with multiple Apache installations

2.13. Working with the Apache configuration file

2.14. Disabling without uninstalling

2.15. Uninstalling

2.16. Moving to a different directory

3. Deploying a Rack-based Ruby application

This documentation has moved. Please visit https://www.phusionpassenger.com/library/deploy/apache/

3.1. Tutorial/example: writing and deploying a Hello World Rack application

This documentation has moved. Please visit https://www.phusionpassenger.com/library/deploy/apache/

3.2. Deploying to a virtual host’s root

This documentation has moved. Please visit https://www.phusionpassenger.com/library/deploy/apache/

3.3. Deploying to a sub URI

This documentation has moved. Please visit https://www.phusionpassenger.com/library/deploy/apache/

3.4. Redeploying (restarting the Rack application)

3.5. Rackup specifications for various web frameworks

This documentation has moved. Please visit https://www.phusionpassenger.com/library/deploy/config_ru.html

4. Deploying a WSGI (Python) application

This documentation has moved. Please visit https://www.phusionpassenger.com/library/deploy/apache/

4.1. Tutorial/example: writing and deploying a Hello World WSGI application

This documentation has moved. Please visit https://www.phusionpassenger.com/library/deploy/apache/

4.2. Deploying to a virtual host’s root

This documentation has moved. Please visit https://www.phusionpassenger.com/library/deploy/apache/

4.3. Deploying to a sub URI

This documentation has moved. Please visit https://www.phusionpassenger.com/library/deploy/apache/

4.4. Redeploying (restarting the WSGI application)

4.5. Sample passenger_wsgi.py for Django

This documentation has moved. Please visit https://www.phusionpassenger.com/library/deploy/wsgi_spec.html

5. Deploying a Node.js application

This documentation has moved. Please visit https://www.phusionpassenger.com/library/deploy/apache/

6. Deploying a Meteor application

This documentation has moved. Please visit https://www.phusionpassenger.com/library/deploy/apache/

7. Configuring Phusion Passenger

This documentation has moved. Please visit https://www.phusionpassenger.com/library/config/apache/

7.1. PassengerRoot <directory>

7.2. PassengerDefaultRuby <filename>

7.3. Deployment options

7.3.1. PassengerEnabled <on|off>

7.3.2. PassengerBaseURI <uri>

7.4. Application loading options

7.4.1. PassengerRuby <filename>

7.4.2. PassengerPython <filename>

7.4.3. PassengerNodejs <filename>

7.4.4. PassengerMeteorAppSettings <filename>

7.4.5. PassengerAppEnv <string>

7.4.6. RailsEnv <string>

7.4.7. RackEnv <string>

7.4.8. PassengerAppRoot <path/to/root>

7.4.9. PassengerAppGroupName <name>

7.4.10. PassengerAppType <name>

7.4.11. PassengerStartupFile <filename>

7.4.12. PassengerRestartDir <directory>

7.4.13. PassengerSpawnMethod <string>

7.4.14. PassengerLoadShellEnvvars <on|off>

7.4.15. PassengerRollingRestarts <on|off>

7.4.16. PassengerResistDeploymentErrors <on|off>

7.5. Security options

7.5.1. PassengerUserSwitching <on|off>

7.5.2. PassengerUser <username>

7.5.3. PassengerGroup <group name>

7.5.4. PassengerDefaultUser <username>

7.5.5. PassengerDefaultGroup <group name>

7.5.6. PassengerFriendlyErrorPages <on|off>

7.6. Resource control and optimization options

7.6.1. PassengerMaxPoolSize <integer>

7.6.2. PassengerMinInstances <integer>

7.6.3. PassengerMaxInstances <integer>

7.6.4. PassengerMaxInstancesPerApp <integer>

7.6.5. PassengerPoolIdleTime <integer>

7.6.6. PassengerMaxPreloaderIdleTime <integer>

7.6.7. PassengerStartTimeout <seconds>

7.6.8. PassengerConcurrencyModel <process|thread>

7.6.9. PassengerThreadCount <number>

7.6.10. PassengerMaxRequests <integer>

7.6.11. PassengerMaxRequestTime <seconds>

7.6.12. PassengerMemoryLimit <integer>

7.6.13. PassengerStatThrottleRate <integer>

7.6.14. PassengerPreStart <url>

7.6.15. PassengerHighPerformance <on|off>

7.7. Connection handling options

7.7.1. PassengerBufferUpload <on|off>

7.7.2. PassengerBufferResponse <on|off>

7.7.3. PassengerResponseBufferHighWatermark <bytes>

7.7.4. PassengerErrorOverride <on|off>

7.7.5. PassengerMaxRequestQueueSize <number>

7.7.6. PassengerStickySessions <on|off>

7.7.7. PassengerStickySessionsCookieName

7.8. Compatibility options

7.8.1. PassengerResolveSymlinksInDocumentRoot <on|off>

7.8.2. PassengerAllowEncodedSlashes <on|off>

7.9. Logging and debugging options

7.9.1. PassengerLogLevel <integer>

7.9.2. PassengerLogFile <filename>

7.9.3. PassengerFileDescriptorLogFile <filename>

7.9.4. PassengerDebugger <on|off>

7.10. Advanced options

7.10.1. PassengerInstanceRegistryDir <directory>

7.10.2. PassengerDataBufferDir <directory>

7.11. Deprecated or removed options

7.11.1. RailsRuby

7.11.2. RailsBaseURI and RackBaseURI

7.11.3. RailsUserSwitching

7.11.4. RailsDefaultUser

7.11.5. RailsAllowModRewrite

7.11.6. RailsSpawnMethod

7.11.7. RailsAutoDetect, RackAutoDetect and WsgiAutoDetect

7.11.8. RailsAppSpawnerIdleTime

7.11.9. RailsFrameworkSpawnerIdleTime

7.11.10. PassengerDebugLogFile

8. Troubleshooting

8.1. Generic troubleshooting tips

8.2. Why does the first request take a long time?

8.3. I get "command not found" when running a Phusion Passenger command through sudo

8.4. OS X: The installer cannot locate MAMP’s Apache

8.6. Static assets such as images and stylesheets aren’t being displayed

8.7. Apache cannot access my app’s files because of SELinux errors

8.8. The application thinks its not on SSL even though it is

8.9. Ruby on Rails-specific troubleshooting

8.9.1. The "About your application’s environment" link does not work

8.9.2. The Rails application reports that it’s unable to start because of a permission error

8.9.3. The Rails application’s log file is not being written to

There are a couple things that you should be aware of:

  • By default, Phusion Passenger runs Rails applications in production mode, so please be sure to check production.log instead of development.log.

    See RailsEnv for configuration. - By default, Phusion Passenger runs Rails applications as the owner of config.ru. So the log file can only be written to if that user has write permission to the log file. Please chmod or chown your log file accordingly.

    See User switching (security) for details.

If you’re using a RedHat-derived Linux distribution (such as Fedora or CentOS) then it is possible that SELinux is interfering. RedHat’s SELinux policy only allows Apache to read/write directories that have the httpd_sys_content_t security context. Please run the following command to give your Rails application folder that context:

chcon -R -h -t httpd_sys_content_t /path/to/your/rails/app

8.10. Conflicting Apache modules

8.10.2. MultiViews (mod_negotiation)

8.10.3. VirtualDocumentRoot

9. Analysis and system maintenance

9.1. Inspecting memory usage

9.2. Inspecting Phusion Passenger’s internal status

9.3. Debugging frozen applications

If one of your application processes is frozen (stopped responding), then you can figure out where it is frozen by killing it with SIGABRT. This will cause the processs to print a backtrace, after which it aborts. The backtrace information is logged into the web server error log file.

In case of Ruby applications, you can also send the SIGQUIT signal to have it print a backtrace without aborting.

9.4. Accessing individual application processes

9.5. Attaching an IRB console to an application process

10. Tips

10.1. User Switching (security feature)

10.1.1. Requirements

10.1.2. Effects

10.1.3. Caveats & troubleshooting

10.1.4. Red Hat and CentOS caveats

10.1.5. Finding out what user an application is running as

10.2. Copy-on-write memory support (reducing memory consumption of Ruby applications)

Phusion Passenger automatically leverages operating system virtual memory copy-on-write features in order to reduce the memory usage of Ruby applications. Experience has shown that this reduces memory usage by 33% on average. For this mechanism to work, a Ruby interpreter with a copy-on-write friendly garbage collector is required. The following Ruby interpreters have copy-on-write friendly garbage collectors:

  • MRI Ruby >= 2.0. Versions prior to 2.0 did not have a copy-on-write friendly garbage collector.

  • Ruby Enterprise Edition, which was Phusion’s branch of MRI Ruby 1.8 with a copy-on-write friendly garbage collector and other enhancement. It has reached End-Of-Life as of 2012, but remains available for legacy systems.

10.3. Tuning for Server Sent Events and WebSockets

10.4. Bundler support

10.4.1. Does Phusion Passenger itself need to be added to the Gemfile?

10.5. Installing multiple Ruby on Rails versions

Each Ruby on Rails applications that are going to be deployed may require a specific Ruby on Rails version. You can install a specific version with this command:

gem install rails -v X.X.X

where X.X.X is the version number of Ruby on Rails.

All of these versions will exist in parallel, and will not conflict with each other. Phusion Passenger will automatically make use of the correct version.

10.6. Making the application restart after each request

In some situations it might be desirable to restart the web application after each request, for example when developing a non-Rails application that doesn’t support code reloading, or when developing a web framework.

To achieve this, simply create the file tmp/always_restart.txt in your application’s root folder. Unlike restart.txt, Phusion Passenger does not check for this file’s timestamp: Phusion Passenger will always restart the application, as long as always_restart.txt exists.

Note If you’re just developing a Rails application then you probably don’t need this feature. If you set RailsEnv development in your web server configuration, then Rails will automatically reload your application code after each request. always_restart.txt is mostly useful when you’re using a web framework that doesn’t support code reloading by itself, of when you’re working on a web framework yourself.

10.7. How to fix broken images/CSS/JavaScript URIs in sub-URI deployments

Some people experience broken images and other broken static assets when they deploy their application to a sub-URI (i.e. http://mysite.com/railsapp/). The reason for this usually is that you used a static URI for your image in the views. This means your img source probably refers to something like /images/foo.jpg. The leading slash means that it’s an absolute URI: you’re telling the browser to always load http://mysite.com/images/foo.jpg no matter what. The problem is that the image is actually at http://mysite.com/railsapp/images/foo.jpg. There are two ways to fix this.

The first way (not recommended) is to change your view templates to refer to images/foo.jpg. This is a relative URI: note the lack of a leading slash). What this does is making the path relative to the current URI. The problem is that if you use restful URIs, then your images will probably break again when you add a level to the URI. For example, when you’re at http://mysite.com/railsapp the browser will look for http://mysite.com/railsapp/images/foo.jpg. But when you’re at http://mysite.com/railsapp/controller. the browser will look for http://mysite.com/railsapp/controller/images/foo.jpg. So relative URIs usually don’t work well with layout templates.

The second and highly recommended way is to always use Rails helper methods to output tags for static assets. These helper methods automatically take care of prepending the base URI that you’ve deployed the application to. For images there is image_tag, for JavaScript there is javascript_include_tag and for CSS there is stylesheet_link_tag. In the above example you would simply remove the <img> HTML tag and replace it with inline Ruby like this:

<%= image_tag("foo.jpg") %>

This will generate the proper image tag to $RAILS_ROOT/public/images/foo.jpg so that your images will always work no matter what sub-URI you’ve deployed to.

These helper methods are more valuable than you may think. For example they also append a timestamp to the URI to better facilitate HTTP caching. For more information, please refer to the Rails API docs.

10.8. Out-of-Band Work and Out-of-Band Garbage Collection

10.9. Hooks

This documentation has moved. Please visit https://www.phusionpassenger.com/library/indepth/hooks.html

10.9.1. Example

10.9.2. Environment

10.9.3. Blocking and concurrency

10.9.4. Error handling

10.9.5. Compatibility

10.9.6. Available hooks

10.10. Flying Passenger

10.10.1. Requirements

10.10.2. Basic usage

10.10.3. Configuring Flying Passenger

10.10.4. Managing the Flying Passenger daemon

10.10.5. Using Flying Passenger with MRI 1.8 or JRuby

10.10.6. Caveats and limitations

10.11. X-Sendfile support

Phusion Passenger does not provide X-Sendfile support by itself. Please install mod_xsendfile for X-Sendfile support.

10.12. Upload progress

Phusion Passenger does not provide upload progress support by itself. Please try drogus’s Apache upload progress module instead.

11. Under the hood

Phusion Passenger hides a lot of complexity for the end user (i.e. the web server system administrator), but sometimes it is desirable to know what is going on. This section describes a few things that Phusion Passenger does under the hood.

11.1. Page caching support

For each HTTP request, Phusion Passenger will automatically look for a corresponding page cache file, and serve that if it exists. It does this by appending ".html" to the filename that the URI normally maps to, and checking whether that file exists. This check occurs after checking whether the original mapped filename exists (as part of static asset serving). All this is done without the need for special mod_rewrite rules.

For example, suppose that the browser requests /foo/bar.

  1. Phusion Passenger will first check whether this URI maps to a static file, i.e. whether the file foo/bar exists in the web application’s public directory. If it does then Phusion Passenger will serve this file through the web server immediately.

  2. If that doesn’t exist, then Phusion Passenger will check whether the file foo/bar.html exists. If it does then Phusion Passenger will serve this file through the web server immediately.

  3. If foo/bar.html doesn’t exist either, then Phusion Passenger will forward the request to the underlying web application.

Note that Phusion Passenger’s page caching support doesn’t work if your web application uses a non-standard page cache directory, i.e. if it doesn’t cache to the public directory. In that case you’ll need to use mod_rewrite to serve such page cache files.

11.2. Phusion Passenger and its relationship with Ruby

11.2.1. How Ruby is used

11.2.2. When the system has multiple Ruby interpreters

11.3. Static assets serving

Phusion Passenger accelerates serving of static files. This means that, if an URI maps to a file that exists, then Phusion Passenger will let Apache serve that file directly, without hitting the web application.

Phusion Passenger does all this without the need for any mod_rewrite rules. People who are switching from an old Mongrel-based setup might have mod_rewrite rules such as these:

# Check whether this request has a corresponding file; if that
# exists, let Apache serve it, otherwise forward the request to
# Mongrel.
RewriteCond %{DOCUMENT_ROOT}/%{REQUEST_FILENAME} !-f
RewriteRule ^(.*)$ balancer://mongrel%{REQUEST_URI} [P,QSA,L]

These kind of mod_rewrite rules are no longer required, and you can safely remove them.

11.4. How Phusion Passenger detects whether a virtual host is a web application

12. Appendix A: About this document

The text of this document is licensed under the Creative Commons Attribution-Share Alike 3.0 Unported License.

Phusion Passenger is brought to you by Phusion.

Phusion Passenger is a trademark of Hongli Lai & Ninh Bui.

13. Appendix B: Terminology

13.1. Application root

The root directory of an application that’s served by Phusion Passenger.

In case of Ruby on Rails applications, this is the directory that contains Rakefile, app/, config/, public/, etc. In other words, the directory pointed to by RAILS_ROOT. For example, take the following directory structure:

/apps/foo/       <------ This is the Rails application's application root!
   |
   +- app/
   |   |
   |   +- controllers/
   |   |
   |   +- models/
   |   |
   |   +- views/
   |
   +- config/
   |   |
   |   +- environment.rb
   |   |
   |   +- ...
   |
   +- public/
   |   |
   |   +- ...
   |
   +- ...

In case of Rack applications, this is the directory that contains config.ru. For example, take the following directory structure:

/apps/bar/      <----- This is the Rack application's application root!
   |
   +- public/
   |    |
   |    +- ...
   |
   +- config.ru
   |
   +- ...

In case of Python (WSGI) applications, this is the directory that contains passenger_wsgi.py. For example, take the following directory structure:

/apps/baz/      <----- This is the WSGI application's application root!
   |
   +- public/
   |    |
   |    +- ...
   |
   +- passenger_wsgi.py
   |
   +- ...

13.2. Idle process

An "idle process" refers to a process that hasn’t processed any requests for a while.

13.3. Inactive process

An "inactive process" refers to a process that’s current not processing any requests. An idle process is always inactive, but an inactive process is not always considered idle.

14. Appendix C: Spawning methods explained

This documentation has moved. Please visit https://www.phusionpassenger.com/library/indepth/spawn_methods/

14.1. The most straightforward and traditional way: direct spawning

This documentation has moved. Please visit https://www.phusionpassenger.com/library/indepth/spawn_methods/

14.2. The smart spawning method

This documentation has moved. Please visit https://www.phusionpassenger.com/library/indepth/spawn_methods/

14.2.1. How it works

This documentation has moved. Please visit https://www.phusionpassenger.com/library/indepth/spawn_methods/

14.2.2. Summary of benefits

This documentation has moved. Please visit https://www.phusionpassenger.com/library/indepth/spawn_methods/

14.3. Smart spawning caveat #1: unintentional file descriptor sharing

This documentation has moved. Please visit https://www.phusionpassenger.com/library/indepth/spawn_methods/

14.3.1. Example 1: Memcached connection sharing (harmful)

This documentation has moved. Please visit https://www.phusionpassenger.com/library/indepth/spawn_methods/

14.3.2. Example 2: Log file sharing (not harmful)

This documentation has moved. Please visit https://www.phusionpassenger.com/library/indepth/spawn_methods/

14.4. Smart spawning caveat #2: the need to revive threads

This documentation has moved. Please visit https://www.phusionpassenger.com/library/indepth/spawn_methods/

15. Appendix D: About environment variables

15.1. Working with environment variables

15.2. The PATH environment variable

15.2.1. Adding Phusion Passenger’s administration tools to PATH

15.3. Making environment variables permanent

15.3.1. bash

15.3.2. Apache

15.3.3. Nginx

15.3.4. cron

15.3.5. Phusion Passenger-served apps

15.4. Environment variables and sudo