Phusion Passenger users guide, Apache version

Phusion Passenger works on any POSIX-compliant operating system. In other words: practically any operating system on earth, except Microsoft Windows.

Phusion Passenger is confirmed on a large number of operating systems and Linux distributions, including, but not limited to, Ubuntu, Debian, CentOS/Fedora/RHEL, Gentoo, Mac OS X, FreeBSD and Solaris. OpenBSD is supported since version 5.2. Both 32-bit and 64-bit platforms are supported.

Please report a bug or join our discussion forum if it doesn’t work on your POSIX-compliant operating system.

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

The Phusion Passenger installation process consists of two steps:

Because Phusion Passenger is designed to run in a wide variety of operating systems and configurations, both steps can be done in multiple ways. Most users — especially first-time users — will be satisfied with the generic installation instructions which covers both steps. However some users may prefer OS-specific installation instructions, which allow Phusion Passenger to better integrate into the operating system. Better integration is characterized by following OS-specific conventions.

If you are not familiar with system administration and do not understand all the choices, then we recommend you to go with the RubyGems generic installation method (if you’re a Ruby user) or the tarball generic installation method (if you’re not a Ruby user).

The steps for upgrading or downgrading Phusion Passenger is almost the same as the steps for installing. All the installation guides in this section will also teach you how to upgrade and downgrade.

RubyGems is only used as a method to obtain the Phusion Passenger files, so in case you have multiple Ruby versions it does not matter which Ruby’s RubyGems you use for installation. Once installed, Phusion Passenger can work with all other Ruby versions on your system. This is explained in Phusion Passenger and its relationship with Ruby.

Ruby may either be installed in the home directory, or system-wide. If it’s installed system-wide then we will want to install gems system-wide as well, so you need to switch to a root prompt first. If Ruby is installed in the home directory then we will want to install gems to the home directory as well, as a normal user.

To find out which case applies, run the following command to find out where the ruby command is:

Do you see a filename that references /home or /Users? If so then your Ruby interpreter is installed in your home directory and you can proceed to step 2. Otherwise, you need to switch to a root prompt by running one of the following commands:

You must maintain this root prompt throughout this installation guide.

Install the latest gem to obtain the files for the latest stable version of the open source Phusion Passenger:

Sometimes you will want to obtain the latest beta version of Phusion Passenger. Beta versions are not normally selected by gem install, so to opt-in for beta versions you have to add the --pre argument:

If you want to obtain a specific version of Phusion Passenger, e.g. because you are downgrading, then specify the version number with --version:

If you want to obtain a specific beta version of Phusion Passenger then you must also pass --pre:

First, download the license key from the Customer Area and save it as /etc/passenger-enterprise-license.

Next, add the Phusion Passenger Enterprise gem server to your RubyGems source list:

Substitute YOUR_ORDER_REFERENCE and YOUR_PASSWORD with your Customer Area login credentials. And notice the trailing slash in the URL! It is very important.

Finally, install the latest gem to obtain the files for the latest stable version of the open source Phusion Passenger:

Sometimes you will want to obtain the latest beta version of Phusion Passenger Enterprise. Beta versions are not normally selected by gem install, so to opt-in for beta versions you have to add the --pre argument:

If you want to obtain a specific version of Phusion Passenger Enterprise, e.g. because you are downgrading, then specify the version number with --version:

If you want to obtain a specific beta version of Phusion Passenger then you must also pass --pre:

If in step 1 you determined that your Ruby interpreter is installed in your home directory, then you need to make sure that the Phusion Passenger gem directory is accessible by your web server. To do that, you must ensure that the Phusion Passenger gem directory, as well as all parent directories, have the world-executable permission.

To find out where the Phusion Passenger gem directory is, run:

Suppose that the above command outputs /home/phusion/.rvm/gems/ruby-1.9.3-p362/gems/passenger-x.x.x. Then you chmod o+x the directory itself and all parent directories up until /home/phusion:

The Phusion Passenger gem only contains source files. In this step we will use the installer to compile the Phusion Passenger binaries, which include the various Phusion Passenger agent executables and the Phusion Passenger Apache module.

Run the following command and follow the on-screen instructions.

At the end of the installation process, you will be asked to copy and paste a configuration snippet (containing LoadModule, PassengerRoot, etc.) into your Apache configuration file. If you’re upgrading, then you already had a similar configuration snippet. Be sure to remove the old one before pasting the new one.

Different operating systems and Apache installations have different conventions with regard to where the Apache configuration file is and how it is organized. Please read Working with the Apache configuration file if you’re not familiar with it. That section is especially of interest for OS X Server >= 10.8 users because the configuration file may not be at a surprising location.

If compilation doesn’t succeed, then please consult the Troubleshooting section.

Despite the name, this "installer" doesn’t actually install anything. The installer checks whether all required dependencies are installed, invokes the compiler, and tells you how to modify the Apache configuration file. However, it doesn’t copy any files to outside the Phusion Passenger source directory.

passenger-install-apache2-module is actually just a user-friendly frontend around the command rake apache2, which performs the actual compilation of Phusion Passenger.

If you are using Flying Passenger then you must restart the Flying Passenger daemon by sending it the SIGTERM signal:

Or, if Flying Passenger is not running with a PID file, look up its PID us ps and then send it SIGTERM:

Restart your web server and run:

You should see the web server processes as well as a number of Phusion Passenger processes (e.g. PassengerWatchdog, PassengerHelperAgent). Congratulations, Phusion Passenger is now installed and running!

If the output is not as expected, then please refer to the Troubleshooting section.

Download the open source Phusion Passenger tarball from the Phusion Passenger website. Older versions can be found on the release archive.

If you a Phusion Passenger Enterprise customer, download the Phusion Passenger Enterprise tarball from the Customer Area. Also be sure to download the license key and save it as /etc/passenger-enterprise-license.

Once you have downloaded the tarball, pick a location to extract it to. You can pick any location. A good location is /opt/passenger. Let’s call this location $PREFIX. Create this directory and extract the tarball as follows:

Note that passenger-x.x.x should be passenger-enterprise-server-x.x.x if you’re using Phusion Passenger Enterprise.

The Phusion Passenger directory must be accessible by the web server and by any web apps you want to run. To do that, you must ensure that the Phusion Passenger gem directory, as well as all parent directories, have the world-executable permission.

Suppose that the Phusion Passenger directory is /opt/passenger/passenger-4.0.0. Run chmod o+x on the directory itself and all parent directories.

Phusion Passenger supports multiple languages and its core is written in C++, but its installer and administration tools are written in Ruby, so you must install that.

Even though Ruby is required, Ruby will normally not be loaded during normal operation unless you deploy a Ruby web application on Phusion Passenger. Phusion Passenger’s dependency on Ruby is very minimal. See Phusion Passenger and its relationship with Ruby for details.

Run ruby --version and rake --version to find out whether both commands are already installed and recent enough. Phusion Passenger requires Ruby >= 1.8.6. Any Rake version will do.

We recommend you to use the Brightbox Ruby packages. They provide more up-to-date versions of Ruby than Debian’s official repositories provide. Their Ubuntu Lucid repository is compatible with Debian 6. If you do not want to use the Brightbox repository, then follow the instructions for Debian 5.

Add the Brightbox repository and install the Bright APT public key:

Then install Ruby and Rake:

Run:

Then add the RubyGems bin directory to your $PATH.

We recommend you to use the Brightbox Ruby packages. They provide more up-to-date versions of Ruby than Ubuntu’s official repositories provide. Add the Brightbox repository as follows:

Then install Ruby and Rake:

Please install Ruby from the Ruby website. Once Ruby is installed, run the following command (possibly as root) to install Rake:

Depending on whether you installed Ruby system-wide, you need to enter a root prompt before continuing to step 5. Please refer to this section.

Please refer to this section. Note that the passenger-install-apache2-module command is inside the bin subdirectory of the Phusion Passenger source directory, so you would have to run something like /opt/passenger/passenger-x.x.x/bin/passenger-install-apache2-module.

If you are using Flying Passenger then you must restart the Flying Passenger daemon by sending it the SIGTERM signal:

Or, if Flying Passenger is not running with a PID file, look up its PID us ps and then send it SIGTERM:

Please refer to this section. Note that all Phusion Passenger administration scripts are located inside the bin subdirectory of the Phusion Passenger source directory, so you would have to run something like /opt/passenger/passenger-x.x.x/bin/passenger-memory-stats.

John Leach from Brightbox has kindly provided Ubuntu packages for Phusion Passenger. The Ubuntu Lucid packages are compatible with Debian 6. The packages are available from the Brightbox repository. Only packages for the open source version of Phusion Passenger are provided. Phusion Passenger Enterprise customers should use the generic RubyGems installation method or the generic tarball installation method instead.

If you use these packages to install Phusion Passenger then you do not need to run passenger-install-apache2-module or passenger-install-nginx-module. These packages contain all the binaries that you need.

First register the Brightbox Apache PPA. Run this on Ubuntu:

On Debian, the apt-add-repository command isn’t available so you have to install the repository and the key by hand:

Once the PPA is added, you can proceed with installing Phusion Passenger for Apache by running:

The Apache package provides configuration snippets for you, so you don’t need to modify any Apache configuration to get it to load Phusion Passenger.

First register the Brightbox Apache PPA. Run this on Ubuntu:

On Debian, the apt-add-repository command isn’t available so you have to install the repository and the key by hand:

Once the PPA is added, you can proceed with installing Phusion Passenger for Nginx by running:

You’ll then need to enable the Phusion Passenger module in Nginx by creating the following configuration file:

Then restart Nginx to apply the changes:

First register the Brightbox Apache PPA. Run this on Ubuntu:

On Debian, the apt-add-repository command isn’t available so you have to install the repository and the key by hand:

Once the PPA is added, you can proceed with installing Phusion Passenger for Apache by running:

You can then proceed with starting Phusion Passenger Standalone:

YUM repositories with RPMs are maintained by Erik Ogan and Stealthy Monkeys Consulting. Only packages for the open source version of Phusion Passenger are provided. Phusion Passenger Enterprise customers should use the generic RubyGems installation method or the generic tarball installation method instead.

If you use YUM to install Phusion Passenger then you do not need to run passenger-install-apache2-module or passenger-install-nginx-module. The YUM packages contain all the binaries that you need. You also don’t need to modify any Apache or Nginx configuration to get them to load Phusion Passenger, the packages provide configuration snippets for you as well.

Install the passenger-release package from the main repository.

Fedora Core 17:

Fedora Core 16:

Fedora Core 15:

Fedora Core 14:

RHEL 6 / CentOS 6 / ScientificLinux 6: (Note: these packages depend on EPEL.)

RHEL 5 / CentOS 5 / ScientificLinux 5: (Note: these packages depend on EPEL.)

From there you can use YUM to install packages. For example, try one of these:

Phusion Passenger for Apache:

Phusion Passenger for Nginx:

Phusion Passenger Standalone:

There are instructions for building your own packages and Yum repositories in the rpm directory ReadMe within the GitHub repository.

Every time we release a new Phusion Passenger version, we make it available through Homebrew. Please note that the Homebrew maintainers have to merge our pull requests manually, so it may take a day or two before a new version shows up in the official Homebrew repository.

Phusion Passenger Enterprise is currently not available through Homebrew. Please try one of the other installation methods insteads.

Phusion Passenger comes in two variants: an open source version, as well as an Enterprise version which introduces a myriad of useful features that can improve stability and performance and efficiency.

Customers who have bought Phusion Passenger Enterprise can upgrade their open source installation to Enterprise as follows:

The uninstallation is necessary because the Enterprise Ruby gem has a different gem name (passenger-enterprise-server instead of passenger), but the same administration command names (e.g. passenger-status). Uninstalling the open source version avoids any conflicts.

By default, the installer (passenger-install-apache2-module) is interactive. If you want to automate installation then you can do so by passing --auto to the installer. See also passenger-install-apache2-module --help for more options.

The Phusion Passenger compilation process can be customized with environment variables. You can learn more about environment variables in About environment variables.

On most systems the Apache configuration file is located in either /etc/apache2/httpd.conf or /etc/apache2/apache2.conf. However, to allow better organization, many operating systems and Apache distributions also read configuration files in the conf.d, mods-enabled and sites-enabled subdirectories.

mods-enabled contains symlinks to files in mods-available. This latter subdirectory contains config files for all available modules, while mods-enabled contains only a subset, namely the modules that should actually be enabled. The symlinks are created using the a2enmod tool. .load files contain LoadModule directives, while .conf files contain all other configuration directives.

Use mods-enabled/mods-available to store Phusion Passenger configuration if you can:

If the mods-enabled mechanism is not available then you can paste configuration snippets into httpd.conf or apache2.conf directly.

On OS X Server >= 10.8 Mountain Lion the location of the Apache configuration file depends on whether you use Web Services or not. If you do, then the configuration file is in /Library/Server/Web/Config/apache2/httpd_server_app.conf. If you do not, then the configuration file is in /etc/apache2/httpd.conf.

You can temporarily unload (disable) Phusion Passenger from the web server, without uninstalling the Phusion Passenger files, so that the web server behaves as if Phusion Passenger was never installed in the first place. This might be useful to you if - for example - you seem to be experiencing a problem caused by Phusion Passenger, but you want to make sure whether that’s actually the case without having to through the hassle of uninstalling Phusion Passenger completely. When disabled, Phusion Passenger will not occupy any memory or CPU or otherwise interfere with the web server.

To unload Phusion Passenger from the web server, edit your Apache configuration file(s) and comment out:

For example, if your configuration file looks like this…

…then comment out the relevant directives, so that it looks like this:

After you’ve done this, save the configuration file and restart the web server.

To uninstall Phusion Passenger, please first remove all Phusion Passenger configuration directives from your web server configuration file(s). After you’ve done this, you need to remove the Phusion Passenger files.

If you installed Phusion Passenger through a tarball then you can move the Phusion Passenger directory to another location. This is not possible if you used any of the other installation methods.

First, move the directory to whereever you like:

Next you must tell your web server that Phusion Passenger has moved. Open your Apache configuration file and set the PassengerRoot directive to the new location:

Restart your web server to finalize the change.

Add a virtual host entry to your Apache configuration file. Make sure that the following conditions are met:

For example:

You may also need to tweak your file/folder permissions. Make sure that the following folders are readable and executable by Apache:

Then restart Apache. The application has now been deployed.

Suppose that you already have a virtual host:

And you want your Ruby on Rails application to be accessible from the URL http://www.phusion.nl/rails.

To do this, make a symlink in the virtual host’s document root, and have it point to your Ruby on Rails application’s public folder. For example:

Next, add a RailsBaseURI option to the virtual host configuration, and also make sure that:

For example:

Then restart Apache. The application has now been deployed.

Deploying a new version of a Ruby on Rails application is as simple as re-uploading the application files, and restarting the application.

There are two ways to restart the application:

For example, to restart our example MyCook application, we type this in the command line:

Please note that, unlike earlier versions of Phusion Passenger, restart.txt is not automatically deleted. Phusion Passenger checks whether the timestamp of this file has changed in order to determine whether the application should be restarted.

Phusion Passenger is not related to Ruby on Rails migrations in any way. To run migrations on your deployment server, please login to your deployment server (e.g. with ssh) and type rake db:migrate RAILS_ENV=production in a shell console, just like one would normally run migrations.

See Capistrano recipe.

First we create a Phusion Passenger-compliant Rack directory structure:

Next, we write a minimal "hello world" Rack application:

Finally, we deploy it by adding the following configuration options to the Apache configuration file:

And we’re done! After an Apache restart, the above Rack application will be available under the URL http://www.rackexample.com/.

Add a virtual host entry to your Apache configuration file. Make sure that the following conditions are met:

For example:

You may also need to tweak your file/folder permissions. Make sure that the following folders are readable and executable by Apache:

Then restart Apache. The application has now been deployed.

Suppose that you already have a virtual host:

And you want your Rack application to be accessible from the URL http://www.phusion.nl/rack.

To do this, make a symlink in the virtual host’s document root, and have it point to your Rack application’s public folder. For example:

Next, add a RackBaseURI option to the virtual host configuration, and also make sure that:

For example:

Then restart Apache. The application has now been deployed.

Deploying a new version of a Rack application is as simple as re-uploading the application files, and restarting the application.

There are two ways to restart the application:

For example, to restart our example application, we type this in the command line:

This subsection shows example config.ru files for various web frameworks.

First we create a Phusion Passenger-compliant WSGI directory structure:

Next, we write a minimal "hello world" WSGI application:

Finally, we deploy it by adding the following configuration options to the Apache configuration file:

And we’re done! After an Apache restart, the above WSGI application will be available under the URL http://www.wsgiexample.com/.

Add a virtual host entry to your Apache configuration file. Make sure that the following conditions are met:

For example:

You may also need to tweak your file/folder permissions. Make sure that the following folders are readable and executable by Apache:

Then restart Apache. The application has now been deployed.

Deploying a new version of a WSGI application is as simple as re-uploading the application files, and restarting the application.

There are two ways to restart the application:

For example, to restart our example application, we type this in the command line:

The location to the Phusion Passenger root directory. This configuration option is essential to Phusion Passenger, and allows Phusion Passenger to locate its own data files. The correct value is given by the installer.

If you’ve moved Phusion Passenger to a different directory then you need to update this option as well. Please read Moving Phusion Passenger to a different directory for more information.

This required option may only occur once, in the global server configuration.

Introduced in version 4.0.0.

This option specifies the default Ruby interpreter to use for web apps as well as for all sorts of internal Phusion Passenger helper scripts, e.g. the one used by PassengerPreStart. Please see PassengerRuby for more information, as well as how it relates to PassengerRuby.

This option may occur in the global server configuration. The default value is ruby, meaning that the Ruby interpreter will be looked up according to the PATH environment variable.

The PassengerDefaultRuby and PassengerRuby directives specify the Ruby interpreter to use. Similarly, the PassengerPython directive is for specifying the Python interpreter.

The relationship between PassengerDefaultRuby and PassengerRuby is as follows:

Phusion Passenger not only uses Ruby to run web apps, but also for running certain helper tools that are written in Ruby, e.g. the internal helper script used by PassengerPreStart. These tools are always run using PassengerDefaultRuby, never by PassengerRuby. PassengerRuby is only used for running web apps. You can learn more about the internal helper scripts in Phusion Passenger and its relationship with Ruby.

It is okay if PassengerDefaultRuby refers to a different Ruby interpreter than the one you originally installed Phusion Passenger with. This too is explained in Phusion Passenger and its relationship with Ruby.

The reason why PassengerDefaultRuby exists at all is because limitations in the Apache API prevents us from implementing the same behavior using only the PassengerRuby directive.

There is no PassengerDefaultPython because there are no Phusion Passenger tools written in Python. As such, having PassengerPython is enough.

The following example illustrates how it works and how you can use these options to specify different Ruby/Python interpreters for different web apps.

Phusion Passenger provides the passenger-config --ruby-command tool for figuring out the correct command for invoking a specific Ruby interpreter. This is especially useful for RVM users. Suppose that you have both Ruby 1.8.7 and Ruby 1.9.3 installed through RVM, and you want to know the correct commands for each Ruby interpreter.

For this purpose we’ll want to invoke passenger-config using its full path, because each time you rvm use a different Ruby interpreter, RVM changes $PATH. If you did not install Phusion Passenger through the generic tarball installation method, then here’s how you can figure out where passenger-config is:

Now, switch to all the RVM Ruby interpreters you want to use. In each interpreter, invoke passenger-config --ruby-command. For Ruby 1.8.7:

Then, for Ruby 1.9.3:

Introduced in version 4.0.0.

This option allows one to specify the Python interpreter to use. See PassengerRuby for more information. The default value is python, meaning that the Python interpreter will be looked up according to the PATH environment variable.

By default, Phusion Passenger assumes that the application’s root directory is the parent directory of the public directory. This option allows one to specify the application’s root independently from the DocumentRoot, which is useful if the public directory lives in a non-standard place.

This option may occur in the following places:

In each place, it may be specified at most once.

Example:

Internally, Phusion Passenger spawns multiple Ruby application processes in order to handle requests. But there are multiple ways with which processes can be spawned, each having its own set of pros and cons. Supported spawn methods are:

This option may occur in the following places:

In each place, it may be specified at most once. The default value is smart.

You can set this option to off to completely disable Phusion Passenger for a certain location. This is useful if, for example, you want to integrate a PHP application into the same virtual host as a Rails application.

Suppose that you have a Rails application in /apps/foo. Suppose that you’ve dropped Wordpress — a blogging application written in PHP — in /apps/foo/public/wordpress. You can then configure Phusion Passenger as follows:

This way, Phusion Passenger will not interfere with Wordpress.

PassengerEnabled may occur in the following places:

In each place, it may be specified at most once. The default value is on.

Specifies the directory that Phusion Passenger should use for storing temporary files. This includes things such as Unix socket files, buffered file uploads (see also PassengerUploadBufferDir), etc.

This option may be specified once, in the global server configuration. The default temp directory that Phusion Passenger uses is /tmp.

This option is especially useful if Apache is not allowed to write to /tmp (which is the case on some systems with strict SELinux policies) or if the partition that /tmp lives on doesn’t have enough disk space.

Some Phusion Passenger command line administration tools, such as passenger-status, must know what Phusion Passenger’s temp directory is in order to function properly. You can pass the directory through the PASSENGER_TMPDIR environment variable, or the TMPDIR environment variable (the former will be used if both are specified).

For example, if you set PassengerTempDir to /my_temp_dir, then invoke passenger-status after you’ve set the PASSENGER_TMPDIR or TMPDIR environment variable, like this:

Phusion Passenger buffers large file uploads to disk in order prevent slow file uploads from blocking web applications. By default, a subdirectory in the system’s temporary files directory (or a subdirectory in the directory specified in PassengerTempDir, if set) is automatically created for storing these buffered file uploads.

This configuration directive allows you to specify a different directory for storing buffered file uploads. If you’ve specified such a directory (as opposed to using Phusion Passenger’s default) then you must ensure that this directory exists.

This configuration directive is also useful if you’re using apache2-mpm-itk. The buffered file upload directory that Phusion Passenger creates by default has very strict permissions: it can only be accessed by the Apache worker processes. However, Phusion Passenger assumes that all Apache worker processes are running as the same user. apache2-mpm-itk breaks this assumption by running multiple Apache worker processes as different users. So if you’re using apace2-mpm-itk, you should set this option to a directory that is writable by all Apache worker processes, such as /tmp.

You may specify PassengerUploadBufferDir in the following places:

In each place, it may be specified at most once.

As described in the deployment chapters of this document, Phusion Passenger checks the file tmp/restart.txt in the applications' root directory for restarting applications. Sometimes it may be desirable for Phusion Passenger to look in a different directory instead, for example for security reasons (see below). This option allows you to customize the directory in which restart.txt is searched for.

You may specify PassengerRestartDir in the following places:

In each place, it may be specified at most once.

You can either set it to an absolute directory, or to a directory relative to the application root. Examples:

Touching restart.txt will cause Phusion Passenger to restart the application. So anybody who can touch restart.txt can effectively cause a Denial-of-Service attack by touching restart.txt over and over. If your web server or one of your web applications has the permission to touch restart.txt, and one of them has a security flaw which allows an attacker to touch restart.txt, then that will allow the attacker to cause a Denial-of-Service.

You can prevent this from happening by pointing PassengerRestartDir to a directory that’s readable by Apache, but only writable by administrators.

This feature is only available in Phusion Passenger Enterprise. It was introduced in version 3.0.0. Buy Phusion Passenger Enterprise here.

Enables or disables support for rolling restarts. Normally when you restart an application (by touching restart.txt), Phusion Passenger would shut down all application processes and spawn a new one. The spawning of a new application process could take a while, and any requests that come in during this time will be blocked until this first application process has spawned.

But when rolling restarts are enabled, Phusion Passenger Enterprise will:

This way, visitors will not experience any delays when you are restarting your application. This allows you to, for example, upgrade your application often without degrading user experience.

Rolling restarts have a few caveat however that you should be aware of:

This option may occur in the following places:

In each place, it may be specified at most once. The default value is off.

This feature is only available in Phusion Passenger Enterprise. It was introduced in version 3.0.0. Buy Phusion Passenger Enterprise here.

Enables or disables resistance against deployment errors.

Suppose you’ve upgraded your application and you’ve issues a command to restart it (by touching restart.txt), but the application code contains an error that prevents Phusion Passenger from successfully spawning a process (e.g. a syntax error). Phusion Passenger would normally display an error message in response to this.

By enabling deployment error resistance, Phusion Passenger Enterprise would instead do this:

This way, visitors will suffer minimally from deployment errors. Phusion Passenger will attempt to restart the application again next time restart.txt is touched.

Enabling deployment error resistance only works if rolling restart is also enabled.

This option may occur in the following places:

In each place, it may be specified at most once. The default value is off.

These options only have effect on classic Ruby on Rails 1.x and 2.x applications. Ruby on Rails >= 3.x applications are considered Rack applications.

The following options have been deprecated, but are still supported for backwards compatibility reasons.

Process inspection tools such as ps and top are useful, but they rarely show the correct memory usage. The real memory usage is usually lower than what ps and top report.

There are many technical reasons why this is so, but an explanation is beyond the scope of this Users Guide. We kindly refer the interested reader to operating systems literature about virtual memory and copy-on-write.

The tool passenger-memory-stats allows one to easily analyze Phusion Passenger’s and the web server’s real memory usage. For example:

The Private or private dirty RSS field shows the real memory usage of processes. Here, we see that all the Apache and Nginx worker processes only take less than 1 MB memory each. This is a lot less than the 50-80 MB-ish memory usage as shown in the VMSize column (which is what a lot of people think is the real memory usage, but is actually not).

One can inspect Phusion Passenger’s internal status with the tool passenger-status. This tool must typically be run as root. For example:

The general information section shows the following information:

The domains section shows, for each application directory, information about running application instances:

Since Phusion Passenger uses fair load balancing by default, the number of sessions for the application instances should be fairly close to each other. For example, this is fairly normal:

But if you see a "spike", i.e. an application instance has an unusually high number of sessions compared to the others, then there might be a problem:

The most likely reason why a spike occurs is because your application is frozen, i.e. it has stopped responding. See Debugging frozen applications for tips.

If one of your application instances is frozen (stopped responding), then you can figure out where it is frozen by killing it with SIGABRT. This will cause the application to raise an exception, with a backtrace.

The exception (with full backtrace information) is normally logged into the web server error log. But if your application or if its web framework has its own exception logging routines, then exceptions might be logged into the application’s log files instead. This is the case with Ruby on Rails. So if you kill a Ruby on Rails application with SIGABRT, please check the application’s production.log first (assuming that you’re running it in a production environment). If you don’t see a backtrace there, check the web server error log.

When a request is sent to the web server, Phusion Passenger will automatically forward the request to the most suitable application process, but sometimes it is desirable to be able to directly access the individual application processes. Use cases include, but are not limited to:

All individual application processes are accessible via HTTP, so you can use standard HTTP tools like curl. The exact addresses can be obtained with the command passenger-status --verbose. These sockets are all bound to 127.0.0.1, but the port number is dynamically assigned. As a security measure, the sockets are also protected with a process-specific random password, which you can see in the passenger-status --verbose output. This password must be sent through the “X-Passenger-Connect-Password” HTTP header.

Example:

Here we see that the web application rack.test has two processes. Process 24235 is accessible via http://127.0.0.1:58122, and process 24250 is accessible via http://127.0.0.1:57933.

To access 24235 we must send its password, nFfVOX1F8LjZ90HJh28Sd_htJOsgRsNne2QXKf8NIXw, through the X-Passenger-Connect-Password HTTP header, like this:

This feature is only available in Phusion Passenger Enterprise. It was introduced in version 3.0.0. Buy Phusion Passenger Enterprise here.

You can attach an IRB console to any application process and inspect its state by executing arbitrary Ruby code. Do this by invoking passenger-irb <PID> where <PID> is the PID of the application process you wish to inspect. Note that the IRB console is currently only available for Ruby apps, not for apps in any other languages.

Phusion Passenger supports automatic user switching: by default, it attempts to run applications as the "right" user, instead of running all applications as the same user.

To better understand the problem, let us consider the situation with PHP. There is a problem that plagues most PHP web hosts, namely the fact that all PHP applications are run in the same user context as the web server. So for example, Joe’s PHP application will be able to read Jane’s PHP application’s passwords. This is obviously undesirable on many servers.

Phusion Passenger’s user switching feature solves this problem. Applications are run as the owner of their "startup file". For Ruby apps, the startup file is config.ru (Rack and Rails >= 3) or config/environment.rb (Rails 1 and 2). For Python apps, the startup file is passenger_wsgi.py. So suppose that config.ru is owned by user joe, then Phusion Passenger will spawn the corresponding application as joe as well. The exact rules are a little bit more complicated, and they’re explained further down in this section.

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:

Phusion Passenger can be combined with Capistrano. The following Capistrano recipe demonstrates Phusion Passenger support. It assumes that you’re using Git as version control system.

Phusion Passenger has automatic support for Bundler. The support consists of loading your application under the environment defined by your Gemfile. In other words, Phusion Passenger loads your application as if bundle exec was used.

The Bundler support works as follows:

It’s possible that your application also calls Bundler.setup during loading, e.g. in config.ru or in config/boot.rb. This is the case with Rails 3, and is also the case if you modified your config/boot.rb according to the Bundler Rails 2.3 instructions. This leads to Bundler.setup being called twice, once before the application startup file is required and once during application startup. However this is harmless and doesn’t have any negative effects.

Phusion Passenger assumes that you’re using Bundler >= 0.9.5. If you don’t want Phusion Passenger to run its Bundler support code, e.g. because you need to use an older version of Bundler with an incompatible API or because you use a system other than Bundler, then you can override Phusion Passenger’s Bundler support code by creating an empty file config/setup_load_paths.rb. If this file exists then it will be required before loading the application startup file. In this file you can do whatever you need to setup Bundler or a similar system.

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:

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.

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.

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:

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.

Available since Phusion Passenger 4.0.0.

At this time, this feature is only available on Ruby.

The Out-of-Band Work feature allows you to run arbitrary long-running tasks outside normal request cycles. This works by letting current requests to the process finish, then telling the process to perform the out-of-band work, then resuming passing requests to the process after said work is finished.

A specific (and perhaps primary) use case of of Out-of-Band Work is Out-of-Band Garbage Collection. The garbage collector is run outside normal request cycles so that garbage collection runs inside normal request cycles can finish a lot faster. This can potentially save tens to hundreds of milliseconds of latency in requests.

Because Out-of-Band Work is implemented at the Phusion Passenger inter-process request routing level, and not by, say, spawning a thread inside the application process, Out-of-Band Work has the following useful properties:

Applications can use Out-of-Band Work as follows:

Note that even though you can request out-of-band work, there’s no guarantee that Phusion Passenger will send an oob_work event in a timely manner, if at all. It is also possible that Phusion Passenger sends an oob_work event without you ever having requested one. This latter could for example happen if the OOB work is administrator-initiated. Do not make any assumptions in your code.

Here’s an example which implements out-of-band garbage collection using the Out-of-Band framework. This example code doesn’t do anything when the code is not being run in Phusion Passenger, thanks to the if block.

For your convenience, Phusion Passenger provides a Rack middleware for out-of-band garbage collection. Add the following to your config.ru. Likewise, this example code doesn’t do anything when the code is not being run in Phusion Passenger, thanks to the if block.

It should be noted that, although the application uses the Phusion Passenger API, it is not necessary to add Phusion Passenger to the Gemfile.

References:

This feature is only available in Phusion Passenger Enterprise. It was introduced in version 4.0.6. Buy Phusion Passenger Enterprise here.

Flying Passenger allows one to decouple Phusion Passenger’s life time from the web server’s life time, so that the web server can be independently restarted from Phusion Passenger, and from any of the application processes served by Phusion Passenger.

Normally, Phusion Passenger starts together with the web server, and shuts down together with the web server. The advantages of this default behavior is that it makes Phusion Passenger easy to administer: one only has to deal with the web server process and can expect all relevant processes to be cleaned up after a web server shut down. However this also brings about a disadvantage: every time one restarts the web server (e.g. to make a minor configuration change), Phusion Passenger and all its application processes also get restarted.

This problem is solved by Flying Passenger, which is an advanced mode of operation in Phusion Passenger that allows the web server to be indepedently restarted from Phusion Passenger. When this mode is enabled:

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

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

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.

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.

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:

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

After you’ve read the deployment instructions you might wonder how Phusion Passenger knows that the DocumentRoot points to a web application that Phusion Passenger is able to serve, and how it knows what kind of web application it is (e.g. Rails or Rack).

Phusion Passenger checks whether the virtual host is a Rails application by checking whether the following file exists:

If you’re not a programmer and don’t understand the above pseudo-code snippet, it means that Phusion Passenger will:

So suppose that your document root is /webapps/foo/public. Phusion Passenger will check whether the file /webapps/foo/config/environment.rb exists.

Note that Phusion Passenger does not resolve any symlinks in the document root path by default since version 2.2.0 — 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, Phusion Passenger will check whether /webapps/example.com/config/environment.rb exists because it resolves all symlinks. Phusion Passenger 2.2.0 and later however will check for /home/www/config/environment.rb. This file of course doesn’t exist, and as a result Phusion 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 Phusion Passenger what the correct application root is through the PassengerAppRoot configuration directive.

Autodetection of Rack applications happens through the same mechanism, exception that Phusion Passenger will look for config.ru instead of config/environment.rb.

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:

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

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

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

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.

Phusion Passenger could create a new Ruby process, which will then load the Rails application along with the entire Rails framework. This process will then enter an request handling main loop.

This is the most straightforward way to spawn worker processes. If you’re familiar with the Mongrel application server, then this approach is exactly what mongrel_cluster performs: it creates N worker processes, each which loads a full copy of the Rails application and the Rails framework in memory. The Thin application server employs pretty much the same approach.

Note that Phusion Passenger’s version of direct spawning differs slightly from mongrel_cluster. Mongrel_cluster creates entirely new Ruby processes. In programmers jargon, mongrel_cluster creates new Ruby processes by forking the current process and exec()-ing a new Ruby interpreter. Phusion Passenger on the other hand creates processes that reuse the already loaded Ruby interpreter. In programmers jargon, Phusion Passenger calls fork(), but not exec().

While direct spawning works well, it’s not as efficient as it could be because each worker process has its own private copy of the Rails application as well as the Rails framework. This wastes memory as well as startup time.

Figure: Worker processes and direct spawning. Each worker process has its own private copy of the application code and Rails framework code.

It is possible to make the different worker processes share the memory occupied by application and Rails framework code, by utilizing so-called copy-on-write semantics of the virtual memory system on modern operating systems. As a side effect, the startup time is also reduced. This is technique is exploited by Phusion Passenger’s smart spawn method.

Because worker processes are created by forking from an ApplicationSpawner server, it will share all file descriptors that are opened by the ApplicationSpawner server. (This is part of the semantics of the Unix fork() system call. You might want to Google it if you’re not familiar with it.) A file descriptor is a handle which can be an opened file, an opened socket connection, a pipe, etc. If different worker processes write to such a file descriptor at the same time, then their write calls will be interleaved, which may potentially cause problems.

The problem commonly involves socket connections that are unintentionally being shared. You can fix it by closing and reestablishing the connection when Phusion Passenger is creating a new worker process. Phusion Passenger provides the API call PhusionPassenger.on_event(:starting_worker_process) to do so. So you could insert the following code in your environment.rb:

Note that Phusion Passenger automatically reestablishes the connection to the database upon creating a new worker process, which is why you normally do not encounter any database issues when using smart spawning mode.

Another part of the fork() system call’s semantics is the fact that threads disappear after a fork call. So if you’ve created any threads in environment.rb, then those threads will no longer be running in newly created worker process. You need to revive them when a new worker process is created. Use the :starting_worker_process event that Phusion Passenger provides, like this:

This gotcha is only applicable to the smart spawn method, not the smart-lv2 spawn method.

If your application expects the Rails framework to be not loaded during the beginning of environment.rb, then it can cause problems when an ApplicationSpawner is created from a FrameworkSpawner, which already has the Rails framework loaded. The most common case is when applications try to patch Rails by dropping a modified file that has the same name as Rails’s own file, in a path that comes earlier in the Ruby search path.

For example, suppose that we have an application which has a patched version of active_record/base.rb located in RAILS_ROOT/lib/patches, and RAILS_ROOT/lib/patches comes first in the Ruby load path. When conservative spawning is used, the patched version of base.rb is properly loaded. When smart (not smart-lv2) spawning is used, the original base.rb is used because it was already loaded, so a subsequent require "active_record/base" has no effect.

You can see all environment variables in your shell by running the following command:

You can set an evironment variable with the syntax export <NAME>=<VALUE>. For example, to set the APXS2 variable to the value /usr/sbin/apxs2:

Any process that you run from your shell from that point on will have said environment variable:

You can reference an environment variable in your shell by typing the $ sign followed by the environment variable’s name. For example, to see the value of the PATH variable:

You can also use this trick to extend the value of an environment variable:

The PATH environment variable dictates where the system looks for command. It is a colon-separated list of directories. If you get a "command not found" error while you know that the command is installed, then setting PATH will help. For example suppose that the command frobnicator is in /opt/local/bin:

We verify that /opt/local/bin is not in PATH:

We can run frobnicator through it’s full path…

…or we can add /opt/local/bin to PATH.

When you exit your shell, the evironment variable changes are lost. There is no standard method to set environment variables system-wide, so you have to set them in different configuration files for different services.

The sudo command resets all environment variables before running the specified command, for security reasons. So if you set environment variables before running sudo passenger-install-xxx-module, sudo passenger-status or any other commands, then the environment variables are not correctly passed to the command. You can solve this by running sudo with -E (preserve environment variables):

Alternatively, you can obtain a root prompt with sudo first, and then set the environment variables, before running any further commands: