Phusion Passenger Standalone users guide

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

Supported operating systems:

"Other Unix" is supported on a "best-effort" basis. We do not regularly check whether Phusion Passenger still works on other Unices, but if users report issues then we’ll try to address them.

Supported architectures:

Supported languages and frameworks:

If you run into any issues, please report a bug or join our discussion forum.

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

Because Phusion Passenger is designed to run in a wide variety of operating systems and configurations, there are multiple ways to install it. Most users  — especially first-time users — will prefer OS-specific installation instructions. These are not only the easiest, but also allow Phusion Passenger to integrate into the operating system in the best way possible. Other users should consult the generic installation instructions.

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.

We provide an official Phusion Passenger APT repository. This APT repository contains Phusion Passenger packages for multiple versions of Debian and Ubuntu. These packages are automatically built by our build server after we push out a source release, and thus are always up to date with the official source releases.

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.

Packages are available for the x86 and x86_64 architectures. Our policy is to support all Ubuntu LTS releases that are still supported by Canonical, plus the latest Ubuntu release, plus all Debian releases that are still supported by Debian.

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.

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.

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 Ruby.

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.

Once you have downloaded the tarball, pick a location to extract it to. You can pick any location. A good location is /opt/passenger. 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.

Edit /etc/bashrc (or /etc/bash.bashrc on some systems) and append the following to the end of the file:

Finally, restart all your shell sessions in order to activate this change. The installation is now complete.

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.

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

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:

If you used the tarball installation method and you added Phusion Passenger’s bin subdirectory to PATH, then you must update your PATH with the new location. Open /etc/bashrc (or /etc/bash.bashrc on some systems) and change:

to:

Finally, restart all your shell sessions to activate the PATH change.

Most configuration is done by customizing the arguments passed to the passenger command. The most important ones are:

See --help for all available options.

Introduced in version 4.0.24.

It is possible to store some options in a configuration file passenger-standalone.json in the application directory. Configuration in this file overrides command line options. The configuration file format is JSON.

In case Passenger Standalone is in mass deployment mode, such a configuration file allows customizing options on a per-application basis.

The following configuration options are supported:

Here is an example configuration file:

Introduced in version 4.0.39.

Phusion Passenger Standalone is built on the same technology that powers Phusion Passenger for Nginx, so any configuration option supported by Phusion Passenger for Nginx can be applied to Standalone as well. You can do this by editing the Standalone configuration template directly.

First, create a copy of the default Phusion Passenger Nginx configuration template file:

Then open nginx.conf.erb and modify it as you see fit. The file is a normal Nginx configuration file, in the ERB template format.

Every time you start Standalone, you must pass the --nginx-config-template parameter, which tells Standalone to use your specific Nginx configuration template file. For example:

Alternatively, if you don’t want to pass this parameter every time, you can also set the nginx_config_template option in passenger-standalone.json.

The easiest way to have Passenger Standalone started during system boot is add it to the file /etc/rc.local. This script is called during system boot.

Here’s an example of what you may want to add to /etc/rc.local. If there is an exit command in rc.local, make sure you add these before the exit command.

To stop Passenger Standalone, run:

If you have multiple applications on your server then it is desirable to have all of them listen on the same port (e.g. port 80), with the HTTP request’s host name determining which Passenger Standalone instance should handle the request. There are three ways to achieve this.

The rest of this subsection describes method 2.

Putting Passenger Standalone behind a reverse proxy requires three steps. First, you must start all Passenger Standalone instances that you want. Each one must be listening on a different port, because two applications can’t listen on the same port. Suppose that you have two applications, /webapps/foo and /webapps/bar. Here’s how you may start them:

Notice the fact that we pass --address 127.0.0.1, which tells Passenger Standalone to only listen for requests that originate from the local machine. This is because the reverse proxy/load balancer, not Passenger Standalone, is supposed to be responsible for receiving external HTTP requests. The reverse proxy/load balancer will be running on the same machine only, so limiting Passenger Standalone in this manner improves security.

The next step is to install a reverse proxy/load balancer, and to configure it to do the following:

You can use any reverse proxy/load balancer you want, but we’re going to show an example using Nginx because it’s a pretty popular choice. Install Nginx as follows:

Open the Nginx configuration file:

Add virtual host entries for your applications foo and bar. While making the virtual host entries, you must determine what host names foo and bar should respond to. Let’s say that foo should respond to www.foo.com and bar should respond to www.bar.com. Then the following entries will tell Nginx to listen on port 80, and to handle requests for the domains www.foo.com and www.bar.com differently.

Once you’re done editing the Nginx configuration file, restart Nginx:

Nginx should now be listening on port 80, and should forward requests to foo and bar respectively. Let’s test it out by accessing http://www.foo.com and http://www.bar.com. But first, we need to ensure that any requests to www.foo.com and www.bar.com, that originate from the local machine, actually end up at the local host, and not at the IP address specified in the DNS records. To do this, edit /etc/hosts and add:

Now visit http://www.foo.com and http://www.bar.com, and verify that it works.

Once you restart the server, the reverse proxy/load balancer will no longer be able to serve www.foo.com or www.bar.com because the Passenger Standalone instances that host them are no longer running. You must therefore configure the system to start Passenger Standalone at system boot. Please refer to Starting Passenger Standalone at system boot for more information.

For example, you can put this in /etc/rc.local to make the system start foo and bar at system boot:

Edit /etc/hosts and remove the entry that you added in step 3.

This is described in Sharing the same port between multiple Passenger Standalone instances.

One of the first things you should do upon encountering a problem, is to check Phusion Passenger Standalone log file. This is typically located in log/passenger.[PORT NUMBER].log. Most problems are logged to this log file.

If neither the logs nor this troubleshooting guide can help you, then please check out our support resources.

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:

Note that for security reasons, sudo always resets the PATH environment variable, even if you pass -E! You can get around this problem by obtaining a root prompt first, and then set the environment variables: