Phusion Passenger Standalone users guide

# Phusion Passenger Standalone users guide

Phusion Passenger is a web server and application server, designed to be fast, robust and lightweight. It runs your web apps with the least amount of hassle by taking care of almost all administrative heavy lifting for you. Advanced administration tools allow you to gain deep insight into your web applications' operations and to keep your servers healthy. Phusion Passenger is polyglot by design, and currently supports Ruby (Rack), Python (WSGI) and Node.js.

In the Standalone mode, Phusion Passenger operates as a fully-featured, secure standalone HTTP server. You do not need to have an existing web server like Apache or Nginx. This mode is ideal…

- …if you are not familiar with Apache or Nginx

- …when you want to quickly start up a server without editing configuration files (e.g. during development)

- …or when you want to decouple the web server from the application server, by setting up reverse proxies.

## 1. Support information

### 1.1. Supported operating systems and languages

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:

OS | Minimum version
--- | ---
Ubuntu | 10.04
Debian | 6
Red Hat, CentOS | 5
Amazon Linux | All versions supported
Mac OS X | 10.8 Mountain Lion
FreeBSD | 8
OpenBSD | 5.2
Other Unix | -

"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:

Architecture | Notes
--- | ---
x86 (32-bit) | -
x86_64 (64-bit) | -
Other | Supported on a "best-effort" basis.

Supported languages and frameworks:

Language/framework | Minimum version
--- | ---
Ruby (MRI) | 1.8.5
JRuby | 1.7.0
Rubinius | 2.2.0
Ruby on Rails | 2.3
Python | 2.6
Node.js/io.js | 0.10
Meteor | 0.6

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

### 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

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.

### 2.2. Installing or upgrading on Mac OS X with Homebrew

Open source

  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.

  1. Update the Homebrew recipes:

         brew update

  2. Run one of the following, and follow the instructions:

         brew install passenger
         -OR-
         brew upgrade passenger

Enterprise

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

### 2.3. Installing or upgrading on Debian or Ubuntu

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.

#### 2.3.1. Adding our APT repository

1. Install our PGP key. Packages are signed by "Phusion Automated Software Signing (auto-software-signing@phusion.nl)", fingerprint 1637 8A33 A6EF 1676 2922 526E 561F 9B9C AC40 B2F7.

       sudo apt-key adv --keyserver keyserver.ubuntu.com --recv-keys 561F9B9CAC40B2F7

2. Add HTTPS support for APT. Our APT repository is stored on an HTTPS server.

       sudo apt-get install apt-transport-https ca-certificates

3. Create a file /etc/apt/sources.list.d/passenger.list and insert one of the following lines, depending on your distribution.

   Open source

         ##### !!!! Only add ONE of these lines, not all of them !!!! #####
         # Ubuntu 15.04
         deb https://oss-binaries.phusionpassenger.com/apt/passenger vivid main
         # Ubuntu 14.04
         deb https://oss-binaries.phusionpassenger.com/apt/passenger trusty main
         # Ubuntu 12.04
         deb https://oss-binaries.phusionpassenger.com/apt/passenger precise main
         # Debian 8
         deb https://oss-binaries.phusionpassenger.com/apt/passenger jessie main
         # Debian 7
         deb https://oss-binaries.phusionpassenger.com/apt/passenger wheezy main
         # Debian 6
         deb https://oss-binaries.phusionpassenger.com/apt/passenger squeeze main

   Enterprise

         ##### !!!! Only add ONE of these lines, not all of them !!!! #####
         # Ubuntu 15.04
         deb https://download:YOUR_DOWNLOAD_TOKEN@www.phusionpassenger.com/enterprise_apt vivid main
         # Ubuntu 14.04
         deb https://download:YOUR_DOWNLOAD_TOKEN@www.phusionpassenger.com/enterprise_apt trusty main
         # Ubuntu 12.04
         deb https://download:YOUR_DOWNLOAD_TOKEN@www.phusionpassenger.com/enterprise_apt precise main
         # Debian 8
         deb https://download:YOUR_DOWNLOAD_TOKEN@www.phusionpassenger.com/enterprise_apt jessie main
         # Debian 7
         deb https://download:YOUR_DOWNLOAD_TOKEN@www.phusionpassenger.com/enterprise_apt wheezy main
         # Debian 6
         deb https://download:YOUR_DOWNLOAD_TOKEN@www.phusionpassenger.com/enterprise_apt squeeze main

     You can find the correct value for YOUR_DOWNLOAD_TOKEN in the Customer Area.

4. Secure passenger.list and update your APT cache:

       sudo chown root: /etc/apt/sources.list.d/passenger.list
       sudo chmod 600 /etc/apt/sources.list.d/passenger.list
       sudo apt-get update

5. (Optional) If using unattended-upgrades, add our APT repository to the list of Allowed-Origins for upgrades, /etc/apt/apt.conf.d/50unattended-upgrades:

       // Automatically upgrade packages from these (origin:archive) pairs
       Unattended-Upgrade::Allowed-Origins {
         // To check "Origin:" and "Suite:", you could use e.g.:
         // grep "Origin\|Suite" /var/lib/apt/lists/oss-binaries.phusionpassenger.com*
         "Phusion:stable";
       };

#### 2.3.2. Installing packages

Open source

  1. Add our APT repository.

  2. Install the package:

         sudo apt-get install passenger

Enterprise

  1. Download your license key from the Customer Area and save it as /etc/passenger-enterprise-license.

  2. Add our APT repository.

  3. Install the packages:

         sudo apt-get install passenger-enterprise

You can now proceed with a chapter for Deploying your (specific type of) application.

### 2.4. Installing or upgrading on Red Hat or CentOS

We provide an official Phusion Passenger YUM repository with packages for Red Hat Enterprise Linux and CentOS. 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. These packages also come with SELinux policy modules so that Passenger works nicely with SELinux.

Packages are available for the x86 and x86_64 architectures. Our policy is to support all Red Hat and CentOS releases that still receive full updates by their vendors. The earliest Red Hat and CentOS version we support is version 5.

#### 2.4.1. Adding our YUM repository

1. Install EPEL and a few other prerequisites.

       sudo yum install epel-release pygpgme curl

2. Download the Passenger YUM repository definition.

   Open source

         sudo curl --fail -sSLo /etc/yum.repos.d/passenger.repo https://oss-binaries.phusionpassenger.com/yum/definitions/el-passenger.repo

   Enterprise

         unset HISTFILE
         sudo curl --fail -sSL -u download:YOUR_DOWNLOAD_TOKEN -o /etc/yum.repos.d/passenger.repo https://www.phusionpassenger.com/enterprise_yum/el-passenger-enterprise.repo

     The unset HISTFILE command ensures that your download token isn’t saved to the Bash history file.

     You can find the correct value for YOUR_DOWNLOAD_TOKEN in the Customer Area.

3. Secure passenger.repo:

       sudo chown root: /etc/yum.repos.d/passenger.repo
       sudo chmod 600 /etc/yum.repos.d/passenger.repo

#### 2.4.2. Installing packages

| Notes about SELinux on Red Hat 6 and CentOS 6 If you are on Red Hat 6 or CentOS 6, and you are also using SELinux in enforcing mode, then Passenger requires kernel >= 2.6.39. If you want to install Passenger on Red Hat 6 or CentOS 6, without upgrading your kernel, then you must disable SELinux completely. Edit /etc/selinux/config, set SELINUX=disabled and reboot. Note that merely setting SELinux to permissive mode is not enough. This issue does not apply to Red Hat >= 7 and CentOS >= 7, because these OS versions supply recent enough kernel versions.

You can install the Passenger packages as follows.

Open source

  1. Add our YUM repository.

  2. Install the package:

         sudo yum install passenger

Enterprise

  1. Download your license key from the Customer Area and save it as /etc/passenger-enterprise-license.

  2. Add our YUM repository.

  3. Install the packages:

         sudo yum install passenger-enterprise

You can now proceed with a chapter for Deploying your (specific type of) application.

### 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

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.

#### Step 1: figuring out whether your Ruby is installed in the home directory or system-wide

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:

    which ruby

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:

- Are you using RVM? Run rvmsudo -H bash

- Are you not using RVM, or do you not know what RVM is? Run sudo -H -s

- Is sudo not installed on your system? Run su -c bash

You must maintain this root prompt throughout this installation guide.

#### Step 2: install the gem

Open Source

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

      gem install passenger

  Previous versions and beta versions

  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:

      gem install passenger --pre

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

      gem install passenger --version 3.0.0

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

      gem install passenger --version 3.9.1.beta --pre

Enterprise

  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:

      gem source --add https://download:YOUR_DOWNLOAD_TOKEN@www.phusionpassenger.com/enterprise_gems/

  Substitute YOUR_DOWNLOAD_TOKEN with the one you find in the Customer Area. 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 Passenger Enterprise:

      gem install passenger-enterprise-server

  Previous versions and beta versions

  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:

      gem install passenger-enterprise-server --pre

  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:

      gem install passenger-enterprise-server --version 3.0.0

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

      gem install passenger-enterprise-server --version 3.9.1.beta --pre

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

#### Step 1: installing Ruby

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.

Debian, Ubuntu | sudo apt-get update sudo apt-get install ruby rake
Red Hat, CentOS, ScientificLinux, Amazon Linux | Enable EPEL, then run as root: yum install ruby rubygem-rake
Mac OS X | No action needed. Ruby is installed by default.
Other operating systems | Install Ruby from the Ruby website.

#### Step 2: download and extract the tarball

Open Source

  Download the open source Phusion Passenger tarball from the Phusion Passenger website.

  Older versions can be found in the release archive.

Enterprise

  Phusion Passenger Enterprise customers can 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. Create this directory and extract the tarball as follows:

    mkdir /opt/passenger
    cd /opt/passenger
    tar xzvf /location-to/passenger-x.x.x.tar.gz
    cd /opt/passenger/passenger-x.x.x

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

#### Step 3: adding the Phusion Passenger tools to PATH

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

    export PATH=/opt/passenger/passenger-x.x.x/bin:$PATH

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

### 2.8. Upgrading from open source to Enterprise

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:

1. Uninstall the open source Phusion Passenger.

2. Install the Enterprise version by following one of the installation guides in this section (e.g. RubyGems generic installation or tarball generic installation).

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.

### 2.9. Cryptographic verification of installation files

#### 2.9.1. Synopsis

We digitally sign various files with our GPG key so that you can check whether they’re legit, i.e. whether they really came from Phusion and haven’t been tampered with by a third party. We apply signing since the open source version 4.0.0 RC 4, or the Enterprise version 4.0.0 RC 1.

#### 2.9.2. Importing the Phusion Software Signing key

Phusion’s GPG key for signing software is as follows:

    Phusion Software Signing (software-signing@phusion.nl)
    Short key ID: 0x0A212A8C
    Long key ID: 0x2AC745A50A212A8C
    Fingerprint: D5F0 8514 2693 9232 F437  AB72 2AC7 45A5 0A21 2A8C

This key is stored at the Phusion website and at the key servers sks-keyservers.net and keyserver.ubuntu.com. You can import it to your keyring with one of these command:

    gpg --keyserver pool.sks-keyservers.net --search-keys 0x2AC745A50A212A8C
    # -OR-
    gpg --keyserver keyserver.ubuntu.com --search-keys 0x2AC745A50A212A8C

The Phusion Software Signing key is only used for signing software. It’s never used for signing emails or for encrypting files, so please be suspicious if you encounter usage of this key outside the context of signing software, and alert us at support@phusion.nl. Include "notspam" in the message to bypass our spam filter.

The email address software-signing@phusion.nl redirects to info@phusion.nl so it’s safe to send email there.

#### 2.9.3. Verifying the Phusion Software Signing key

The Phusion Software Signing key is also signed by the Phusion founders. Their keys are as follows:

    Hongli Lai (hongli@phusion.nl)
    Short key ID: 8C59158F
    Long key ID: CD70085E8C59158F
    Fingerprint: 218A 7255 83D0 2ECE F3A9 C2A7 CD70 085E 8C59 158F

    Ninh Bui (ninh@phusion.nl)
    Short key ID: 69481265
    Long key ID: AE405F7869481265
    Fingerprint: A77C 9CEF 766D 0E7D A95B 8778 AE40 5F78 6948 1265

Both keys are stored at both sks-servers.net and keyserver.ubuntu.com. Import them with:

    gpg --keyserver pool.sks-servers.net --search-keys 0xCD70085E8C59158F
    gpg --keyserver pool.sks-servers.net --search-keys 0xAE405F7869481265
    # -OR-
    gpg --keyserver keyserver.ubuntu.com --search-keys 0xCD70085E8C59158F
    gpg --keyserver keyserver.ubuntu.com --search-keys 0xAE405F7869481265

#### 2.9.4. Verifying the gem and tarball

You can find the open source version’s gem and tarball GPG signatures at https://www.phusionpassenger.com/file_releases. The Enterprise version’s GPG signatures can be found in the Customer Area. All signatures have the .asc extension. Once you have imported our key, you can verify the validity of a file against its signature as follows:

    $ gpg --verify passenger-x.x.x.tar.gz.asc passenger-x.x.x.tar.gz
    gpg: Signature made Mon Mar 11 09:45:46 2013 CET using RSA key ID 0A212A8C
    gpg: Good signature from "Phusion Software Signing <software-signing@phusion.nl>"

#### 2.9.5. Verifying Git signatures

Tags in the Git repository for the open source version are also tagged. You can verify a Git tag as follows:

    $ git tag --verify release-x.x.x
    object d886f34b5705e4314feccaf0d77b9a38416e15e0
    type commit
    tag release-4.0.0.rc5
    tagger Hongli Lai (Phusion) <hongli@phusion.nl> 1362993117 +0100

    This is a tag message.
    gpg: Signature made Mon Mar 11 10:12:02 2013 CET using RSA key ID 0A212A8C
    gpg: Good signature from "Phusion Software Signing <software-signing@phusion.nl>"

#### 2.9.6. Verifying Debian packages

Our APT repository is signed by Phusion Automated Software Signing (auto-software-signing@phusion.nl). Packages are automatically checked upon installation.

#### 2.9.7. Verifying RPM packages

Our YUM repository is signed by PackageCloud (ops@packagecloud.io). PackageCloud is the RPM package hosting service that we use. You can find their key here. Packages are automatically checked upon installation.

#### 2.9.8. Revocation

In the event our key is compromised, we will revoke the key and upload the revocation information to sks-servers.net and keyserver.ubuntu.com. However your system will not know about the revocation until you update the keys from the keyservers. You should update your keys regularly (e.g. once a week) by invoking:

    gpg --refresh-keys --keyserver pool.sks-servers.net
    # -OR-
    gpg --refresh-keys --keyserver keyserver.ubuntu.com

If you installed Phusion Passenger through our APT repository, then you should update APT’s keyring from time to time as well:

    sudo apt-key adv --refresh-keys --keyserver keyserver.ubuntu.com

### 2.10. Customizing the compilation process

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

#### 2.10.1. Setting the compiler

You can force the Phusion Passenger build system to use a specific C or C++ compiler by setting the CC and CXX environment variables. These may be set to any arbitrary shell commands.

For example, contributors who want to hack on Phusion Passenger may want to use Clang for faster compilation and ccache for faster recompilation, and may want to enable more error-catching compilation flags:

    export CC='ccache clang -fcolor-diagnostics -Qunused-arguments -fcatch-undefined-behavior -ftrapv'
    export CXX='ccache clang++ -fcolor-diagnostics -Qunused-arguments -fcatch-undefined-behavior -ftrapv'

| If you run the installer with sudo then environment variables may not be passed properly. Learn more at Environment variables and sudo.

#### 2.10.2. Adding additional compiler or linker flags

On some systems, C/C++ libraries and headers that Phusion Passenger requires may be located in a non-standard directory. You can force the Phusion Passenger build system to look in those locations by injecting compiler and linker flags using the following environment variables:

EXTRA_PRE_CFLAGS

  These flags are injected into all C compiler invocations that involve compiling C source files. This also covers compiler invocations that compile and link. The flags are injected at the beginning of the command string, even before EXTRA_PRE_LDFLAGS.

EXTRA_CFLAGS

  Similar to EXTRA_PRE_CFLAGS, but injected at the end of the command string, before EXTRA_LDFLAGS.

EXTRA_PRE_CXXFLAGS

  Similar to EXTRA_PRE_CFLAGS, but for C++ compiler invocations.

EXTRA_CXXFLAGS

  Similar to EXTRA_CFLAGS, but for C++ compiler invocations.

EXTRA_PRE_LDFLAGS

  These flags are injected into all C/C++ compiler invocations that involve linking. This includes compiler invocations that compile and link. The flags are injected at the beginning of the command string, but after EXTRA_PRE_CFLAGS/EXTRA_PRE_CXXFLAGS.

EXTRA_PRE_C_LDFLAGS

  These flags are injected into all C compiler invocations that involve linking, right after EXTRA_PRE_LDFLAGS.

EXTRA_PRE_CXX_LDFLAGS

  Similar to EXTRA_PRE_CXX_LDFLAGS, but for C++ compiler invocations.

EXTRA_LDFLAGS

  Similar to EXTRA_PRE_LDFLAGS, but injected at the very end of the command string, even after EXTRA_CFLAGS and EXTRA_CXXFLAGS.

EXTRA_C_LDFLAGS

  Similar to EXTRA_LDFLAGS, but only injected for C executable linking commands. Injected right after EXTRA_LDFLAGS.

EXTRA_CXX_LDFLAGS

  Similar to EXTRA_LDFLAGS, but only injected for C++ executable linking commands. Injected right after EXTRA_LDFLAGS.

PASSENGER_THREAD_LOCAL_STORAGE

  Setting this to 1 will enable the PASSENGER_THREAD_LOCAL_STORAGE macro, which forcefully disables the use of thread-local storage inside the Phusion Passenger codebase. Setting this environment variable is useful on systems that have broken support for thread-local storage, despite passing our build system’s check for proper thread-local storage support. At the time of writing, one user has reported that Ubuntu 12.04 32-bit has broken thread-local storage report although neither the reporter nor us were able to reproduce the problem on any other systems running Ubuntu 12.04 32-bit. Note that this flag has no effect on non-Phusion Passenger code.

| If you run the installer with sudo then environment variables may not be passed properly. Learn more at Environment variables and sudo.

#### 2.10.3. Forcing location of command line tools and dependencies

The Phusion Passenger build system attempts to autodetect many things by locating relevant helper tools. For example, to find out which compiler flags it should use for compiling Apache modules, it locates the apxs2 command and queries it. To find out which compiler flags it should use for libcurl, it queries the curl-config command. These commands may not be in $PATH, or even when they are you may want to use a different one.

You can force the build to find certain command line tools at certain locations by using the following environment variables:

HTTPD

  The location of the httpd executable (the Apache server executable).

APXS2

  The location of the apxs2 executable (the Apache module developer tool). Only used by passenger-install-apache2-module.

  This environment variable, together with HTTPD, are what you need to customize if you have multiple Apache installations on your system, or if your Apache is located in a non-standard location which Phusion Passenger cannot detect. By setting APXS2 and HTTP to the right paths, you can force Phusion Passenger to be compiled against that specific Apache installation.

  For example, if your Apache installation is located in /opt/lamp/apache2, then you can run the installer as follows:

      $ sudo bash
      # export HTTPD=/opt/lampp/apache2/bin/apache
      # export APXS2=/opt/lampp/apache2/bin/apxs
      # passenger-install-apache2-module

APR_CONFIG

  The location of the apr-config executable (the Apache Portable Runtime developer tool).

APU_CONFIG

  The location of the apu-config executable (the Apache Portable Runtime Utility developer tool).

MAKE

  The location of a make tool. It does not matter which implementation of make this is.

GMAKE

  The location of the GNU-compatible make tool.

| If you do not know what environment variables are, or how to use them, then please read Environment variables and sudo.

| If you run the installer with sudo then environment variables may not be passed properly. Learn more at Environment variables and sudo.

### 2.11. Uninstalling

- If you installed Phusion Passenger through Homebrew, then run brew uninstall passenger.

- If you installed Phusion Passenger via a Ruby gem, then run gem uninstall passenger (or, if you’re a Phusion Passenger Enterprise user, gem uninstall passenger-enterprise-server). You might have to run this as root.

- If you installed Phusion Passenger via a source tarball, then remove the directory in which you placed the extracted Phusion Passenger files. This directory is the same as the one pointed to the by PassengerRoot/passenger_root configuration directive.

- If you installed Phusion Passenger through APT or YUM, then use them to uninstall Phusion Passenger.

### 2.12. Moving to a different directory

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:

    mv /opt/passenger/passenger-4.0.0 /usr/local/passenger-4.0.0

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:

    export PATH=/opt/passenger/passenger-4.0.0/bin:$PATH

to:

    export PATH=/usr/local/passenger-4.0.0/bin:$PATH

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

## 3. Usage

Go to your application’s root directory, and run:

    passenger start

## 4. Configuration

### 4.1. Command line options

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

--port NUMBER

  The port number that Phusion Passenger Standalone should listen on. If not given, port 3000 is assumed.

--environment NAME

  Customizes the value of the RAILS_ENV, RACK_ENV, WSGI_ENV, NODE_ENV and PASSENGER_APP_ENV environment variables. Some web frameworks, for example Rails and Connect.js, adjust their behavior according to the environment. The default value is development.

--max-pool-size NUMBER

  The maximum number of application processes to run. The maximum number that you can run depends on the amount of memory your server has. The article Tuning Phusion Passenger’s concurrency settings explains how you can infer a good number for this option.

--min-instances NUMBER

  If you don’t want the number of application processes to scale dynamically, then use this option to set it to a value equal to --max-pool-size.

--spawn-method NAME

  When set to "smart" (the default), Phusion Passenger preloads your app and utilizes copy-on-write in order to save memory. You can disable this by setting this option to "direct". Preloading is only supported for Ruby apps. For apps written in other languages, it is as if "direct" is always used.

--friendly-error-pages

  Phusion Passenger can display a friendly error page whenever your application fails to start. The friendly error page presents the startup error message, some suggestions for solving the problem, a backtrace, and a dump of the environment variables. This feature is very useful during application development and useful for less experienced system administrators, but the page might reveal potentially sensitive information, depending on the application. For this reason, friendly error pages are turned off by default when --environment is set to staging or production, but enabled by default otherwise.

  You can use --friendly-error-pages and --no-friendly-error-pages to explicitly enable or disable this feature, respectively.

--sticky-sessions

  Enables sticky sessions. Required for SockJS, Socket.io, faye-websocket and Meteor JS applications.

--sticky-sessions-cookie-name NAME

  Allows customizing the sticky session cookie name.

--ssl

  Enables SSL support. If this is set, you must also set --ssl-certificate and --ssl-certificate-key to the SSL certificate and key files, respectively.

--ssl-port

  If --ssl is given, and you set this option, then Phusion Passenger Standalone will listen for HTTP on the regular --port number, as well as listen for HTTPS on the port you specified with this option. For example:

      # Listen for HTTP on port 3000, HTTPS on port 3001.
      passenger start --ssl --ssl-certificate ... --ssl-certificate-key ... --ssl-port 3001

--nginx-config-template

  Specifies the Nginx configuration template file to use. See Advanced configuration.

See --help for all available options.

### 4.2. Configuration file

Introduced in version 4.0.24.

It is possible to store some options in a configuration file Passengerfile.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:

port

  Equivalent to the --port command line option.

environment

  Equivalent to the --environment command line option.

max_pool_size

  Equivalent to the --max-pool-size command line option. But when in mass deployment mode, this option in the configuration file has no effect; the command line option should be used to customize this.

min_instances

  Equivalent to the --min-instances command line option.

spawn_method

  Equivalent to the --spawn-method command line option.

sticky_sessions

  Equivalent to the --sticky-sessions command line option.

sticky_sessions_cookie_name

  Equivalent to the --sticky-sessions-cookie-name command line option.

ssl

  Equivalent to the --ssl command line option. When given, you must also set ssl_certificate and ssl_certificate_key in the configuration file.

ssl_port

  Equivalent to the --ssl-port command line option.

  When in mass deployment mode, you will probably want to set a different port too. If you don’t, and you end up in a situation in which a port is used for both HTTP and HTTPS traffic, then the builtin Nginx core will abort with an error.

server_names (Enterprise only)

  Only relevant in mass deployment mode. This option specifies which server names (host names) should be routed to this application. This option must be an array of names, e.g. "server_names": ["foo.com", "bar.com"]. By default, the name of the application directory is used as the server name. For example, for an application located in /webapps/foobar.com, "foobar.com" is used as the server name.

envvars (since 5.0.0 RC 1)

  Environment variables to pass to the application. This option must be a key-value map, e.g. "envvars": { "ADMIN_EMAIL": "root@phusion.nl", "SECRET_KEY": "12345" }.

nginx_config_template

  Equivalent to the --nginx-config-template command line option.

Here is an example configuration file:

    {
            "port": 8000,
            "environment": "production",
            "ssl": true,
            "ssl_certificate": "/path-to-cert.crt",
            "ssl_certificate_key": "/path-to-cert.key"
    }

### 4.3. Advanced configuration

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:

    cp $(passenger-config about resourcesdir)/templates/standalone/config.erb nginx.conf.erb

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:

    passenger start --nginx-config-template nginx.conf.erb

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

| The original configuration template file may change from time to time, e.g. because new features are introduced into Phusion Passenger. If your configuration template file does not contain the required changes, then these new features may not work properly. In the worst case, Standalone might even malfunction. Therefore, every time you upgrade Phusion Passenger, you should check whether the original configuration template file has changed, and merge back any changes into your own file.

## 5. Using Passenger Standalone in production

### 5.1. Starting Passenger Standalone at system boot

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.

    # If you installed Phusion Passenger from tarball, add its `bin` directory to PATH.
    #export PATH=/path-to-passenger/bin:$PATH

    # Change working directory to your webapp.
    cd /path-to-your-webapp

    # Start Passenger Standalone in daemonized mode. Passenger will be started as
    # root when run from this file, so we also tell it to drop its privileges to a
    # normal user. Replace 'someusername' with the user you want to run your
    # application under.
    passenger start --daemonize --port 80 --user someusername

To stop Passenger Standalone, run:

    cd /path-to-your-webapp

    # If you use RVM, use 'rvmsudo' instead of 'sudo'
    sudo passenger stop

### 5.2. Sharing the same port between multiple Passenger Standalone instances

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.

1. The first way is to use the Mass deployment feature, which allows Passenger Standalone to directly host multiple applications at the same time. Please refer to that section to learn more.

2. The second way is to run multiple Passenger Standalone instances — one for each application — and to put all of them behind a reverse proxy or load balancer. The reverse proxy/load balancer can for example be Nginx, Apache or HAProxy. The reverse proxy/load balancer listens on port 80, determines which Passenger Standalone instance should handle the request, and forwards the request to that instance.

3. The third way is to use Phusion Passenger for Nginx or Phusion Passenger for Apache. These are two modes of Phusion Passenger that are distinct from the Standalone mode, which this document describes. In the Nginx and Apache modes, Phusion Passenger integrates directly into Nginx and Apache, and makes it very easy to host multiple applications directly on Nginx or Apache.

   Compared method 2 — putting Passenger Standalone behind a reverse proxy or load balancer — the Nginx or Apache modes are easier to use and require less configuration. On the other hand, the Nginx modes requires reinstalling or recompiling Nginx, while the Apache mode requires that the Phusion Passenger Apache module is installed.

The rest of this subsection describes method 2.

#### Step 1: starting all applications

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:

    # Start foo on port 4000
    cd /webapps/foo
    passenger start --daemonize --address 127.0.0.1 --port 4000

    # Start bar on port 4010
    cd /webapps/bar
    passenger start --daemonize --address 127.0.0.1 --port 4010

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.

#### Step 2: install and configure the reverse proxy/load balancer

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

- To listen on port 80.

- To forward requests to either foo or bar, depending on the request’s HTTP host name.

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:

Debian, Ubuntu | sudo apt-get update sudo apt-get install nginx-extras
Red Hat, CentOS, ScientificLinux, Amazon Linux | Enable EPEL, then run as root: yum install nginx
Mac OS X (Homebrew) | brew install nginx
Other operating systems | Install Nginx from the Nginx website.

Open the Nginx configuration file:

Debian, Ubuntu | /etc/nginx/nginx.conf
Red Hat, CentOS, ScientificLinux, Amazon Linux | /etc/nginx/nginx.conf
Mac OS X (Homebrew) | /usr/local/etc/nginx/nginx.conf
Other operating systems | It depends on how you installed Nginx, but it’s usually $PREFIX/conf/nginx.conf, where $PREFIX is the prefix you installed Nginx to.

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.

    http {
        ...

        # These are some "magic" Nginx configuration options that aid in making
        # WebSockets work properly with Passenger Standalone. Please learn more
        # at http://nginx.org/en/docs/http/websocket.html
        map $http_upgrade $connection_upgrade {
            default upgrade;
            ''      close;
        }

        server {
            listen 80;
            server_name www.foo.com;

            # Tells Nginx to serve static assets from this directory.
            root /webapps/foo/public;

            location / {
                # Tells Nginx to forward all requests for www.foo.com
                # to the Passenger Standalone instance listening on port 4000.
                proxy_pass http://127.0.0.1:4000;

                # These are "magic" Nginx configuration options that
                # should be present in order to make the reverse proxying
                # work properly. Also contains some options that make WebSockets
                # work properly with Passenger Standalone. Please learn more at
                # http://nginx.org/en/docs/http/ngx_http_proxy_module.html
                proxy_http_version 1.1;
                proxy_set_header Host $http_host;
                proxy_set_header Upgrade $http_upgrade;
                proxy_set_header Connection $connection_upgrade;
                proxy_buffering off;
            }
        }

        # We handle bar in a similar manner.
        server {
            listen 80;
            server_name www.bar.com;

            root /webapps/bar/public;

            location / {
                # bar is listening on port 4010 instead of 4000, we
                # change the URL here.
                proxy_pass http://127.0.0.1:4010;

                proxy_http_version 1.1;
                proxy_set_header Host $http_host;
                proxy_set_header Upgrade $http_upgrade;
                proxy_set_header Connection $connection_upgrade;
                proxy_buffering off;
            }
        }
    }

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

Debian, Ubuntu | sudo /etc/init.d/nginx restart
Red Hat, CentOS, ScientificLinux, Amazon Linux | sudo service nginx restart
Mac OS X (Homebrew) | 1. Run sudo kill $(cat /usr/local/var/run/nginx.pid) 2. You you installed the Nginx launchd plist that Homebrew provides (see brew info nginx to learn more), then you don’t have to do anything, and launchd will automatically restart Nginx. Otherwise, you have to manually start Nginx again: sudo /usr/local/bin/nginx.
Other operating systems | It depends on how you installed Nginx, but it’s usually as follows: 1. Lookup the PID of the Nginx master process using ps aux. 2. Run sudo kill <PID> 3. Start Nginx again: sudo $PREFIX/sbin/nginx, where $PREFIX is the prefix you installed Nginx to.

#### Step 3: testing

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:

    127.0.0.1  www.foo.com www.bar.com

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

#### Step 4: making all apps start at system boot

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:

    # If you installed Phusion Passenger from tarball, add its `bin` directory to PATH.
    #export PATH=/path-to-passenger/bin:$PATH

    cd /webapps/foo
    passenger start --daemonize --port 4000 --user someusername1

    cd /webapps/bar
    passenger start --daemonize --port 4010 --user someusername2

#### Step 5: wrapping up

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

### 5.3. Installing Passenger Standalone behind Nginx

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

## 6. Mass deployment

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

Mass deployment is a special mode in Phusion Passenger Standalone that allows you to deploy multiple web applications without having to create configuration entries for each one of them. Given a directory with multiple web applications, Passenger Standalone will automatically give each web application its own virtual host entry, and serve all of them from a single server. The virtual host’s server name is equal to the web application’s directory name. Whenever a new web application is added or removed, Passenger Standalone automatically reconfigures itself without administrator intervention. This makes the mass deployment mode especially useful when there are a large number of web applications.

For example, suppose we have a directory /webapps with three web applications: Ruby app, a Python app and a Node.js app.

    /webapps
      |
      +-- rubyapp.com
      |    |
      |    +-- config.ru
      |
      +-- pythonapp.com
      |    |
      |    +-- passenger_wsgi.py
      |
      +-- nodeapp.com
           |
           +-- app.js

You can activate Passenger Standalone in mass deployment mode by changing the working directory to /webapps and running passenger start:

    $ cd /webapps
    $ passenger start
    =============== Phusion Passenger Standalone web server started ===============
    PID file: /webapps/passenger.3000.pid
    Log file: /webapps/passenger.3000.log
    Environment: development

    Serving these applications on 0.0.0.0 port 3000:
     Host name                     Directory
    .-----------------------------------------------------------
     rubyapp.com                   /webapps/rubyapp.com
     pythonapp.com                 /webapps/pythonapp.com
     nodeapp.com                   /webapps/nodeapp.com
    .-----------------------------------------------------------

If you for example remove /webapps/rubyapp.com, Passenger Standalone will reconfigure itself without that web application. Or if you add a new web applications /webapps/newapp.org, Passenger Standalone will reconfigure itself with that web application.

Any options that you pass to the passenger command will affect all deployed web applications. It is also possible to change options on a per-application basis through the use of a Passengerfile.json file inside each application’s directory.

## 7. Troubleshooting

### 7.1. Generic troubleshooting tips

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.

### 7.2. Upon uploading a file, Phusion Passenger reports "client_body_temp/00000000xx failed (2: No such file or directory)"

Symptoms

  When performing an HTTP POST call, the request sometimes fails, with Phusion Passenger reporting an error along the lines of:

      /tmp/passenger-standalone.8583/client_body_temp/0000000022" failed (2: No such
      file or directory), client: 127.0.0.1, server: www.foo.com

Cause

  Phusion Passenger buffers HTTP POST bodies (file uploads) to a temporary directory, by default /tmp/passenger-standalone.xxx. This error means that Phusion Passenger that that directory has been removed, probably by some other program.

Solution

  Tell Phusion Passenger to use a different directory to store its temporary files passing the --temp-dir command line option. For example:

      mkdir $HOME/tmp
      cd /path-to-your-app
      passenger start --temp-dir=$HOME/tmp

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

Symptoms

  Phusion Passenger commands can be found as a normal user, but not when run through sudo:

      $ passenger-status
      ...some output, but no "command not found" error...
      $ passenger-install-apache2-module
      ...some output, but no "command not found" error...
      $ sudo passenger-status
      sudo: passenger-status: command not found
      $ sudo passenger-install-apache2-module
      sudo: passenger-install-apache2-module: command not found

Cause

  The operating system looks up commands using the PATH environment variable. However, sudo resets all environment variables to a default value, dictated by sudo. If Phusion Passenger was installed to a location that is not in the default sudo PATH value, then sudo will not be able to find the Phusion Passenger commands.

  In addition, if you installed Phusion Passenger using a Ruby interpreter that was installed through RVM, then you must use rvmsudo instead of sudo. As a rule, when you’re an RVM user, always use rvmsudo instead of sudo.

Solution

  Execute the command using its full path. You can use which as a normal user to lookup the full path:

      $ which passenger-status
      /somewhere/bin/passenger-status

  Next, run full path of the command using either sudo or rvmsudo:

      $ sudo /somewhere/bin/passenger-status

      # -OR, if you're using RVM:-

      $ rvmsudo /somewhere/bin/passenger-status

Recommended reading

  When using sudo, you will probably run into similar "command not found" issues in the future, with components other than Phusion Passenger. We strongly recommend you to learn about environment variables so that you know what to do in the future.

## 8. Under the hood

### 8.1. Phusion Passenger and its relationship with Ruby

#### 8.1.1. How Ruby is used

Phusion Passenger’s core is written in C++ for performance and memory efficiency. It supports web applications written in any language. Phusion Passenger requires Ruby, its usage of Ruby is minimal in order to maximize performance and to minimize memory usage.

- Phusion Passenger’s installer, build system and administration tools are written in Ruby.

- Certain internally used tools, such as the crash handler (which generates a backtrace in case Phusion Passenger crash) and the prespawn script (used to implement passenger_pre_start) are written in Ruby as well.

- Ruby web application support is implemented in Ruby.

- If you use Flying Passenger, then the Flying Passenger daemon is written in Ruby. The daemon is a small (less than 500 lines of code) and offloads most tasks to the C++ core.

- If you use Phusion Passenger Standalone, then the frontend (the passenger command) is written in Ruby. The frontend is small (less than 1500 lines of code) and offloads most tasks to the C++ core.

Other than the aforementioned aspects, Phusion Passenger does not use Ruby during normal operation. For example, if you run Python WSGI web applications on Phusion Passenger, then there will be (almost) no Ruby code running on the system.

#### 8.1.2. When the system has multiple Ruby interpreters

Phusion Passenger may be installed with any Ruby interpreter. Once installed, you can run Phusion Passenger’s Ruby parts under any Ruby interpreter you want, even if that Ruby interpreter was not the one you originally installed Phusion Passenger with.

The reason for this is that Phusion Passenger does not dynamically link to Ruby: Phusion Passenger uses Ruby entirely out-of-process. Thus you can switch to any Ruby interpreter you want during runtime, without recompiling Phusion Passenger, and without worrying about what Ruby you used to install Phusion Passenger.

Phusion Passenger is also capable of running Ruby web applications under any Ruby interpreter you want. So it is not important which Ruby you use to install Phusion Passenger: it will work regardless. Please refer to the documentation for the passenger_ruby directive to learn how run different web applications under different Ruby interpreters.

Caveat: RVM and RVM gemsets

There is however one caveat if you happen to be using RVM or RVM gemsets. When you gem install Phusion Passenger using RVM, then RVM will install Phusion Passenger into the currently active RVM Ruby and gemset. This means that Phusion Passenger commands - such as passenger, passenger-install-xxx-module and passenger-status - are available in that same RVM Ruby and gemset only. When you switch Ruby interpreter, or when you switch gemset, the Phusion Passenger commands will no longer be available, and you will get a command not found error. Here’s an example which demonstrates the problem.

"Command not found" problem demonstration

    ## Install Phusion Passenger (open source edition) using Ruby 1.9.3
    ## and the 'business' gemset
    $ rvm use 1.9.3
    Using /home/phusion/.rvm/gems/ruby-1.9.3-p429
    $ rvm gemset create business
    $ rvm gemset use business
    Using ruby-1.9.3-p429 with gemset business
    $ curl -O https://s3.amazonaws.com/phusion-passenger/releases/gem_bootstrap.sh
    $ eval "`sh gem_bootstrap.sh`"
    $ gem install passenger

    ## Verify that passenger works
    $ passenger --version
    Phusion Passenger version 4.0.14

    ## Switch to a different RVM gemset. You will get a `command not found`
    $ rvm gemset use default
    Using ruby-1.9.3-p429 with gemset default
    $ passenger --version
    bash: passenger: command not found

    ## Switch to a different Ruby interpreter. You will also get
    ## a `command not found`
    $ rvm use 2.0.0
    Using /home/phusion/.rvm/gems/ruby-2.0.0-p195
    $ passenger --version
    bash: passenger: command not found

    ## Switch back to the Ruby and gemset that you installed Phusion
    ## Passenger with, and verify that it works again
    $ rvm use 1.9.3
    Using /home/phusion/.rvm/gems/ruby-2.0.0-p195
    $ rvm gemset use business
    Using ruby-1.9.3-p429 with gemset business
    $ passenger --version
    Phusion Passenger version 4.0.14

Solutions

There are several ways to solve this problem:

1. Permanently add Phusion Passenger’s command directory to your PATH, so that your shell can always find them even when you switch RVM Ruby or gemset. If you don’t know what PATH means, please read About environment variables first.

   The drawback is that you have to redo this every time you upgrade Phusion Passenger, because the Phusion Passenger directory filename is dependent on the version number.

   First, identify the location of the Phusion Passenger command directory, like this:

       $ echo `passenger-config --root`/bin
       /home/phusion/.rvm/gems/ruby-1.9.3-p429/gems/passenger-4.0.15/bin

   Next, add the directory that you’ve found to your current shell’s PATH:

       $ export PATH=/home/phusion/.rvm/gems/ruby-1.9.3-p429/gems/passenger-4.0.15/bin:$PATH

   Finally, make the change permanent by appending the above command to your bash startup file:

       $ echo 'export PATH=/home/phusion/.rvm/gems/ruby-1.9.3-p429/gems/passenger-4.0.15/bin:$PATH' >> ~/.bashrc

2. Switch back to the RVM Ruby and gemset that you installed Phusion Passenger with, before running any Phusion Passenger command.

3. Prepend any Phusion Passenger command with rvm-exec RUBY_NAME@GEMSET_NAME ruby -S. If the relevant Phusion Passenger command also needs root privileges, then prepend rvmsudo before that. For example:

       rvm-exec 1.9.3@business ruby -S passenger --version
       rvmsudo rvm-exec 1.9.3@business ruby -S passenger-install-apache2-module

## 9. Appendix: About environment variables

Environment variables are named values that affect how the system works. For example they tell the system where to look for commands (the PATH variable) or where to look for libraries (LD_LIBRARY_PATH). Their names are often in all-uppercase. Sometimes people refer to an environment variable with a dollar sign $ in front, but that’s the same thing: when people say "the $PATH environment variable" they mean "the PATH environment variable". This is because the dollar sign $ is a shell syntax for refering to an environment variable, as you will learn later.

Environment variables are set on a per-process basis, but they are inherited by child processes. This means that if you set environment variables in process A, another already running process B will not see these new environment variables. But if A spawns a child process C, then C will have all environment variables that A had. If you once again change the environment variables in A, then C will not see the changes.

The per-process nature of environment variables some implications. When you set environment variables in your bashrc or other bash startup files…

- …only newly spawned bash shells see them.

- …the web server usually does not see them, because the web server tends to be started from init scripts, not from bash.

- …cron jobs do not see them, because cron jobs' environment variables are entirely dictated by their crontabs.

| Because this chapter is meant for beginners, it assumes that the reader uses the bash shell. This chapter does not describe instructions for zsh, csh or other shells. We assume that users of other shells are familiar with the Bourne shell syntax, and know how to apply the instructions in this chapter in their shells' native syntaxes.

### 9.1. Working with environment variables

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

    env

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:

    export APXS2=/usr/sbin/apxs2

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

    export APXS2=/usr/sbin/apxs2
    ruby -e 'p ENV["APXS2"]'
    # => "/usr/sbin/apxs2"

| The "export" keyword is important You must set the export keyword. If you omit the export keyword then the environment variable will not be visible to other processes:
    APXS2=/usr/sbin/apxs2
    ruby -e 'p ENV["APXS2"]'
    # => nil

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:

    echo $PATH

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

    export PATH=/usr/bin

    # Prepends '/opt/local/bin', so that it becomes /opt/local/bin:/usr/bin
    export PATH=/opt/local/bin:$PATH
    # Appends '/usr/local/bin', so that it becomes /opt/local/bin:/usr/bin:/usr/local/bin
    export PATH=$PATH:/usr/local/bin

### 9.2. The PATH 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:

    user@localhost bash$ frobnicator
    bash: frobnicator: command not found

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

    user@localhost bash$ echo $PATH
    /bin:/usr/bin:/usr/local/bin

We can run frobnicator through it’s full path…

    user@localhost bash$ /opt/local/bin/frobnicator
    # => success!

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

    user@localhost bash$ export PATH=$PATH:/opt/local/bin
    user@localhost bash$ frobnicator
    # => success!

#### 9.2.1. Adding Phusion Passenger’s administration tools to PATH

If you get a "command not found" error when invoking one of the Phusion Passenger administration tools (e.g. passenger-status or passenger-memory-stats then that means the tools are not in PATH, so you need to add them.

- If you installed Phusion Passenger with RubyGems, then the tools are in your RubyGems executable path. You can view the gem path using the command gem env:

      $ gem env
      RubyGems Environment:
        - RUBYGEMS VERSION: 1.8.15
        - RUBY VERSION: 1.8.7 (2011-12-28 patchlevel 357) [i686-darwin10.8.0]
        - INSTALLATION DIRECTORY: /opt/ruby-enterprise-1.8.7-2010.01/lib/ruby/gems/1.8
        - RUBY EXECUTABLE: /opt/ruby-enterprise-1.8.7-2010.01/bin/ruby
        - EXECUTABLE DIRECTORY: /opt/ruby-enterprise-1.8.7-2010.01/bin    <--------- !!
        - RUBYGEMS PLATFORMS:
          - ruby
          - x86-darwin-10
        - GEM PATHS:
           - /opt/ruby-enterprise-1.8.7-2010.01/lib/ruby/gems/1.8
           - /Users/hongli/.gem/ruby/1.8
        - GEM CONFIGURATION:
           - :update_sources => true
           - :verbose => true
           - :benchmark => false
           - :backtrace => false
           - :bulk_threshold => 1000
           - "gem" => "--no-ri --no-rdoc"
        - REMOTE SOURCES:
           - http://rubygems.org/

  As you can see, the RubyGems executable path in the example happens to be /opt/ruby-enterprise-1.8.7-2010.01/bin. So that directory must be added to PATH.

- If you installed Phusion Passenger using the tarball, then the tools are in the bin subdirectory of the Phusion Passenger tarball directory that you extracted. For example, if you extracted passenger-4.9.0.tar.gz inside /opt, then the tools are located in /opt/passenger-4.0.9/bin. In that case, you need to add /opt/passenger-4.0.9/bin to your PATH.

- If you installed Phusion Passenger using native OS packages, then some Phusion Passenger administration tools are in /usr/bin, while others are in /usr/sbin. If you are not logged in as root, then /usr/sbin may not be in PATH, which would explain why you get a "command not found" when trying to invoke some of the tools. You should /usr/sbin to PATH.

- If you are unsure where your Phusion Passenger directory is then you can use the find command to look them up. Go to the root directory and invoke find with sudo:

      $ cd /
      $ sudo find . -name passenger-status
      /usr/local/passenger/bin/passenger-status

  In this example, the administration tools happen to be in /usr/local/passenger/bin, so you must add that to PATH.

| You may still get a "command not found" when invoking the tools through sudo, even after you’ve added the relevant directory to PATH. Please read Environment variables and sudo to learn more.

### 9.3. Making environment variables permanent

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.

#### 9.3.1. bash

To make environment variables permanent for future bash sessions for the current user, add them to your ~/.bashrc:

    echo 'export FOO=bar' >> ~/.bashrc
    echo 'export PATH=/usr/local/bin:$PATH' >> ~/.bashrc

To make them permanent for future bash sessions for all users, add them to /etc/bashrc.

| Depending on the system, the bashrc file may have a different filename. On Debian and Ubuntu, it’s /etc/bash.bashrc. NOTE: Make sure your ~/.bashrc is actually included by your ~/.profile, which might not be the case if you created the user with useradd instead of adduser for example

#### 9.3.2. Apache

| This subsection describes how to set environment variables on Apache itself, not on apps served through Phusion Passenger for Apache. The environment variables you set here will be passed to all apps, but you cannot customize them on a per-app basis. See also Setting environment variables on Phusion Passenger-served apps.

On Debian and Ubuntu, with an Apache installed through apt, Apache environment variables are defined in the file /etc/apache2/envvars. This is a shell script so environment variables must be specified with the shell syntax.

On Red Hat, Fedora, CentOS and ScientificLinux, with an Apache installed through YUM, Apache environment variables are defined in /etc/sysconfig/httpd.

On OS X they are defined in /System/Library/LaunchDaemons/org.apache.httpd.plist, as explained here on Stack Overflow.

On other systems, or if you did not install Apache through the system’s package manager, the configuration file for environment variables is specific to the vendor that supplied Apache. There may not even be such a configuration file. You should contact the vendor for support.

#### 9.3.3. Nginx

| This subsection describes how to set environment variables on Nginx itself, not on apps served through Phusion Passenger for Nginx. The environment variables you set here will be passed to all apps, but you cannot customize them on a per-app basis. See also Setting environment variables on Phusion Passenger-served apps.

If you installed Nginx through the Debian or Ubuntu packages, then you can define environment variables in /etc/default/nginx. This is a shell script so you must use the export FOO=bar syntax.

Otherwise, environment variables are best set through the script which starts Nginx. For example, if you installed Nginx from source and you used then you should edit that script to define the environment variables. Those init scripts are regular shell scripts, so use the export FOO=bar syntax. Just make sure your set your environment variables before the script starts Nginx.

| Setting environment variables on Nginx has no effect on the Flying Passenger daemon because the daemon is started seperately. You should set the environment variables in the shell right before starting the daemon.

#### 9.3.4. cron

To make environment variables permanent for cron jobs, add those variables to the relevant crontab. But note that inside crontabs you cannot refer to existing environment variables with the $ syntax because crontabs are not shell scripts. You have to specify the entire value.

What to put in "crontab -e"

    # Environment variable definitions
    FOO=bar
    APXS2=/usr/sbin/apxs2

    # **WRONG!** You cannot refer to existing variables with the `$` syntax!
    PATH=/usr/bin:$PATH
    # **WRONG!** You cannot use the 'export' keyword!
    export PATH=/usr/bin:/usr/local/bin
    # Correct:
    PATH=/usr/bin:/usr/local/bin

    # Jobs:
    # m h  dom mon dow   command
      * *  *   *   *     frobnicator

#### 9.3.5. Phusion Passenger-served apps

You can pass environment variables to Phusion Passenger-served apps through various methods:

- When running Apache, use the PassEnv and SetEnv directives of mod_env. This is supported starting from Phusion Passenger 4.0.

- When running Nginx, use the passenger_env_var directive.

- Through your bashrc. Starting from version 4.0, Phusion Passenger 4.0 spawns applications through bash and inherit all bash environment variables. Phusion Passenger Standalone tends to be started from the shell and thus inherits all environment variables set by the shell.

- Through Apache and Nginx, as described earlier in this chapter. Any environment variables that you set on Apache and Nginx itself are inherited by Phusion Passenger, and thus by Phusion Passenger-served apps as well.

- Through the application itself. Most programming languages provide APIs for setting environment variables. For example in Ruby you can write:

      ENV['FOO'] = 'bar'

  In Python you can write:

      import os
      os.environ['FOO'] = 'bar'

### 9.4. Environment variables and sudo

| RVM users should always use the rvmsudo command instead of sudo. However all information in this section apply to rvmsudo as well.

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):

    user@localhost bash$ export APXS2=/usr/sbin/apxs2
    user@localhost bash$ sudo -E passenger-install-apache2-module

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

    user@localhost bash$ sudo -s
    Password: ...
    root@localhost bash# export APXS2=/usr/sbin/apxs2
    root@localhost bash# passenger-install-apache2-module

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:

    user@localhost bash$ sudo -s
    Password: ...
    root@localhost bash# export PATH=$PATH:/opt/myruby/bin
    root@localhost bash# passenger-install-apache2-module