=== Synopsis

The Phusion Passenger installation process consists of two steps:

1. The *obtainment step*, where you download the Phusion Passenger files puts them somewhere on your system. This can be done through downloading the source tarball, installing the Ruby gem or installing a native OS package via APT or YUM.
2. The *integration step*, where you configure Phusion Passenger so that it works properly with other system components such as Apache, Nginx, Ruby, Python, etc.

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_install,RubyGems generic installation method>> (if you're a Ruby user) or the <<tarball_generic_install,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_generic_install]]
=== 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 <<relationship_with_ruby,Phusion Passenger and its relationship with Ruby>>.

[[is_ruby_home_or_system_wide_installed]]
[float]
==== Step 1: figuring out whether your Ruby is installed 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 -s`
* Are you not using RVM, or do you not know what RVM is? Run `sudo -s`
* Is 'sudo' not installed on your system? Run `su -c bash`

You must maintain this root prompt throughout this installation guide.

[float]
==== 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
----------------------

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 link:https://www.phusionpassenger.com/orders[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://YOUR_ORDER_REFERENCE:YOUR_PASSWORD@www.phusionpassenger.com/enterprise_gems/
------------------------------------------

Substitute 'YOUR_ORDER_REFERENCE' and 'YOUR_PASSWORD' with your link:https://www.phusionpassenger.com/orders[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:

----------------------
gem install passenger-enterprise-server
----------------------

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

[float]
==== Step 3: loosen permissions

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:

-------------------------
passenger-config --root
-------------------------

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

-------------------------
chmod o+x /home/phusion/.rvm/gems/ruby-1.9.3-p362/gems/passenger-x.x.x
chmod o+x /home/phusion/.rvm/gems/ruby-1.9.3-p362/gems
chmod o+x /home/phusion/.rvm/gems/ruby-1.9.3-p362
chmod o+x /home/phusion/.rvm/gems
chmod o+x /home/phusion/.rvm
chmod o+x /home/phusion
-------------------------

[[run_passenger_installer]]
[float]
==== Step 4: run the Phusion Passenger installer

ifdef::apache[]
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.

----------------------------------
passenger-install-apache2-module
----------------------------------

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_apache_conf,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,Troubleshooting>> section.

.What does the installer do?

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.
endif::[]
ifdef::nginx[]
Nginx is a different from other web servers in that it does not support loadable modules. The only way to extend Nginx is to recompile it entirely from source. Since Phusion Passenger consists of some external executables plus an Nginx module, you must recompile Nginx when first installing Phusion Passenger, but also when upgrading Nginx itself or when upgrading the Phusion Passenger version.

Recompiling Nginx and the Phusion Passenger executables is what we will do in this step. The good news is that Phusion Passenger provides a tool to make this easy for you.

If you've already installed Nginx before, but without Phusion Passenger support, then you *should* uninstall it first. You don't have to, because you can also install another Nginx with Phusion Passenger support, in parallel to the existing Nginx. We merely recommend uninstalling the existing in order to avoid user confusion, but the choice is yours.

If you had previously installed Nginx with Phusion Passenger support, and you are upgrading, then you don't have to uninstall your existing Nginx first. Instead we'll overwrite it this step. But it is important that you recompile Nginx with the configure parameters that you used last time.

Here's how you can uninstall the original Nginx:

- If you installed the existing Nginx through APT, run: `sudo apt-get remove nginx nginx-full nginx-light nginx-naxsi nginx-common`
- If you installed the existing Nginx through YUM, run `yum remove nginx` as root.

To proceed with installing or upgrading Phusion Passenger, run the Phusion Passenger Nginx installer and follow the on-screen instructions:

----------------------------------
passenger-install-nginx-module
----------------------------------

At some point it will ask you which prefix to install Nginx to. If you're upgrading, then specify the same prefix that you used last time, as well as the same configuration parameters that you used last time.
endif::[]

[float]
==== Step 5: Restarting the Flying Passenger daemon

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

-------------------------------
kill `cat /path-to/flying-passenger.pid`
-------------------------------

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

-------------------------------
ps auxw | grep flying-passenger
kill PID_OF_FLYING_PASSENGER
-------------------------------

[[verify_passenger_running]]
[float]
==== Step 6: Verifying that Phusion Passenger is running

Restart your web server and run:

---------------------------
passenger-memory-stats
---------------------------

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!
ifdef::nginx[]
At this point you may be interested in <<nginx_init_script,creating an Nginx init script>>.
endif::[]

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


[[tarball_generic_install]]
=== Generic installation, upgrade and downgrade method: via tarball

[float]
==== Step 1: download and extract the tarball

Download the open source Phusion Passenger tarball from link:https://www.phusionpassenger.com/download#open_source[the Phusion Passenger website]. Older versions can be found on link:https://www.phusionpassenger.com/file_releases[the release archive].

If you a link:https://www.phusionpassenger.com/enterprise[Phusion Passenger Enterprise] customer, download the Phusion Passenger Enterprise tarball from the link:https://www.phusionpassenger.com/orders[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:

--------------------------------------------------
mkdir $PREFIX
cd $PREFIX
tar xzvf /location-to/passenger-x.x.x.tar.gz
cd $PREFIX/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.

[float]
==== Step 2: loosen permissions

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.

-------------------------
chmod o+x /opt/passenger/passenger-4.0.0
chmod o+x /opt/passenger
chmod o+x /opt
-------------------------

[float]
==== Step 3: installing Ruby and Rake

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 <<relationship_with_ruby,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.

.Debian 6

We recommend you to use link:http://wiki.brightbox.co.uk/docs:phusion-passenger[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:

-----------------------------
echo deb http://ppa.launchpad.net/brightbox/ruby-ng/ubuntu lucid main | sudo tee /etc/apt/sources.list.d/brightbox-source.list
sudo apt-key adv --keyserver keyserver.ubuntu.com --recv-keys C3173AA6
-----------------------------

Then install Ruby and Rake:

-----------------------------
sudo apt-get update
sudo apt-get install ruby1.9.3
sudo gem install rake
-----------------------------

.Debian 5

Run:

-----------------------------
sudo apt-get update
sudo apt-get install ruby rake
-----------------------------

Then <<add_rubygems_bin_dir_to_path,add the RubyGems bin directory to your $PATH>>.

.Ubuntu

We recommend you to use link:http://wiki.brightbox.co.uk/docs:phusion-passenger[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:

-----------------------------
sudo apt-add-repository ppa:brightbox/passenger
sudo apt-get update
-----------------------------

Then install Ruby and Rake:

-----------------------------
sudo apt-get update
sudo apt-get install ruby1.9.3
sudo gem install rake
-----------------------------

.Other operating systems

Please install Ruby from link:http://www.ruby-lang.org/[the Ruby website]. Once Ruby is installed, run the following command (<<is_ruby_home_or_system_wide_installed,possibly as root>>) to install Rake:

-----------------------
gem install rake
-----------------------

[float]
==== Step 4: figuring out whether your Ruby is installed the home directory or system-wide

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

[float]
==== Step 5: run the Phusion Passenger installer

Please refer to <<run_passenger_installer,this section>>.
ifdef::apache[]
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'.
endif::[]
ifdef::nginx[]
Note that the `passenger-install-nginx-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-nginx-module'.
endif::[]

[float]
==== Step 6: Restarting the Flying Passenger daemon

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

-------------------------------
kill `cat /path-to/flying-passenger.pid`
-------------------------------

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

-------------------------------
ps auxw | grep flying-passenger
kill PID_OF_FLYING_PASSENGER
-------------------------------

[float]
==== Step 7: Verifying that Phusion Passenger is running

Please refer to <<verify_passenger_running,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'.


[[install_on_debian_ubuntu]]
=== Installing or upgrading on Debian or Ubuntu

We provide and 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 non-LTS Ubuntu release, plus all Debian releases that are still supported by Debian.

==== Adding our APT repository

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

--------------------------------------------------------------
gpg --keyserver keyserver.ubuntu.com --recv-keys 561F9B9CAC40B2F7
gpg --armor --export 561F9B9CAC40B2F7 | sudo apt-key add -
--------------------------------------------------------------

Our APT repository is stored on an HTTPS server so you may need to add HTTPS support for APT:

--------------------------------------------------------------
sudo apt-get install apt-transport-https
--------------------------------------------------------------

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

Phusion Passenger open source:

--------------------------------------------------------------
deb https://oss-binaries.phusionpassenger.com/apt/passenger lucid main
deb https://oss-binaries.phusionpassenger.com/apt/passenger precise main
deb https://oss-binaries.phusionpassenger.com/apt/passenger raring main
deb https://oss-binaries.phusionpassenger.com/apt/passenger squeeze main
deb https://oss-binaries.phusionpassenger.com/apt/passenger wheezy main
--------------------------------------------------------------

Phusion Passenger Enterprise:

--------------------------------------------------------------
deb https://YOUR_ORDER_REFERENCE:YOUR_PASSWORD@www.phusionpassenger.com/enterprise_apt lucid main
deb https://YOUR_ORDER_REFERENCE:YOUR_PASSWORD@www.phusionpassenger.com/enterprise_apt precise main
deb https://YOUR_ORDER_REFERENCE:YOUR_PASSWORD@www.phusionpassenger.com/enterprise_apt raring main
deb https://YOUR_ORDER_REFERENCE:YOUR_PASSWORD@www.phusionpassenger.com/enterprise_apt squeeze main
deb https://YOUR_ORDER_REFERENCE:YOUR_PASSWORD@www.phusionpassenger.com/enterprise_apt wheezy main
--------------------------------------------------------------

Please replace 'YOUR_ORDER_REFERENCE' and 'YOUR_PASSWORD' with your link:https://www.phusionpassenger.com/orders[Customer Area] login credentials.

After creating `/etc/apt/sources.list.d/passenger.list`, run:

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

==== Installing packages

.Open source

To install Phusion Passenger for Nginx:

--------------------------------------------------------------
sudo apt-get install nginx-full passenger
--------------------------------------------------------------

Then edit `/etc/nginx/nginx.conf`, and uncomment `passenger_root` and `passenger_ruby`. Finally, run `sudo service nginx restart`.

To install Phusion Passenger for Apache:

--------------------------------------------------------------
sudo apt-get install libapache2-mod-passenger
--------------------------------------------------------------

To install Phusion Passenger Standalone:

--------------------------------------------------------------
sudo apt-get install passenger
--------------------------------------------------------------

.Enterprise

Before installing packages, download your license key from the link:https://www.phusionpassenger.com/orders[Customer Area] and save it as `/etc/passenger-enterprise-license`.

To install Phusion Passenger for Nginx:

--------------------------------------------------------------
sudo apt-get install nginx-full passenger-enterprise
--------------------------------------------------------------

Then edit `/etc/nginx/nginx.conf`, and uncomment `passenger_root` and `passenger_ruby`. Finally, run `sudo service nginx restart`.

To install Phusion Passenger for Apache:

--------------------------------------------------------------
sudo apt-get install libapache2-mod-passenger-enterprise
--------------------------------------------------------------

To install Phusion Passenger Standalone:

--------------------------------------------------------------
sudo apt-get install passenger-enterprise
--------------------------------------------------------------


=== Installing or upgrading on Red Hat, Fedora, CentOS or ScientificLinux

YUM repositories with RPMs are maintained by link:https://github.com/erikogan/passenger[Erik Ogan] and link:http://stealthymonkeys.com/[Stealthy Monkeys Consulting]. Only packages for the open source version of Phusion Passenger are provided. link:https://www.phusionpassenger.com/enterprise[Phusion Passenger Enterprise] customers should use the <<rubygems_generic_install,generic RubyGems installation method>> or <<tarball_generic_install,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.

[float]
==== Step 1: Import the Stealthy Monkeys Consulting's GPG key

---------------------------------------------
rpm --import http://passenger.stealthymonkeys.com/RPM-GPG-KEY-stealthymonkeys.asc
---------------------------------------------

[float]
==== Step 2: Install the release package

Install the passenger-release package from the link:http://passenger.stealthymonkeys.com/[main repository].

Fedora Core 17:
---------------------------------------------
yum install http://passenger.stealthymonkeys.com/fedora/17/passenger-release.noarch.rpm
---------------------------------------------

Fedora Core 16:
---------------------------------------------
yum install http://passenger.stealthymonkeys.com/fedora/16/passenger-release.noarch.rpm
---------------------------------------------

Fedora Core 15:
---------------------------------------------
yum install http://passenger.stealthymonkeys.com/fedora/15/passenger-release.noarch.rpm
---------------------------------------------

Fedora Core 14:
---------------------------------------------
yum install http://passenger.stealthymonkeys.com/fedora/14/passenger-release.noarch.rpm
---------------------------------------------

RHEL 6 / CentOS 6 / ScientificLinux 6: (Note: these packages depend on link:http://fedoraproject.org/wiki/EPEL[EPEL].)
---------------------------------------------
yum install http://passenger.stealthymonkeys.com/rhel/6/passenger-release.noarch.rpm
---------------------------------------------

RHEL 5 / CentOS 5 / ScientificLinux 5: (Note: these packages depend on link:http://fedoraproject.org/wiki/EPEL[EPEL].)
---------------------------------------------
rpm -Uvh http://passenger.stealthymonkeys.com/rhel/5/passenger-release.noarch.rpm
---------------------------------------------

[float]
==== Step 3: Install the right Phusion Passenger package

From there you can use link:http://prefetch.net/articles/yum.html[YUM] to install packages. For example, try one of these:

Phusion Passenger for Apache:

---------------------------------------------
yum install mod_passenger
---------------------------------------------

Phusion Passenger for Nginx:

---------------------------------------------
yum install nginx-passenger
---------------------------------------------

Phusion Passenger Standalone:

---------------------------------------------
yum install passenger-standalone
---------------------------------------------

[float]
==== Building your own packages

There are instructions for building your own packages and Yum repositories in the link:https://github.com/phusion/passenger/tree/master/rpm#readme[rpm directory ReadMe] within the link:https://github.com/phusion/passenger[GitHub repository].


=== 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 the following command and follow the instructions. This will give you access to link:Users%20guide%20Apache.html[Phusion Passenger for Apache] and link:Users%20guide%20Standalone.html[Phusion Passenger Standalone].
+
---------------------------
brew install passenger
-OR-
brew upgrade passenger
---------------------------
 3. (Optional) If you want to use link:Users%20guide%20Nginx.html[Phusion Passenger for Nginx], run:
+
---------------------------
brew install nginx --with-passenger
-OR-
brew upgrade nginx --wtih-passenger
---------------------------

.Enterprise

link:https://www.phusionpassenger.com/enterprise[Phusion Passenger Enterprise] is currently not available through Homebrew. Please try one of the other installation methods insteads.


=== Upgrading from open source to Enterprise

Phusion Passenger comes in two variants: an open source version, as well as an link:https://www.phusionpassenger.com/enterprise[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. <<uninstalling,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_install,RubyGems generic installation>> or <<tarball_generic_install,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.


=== Cryptographic verification of installation files

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

==== 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 link:http://www.phusion.nl/about/gpg[the Phusion website] and at the key servers link:http://pool.sks-keyservers.net/pks/lookup?op=get&search=0x2AC745A50A212A8C[sks-keyservers.net] and link:http://keyserver.ubuntu.com/pks/lookup?op=get&search=0x2AC745A50A212A8C[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.

==== 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: 4B6F4332
  Long key ID: 06A131094B6F4332
  Fingerprint: 64E8 0420 FC6A 499F 9E1F  81FA 06A1 3109 4B6F 4332

  Ninh Bui (ninh@phusion.nl)
  Short key ID: 6FAF3782
  Long key ID: BA8DA3F46FAF3782
  Fingerprint: 353A 398C 49AF 5CD5 74A0  656C BA8D A3F4 6FAF 3782

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

------------------------------------------
gpg --keyserver pool.sks-servers.net --search-keys 0x06A131094B6F4332
gpg --keyserver pool.sks-servers.net --search-keys 0xBA8DA3F46FAF3782
# -OR-
gpg --keyserver keyserver.ubuntu.com --search-keys 0x06A131094B6F4332
gpg --keyserver keyserver.ubuntu.com --search-keys 0xBA8DA3F46FAF3782
------------------------------------------

==== Verifying the gem and tarball

You can find the open source version's gem and tarball GPG signatures at https://www.phusionpassenger.com/signatures/. The Enterprise version's GPG signatures can be found in the link:https://www.phusionpassenger.com/orders[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>"
-----------------------------------------

==== Verifying Git signatures

Tags in the link:https://github.com/FooBarWidget/passenger[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>"
-------------------------------------------------------

==== Verifying DEB and RPM packages

The DEB and RPM packages are signed with the signatures of the respective packagers. Phusion does not provide signatures for them.

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


=== Non-interactive, automatic, headless installs or upgrades

ifdef::apache[]
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.
endif::[]
ifdef::nginx[]
By default, the installer (`passenger-install-nginx-module`) is interactive. If you want to automate installation then you can do so by passing various answers to the installer through command line options. Please run the installer with `--help` for a list of available command line options.
endif::[]


=== 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,About environment variables>>.

==== 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 link:http://ccache.samba.org/[ccache] for faster recompilation, and may want to enable more error-catching compilation flags:

[source,sh]
----------------------
export CC='ccache clang -fcolor-diagnostics -Qunused-arguments -fcatch-undefined-behavior -ftrapv'
export CXX='ccache clang++ -fcolor-diagnostics -Qunused-arguments -fcatch-undefined-behavior -ftrapv'
----------------------

NOTE: If you run the installer with `sudo` then environment variables may not be passed properly. Learn more at <<env_vars_and_sudo,Environment variables and sudo>>.

==== 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 or C++ source files. This includes 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` and `EXTRA_PRE_CXXFLAGS`.
`EXTRA_LDFLAGS`::
	Similar to `EXTRA_PRE_LDFLAGS`, but injected at the very end of the command string, even after `EXTRA_CFLAGS` and `EXTRA_CXXFLAGS`.
`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.

NOTE: If you run the installer with `sudo` then environment variables may not be passed properly. Learn more at <<env_vars_and_sudo,Environment variables and sudo>>.

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

TIP: If you do not know what environment variables are, or how to use them, then please read <<env_vars_and_sudo,Environment variables and sudo>>.
NOTE: If you run the installer with `sudo` then environment variables may not be passed properly. Learn more at <<env_vars_and_sudo,Environment variables and sudo>>.


ifdef::apache[]
[[working_with_apache_conf]]
=== Working with the Apache configuration file

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:

- Create '/etc/apache2/mods-available/passenger.load' and paste the `LoadModule ...` directive that `passenger-install-apache2-module` outputs.
- Create '/etc/apache2/mods-available/passenger.conf' and paste the `PassengerRoot` and other Phusion Passenger options.
- Enable by running `sudo a2enmod passenger`.

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'.
endif::[]


ifdef::nginx[]
=== Installing as a normal Nginx module without using the installer

You can also install Phusion Passenger the way you install any other Nginx module, e.g. with `--add-module`. Run Nginx's configure script with `--add-module=/path-to-passenger-root/ext/nginx`.

If you installed Phusion Passenger via the gem, then 'path-to-passenger-root' can be obtained with the command:

--------------------------
passenger-config --root
--------------------------

This will probably output something along the lines of '/usr/lib/ruby/gems/1.8/gems/passenger-x.x.x',
so you'll probably have to specify something like `--add-module=/usr/lib/ruby/gems/1.8/gems/passenger-x.x.x/ext/nginx`.

If you installed Phusion Passenger via a source tarball, then 'path-to-passenger-root'
is the directory which contains the Phusion Passenger source code. So if you
extracted the Phusion Passenger source code to '/opt/passenger-x.x.x', then you'll
have to specify `--add-module=/opt/passenger-x.x.x/ext/nginx`.

After having installed Nginx with Phusion Passenger support, you must paste the following
line into your Nginx configuration file:

------------------------------------------
passenger_root /path-to-passenger-root;
------------------------------------------

After having done so, restart Nginx.

[[nginx_init_script]]
=== Creating an Nginx init script

If you installed Nginx with one of the generic installation methods then you won't have an init script to start, stop and restart Nginx with. A bare Nginx installation works with signals: you start it by invoking it from the command line, you stop it by sending SIGTERM to it and you gracefully restart it by sending SIGHUP to it.

If you prefer to use an init script then please refer to the following resources:

- link:http://wiki.nginx.org/Nginx-init-ubuntu[Init script for Ubuntu 8.04-9.10]
- link:http://library.linode.com/web-servers/nginx/installation/ubuntu-12.04-precise-pangolin#sph_create-an-init-script-to-manage-nginx[Init script for Ubuntu 12.04]
- link:http://wiki.nginx.org/RedHatNginxInitScript[Init script for Red Hat, Fedora and CentOS]

When using one of those init scripts, please make sure that the paths inside the init script are correct. In particular, the paths to the Nginx binary, to the PID file and to the configuration file must match the actual locations of your Nginx installation.
endif::[]


=== Disabling without uninstalling

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

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

- all Phusion Passenger configuration directives.
- the `LoadModule passenger_module` directive.

For example, if your configuration file looks like this...

-----------------------------------
Listen *:80
NameVirtualHosts *:80
....

LoadModule passenger_module /somewhere/passenger-x.x.x/ext/apache2/mod_passenger.so

PassengerRoot /somewhere/passenger/x.x.x
PassengerDefaultRuby /usr/bin/ruby
PassengerMaxPoolSize 10

<VirtualHost *:80>
    ServerName www.foo.com
    DocumentRoot /webapps/foo/public
    RailsBaseURI /rails
</VirtualHost>
-----------------------------------

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

-----------------------------------
Listen *:80
NameVirtualHosts *:80
....

# LoadModule passenger_module /somewhere/passenger-x.x.x/ext/apache2/mod_passenger.so

# PassengerRoot /somewhere/passenger/x.x.x
# PassengerDefaultRuby /usr/bin/ruby
# PassengerMaxPoolSize 10

<VirtualHost *:80>
    ServerName www.foo.com
    DocumentRoot /webapps/foo/public
    # RailsBaseURI /rails
</VirtualHost>
-----------------------------------
endif::[]
ifdef::nginx[]
To unload Phusion Passenger, edit your Nginx configuration file(s)
and comment out all Phusion Passenger configuration directives.

For example, if your configuration file looks like this...

-----------------------------------
...

http {
    passenger_root /somewhere/passenger-x.x.x;
    passenger_ruby /usr/bin/ruby;
    passenger_max_pool_size 10;

    gzip on;

    server {
        server_name www.foo.com;
        listen 80;
        root /webapps/foo/public;
        passenger_enabled on;
    }
}
-----------------------------------

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

-----------------------------------
...

http {
    # passenger_root /somewhere/passenger-x.x.x;
    # passenger_ruby /usr/bin/ruby;
    # passenger_max_pool_size 10;

    gzip on;

    server {
        server_name www.foo.com;
        listen 80;
        root /webapps/foo/public;
        # passenger_enabled on;
    }
}
-----------------------------------
endif::[]

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

[[uninstalling]]
=== Uninstalling

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 via a Ruby gem, then run `gem uninstall passenger` (or, if you're a link:https://www.phusionpassenger.com/enterprise[Phusion Passenger Enterprise] user, `gem uninstall passenger-enterprise-server`).
  You <<is_ruby_home_or_system_wide_installed,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.
- If you installed Phusion Passenger through Homebrew, then run `brew uninstall passenger`.

ifdef::nginx[]
Nginx does not have to be recompiled. Altough it contains Phusion Passenger code, it will not do anything when all Phusion Passenger configuration directives are removed.
endif::[]


[[moving_phusion_passenger]]
=== 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
--------------------------------------------------------------

Next you must tell your web server that Phusion Passenger has moved.
ifdef::apache[]
Open your <<working_with_apache_conf,Apache configuration file>> and set the 'PassengerRoot' directive to the new location:

---------------------------------------------
PassengerRoot /usr/local/passenger-4.0.0
---------------------------------------------
endif::[]
ifdef::nginx[]
Open your Nginx configuration file and set the 'passenger_root' directive to the new location:

---------------------------------------------
passenger_root /usr/local/passenger-4.0.0
---------------------------------------------
endif::[]

Restart your web server to finalize the change.
