gem version

Deployment: installations

Relevant selections for this article:

Ruby Nginx

Before deploying your app you have to make sure that Ruby and Passenger are installed.

Did you already install Ruby?

Installing Ruby with RVM

Before you can deploy your app on the production server, you need to install Ruby. In this tutorial we recommend that you use Ruby Version Manager (RVM) for this purpose. RVM is a tool for installing and managing multiple Ruby versions.

There are other ways to install Ruby, e.g. through yum, apt-get, source tarball, rbenv and chruby. You can use one of those other installation methods if you so wish, and this tutorial will work fine even if you installed Ruby using one of those other installation methods. But the one that we recommend in this tutorial is RVM, because in our opinion it is the easiest option.

Prepare the system

Ensure that curl and gpg are installed, as well as a compiler toolchain. Curl and gpg are needed for further installation steps, while the compiler toolchain is needed for installing common Ruby gems.

Debian, Ubuntu
$ sudo apt-get update
$ sudo apt-get install -y curl gnupg build-essential
Red Hat, CentOS, Rocky, Alma, Fedora, Amazon Linux, Scientific Linux
$ sudo yum install -y curl gpg gcc gcc-c++ make which tar
macOS You don't have to do anything. They are already installed.

Install RVM

Run the following commands on your production server to install RVM:

$ sudo gpg --keyserver hkp://keys.gnupg.net --recv-keys 409B6B1796C275462A1703113804BB82D39DC0E3 7D2BAF1CF37B13E2069D6956105BD0E739499BDB
$ curl -sSL https://get.rvm.io | sudo bash -s stable
$ sudo usermod -a -G rvm `whoami`

You may need to use gpg2 instead of gpg on some systems.

On systems where sudo is configured with secure_path, the shell environment needs to be modified to set rvmsudo_secure_path=1. secure_path is set on most Linux systems, but not on macOS. The following command tries to autodetect whether it is necessary to install rvmsudo_secure_path=1, and only installs the environment variable if it is the code.

$ if sudo grep -q secure_path /etc/sudoers; then sudo sh -c "echo export rvmsudo_secure_path=1 >> /etc/profile.d/rvm_secure_path.sh" && echo Environment variable installed; fi

When you are done with all this, relogin to your server to activate RVM. This is important: if you don't relogin, RVM doesn't work. Also if you use gnu screen or another terminal multiplexer, RVM also won't work; you must use a plain ssh session.

Install the Ruby version you want

Usually, installing the latest Ruby version will suffice. If you are deploying the example app from the quickstart, then that example application works with all Ruby versions.

However, if you are deploying your own app, then your app may have a specific Ruby version requirement.

To install the latest version of Ruby, run:

$ rvm install ruby
$ rvm --default use ruby

To install a specific version of Ruby, run:

$ rvm install ruby-X.X.X
$ rvm --default use ruby-X.X.X

Replace X.X.X with the Ruby version you want.

Install Bundler

Bundler is a popular tool for managing application gem dependencies. We will use Bundler in this tutorial, so let us install it:

$ gem install bundler --no-rdoc --no-ri

Optional: install Node.js if you're using Rails

If you are using Rails, then you must install Node.js. This is because Rails's asset pipeline compiler requires a Javascript runtime. The Node.js version does not matter.

If you do not use Rails then you can skip to the next step.

To install Node.js:

Ubuntu
$ sudo apt-get install -y nodejs &&
$ sudo ln -sf /usr/bin/nodejs /usr/local/bin/node
Debian ≥ 7 (Wheezy or later)

Run the following commands to install Node.js from the NodeSource APT repository.

$ sudo apt-get update &&
$ sudo apt-get install -y apt-transport-https ca-certificates &&
$ curl --fail -ssL -o setup-nodejs https://deb.nodesource.com/setup_8.x &&
$ sudo bash setup-nodejs &&
$ sudo apt-get install -y nodejs build-essential
Red Hat, CentOS, Rocky, Alma, Fedora, Amazon Linux, Scientific Linux
$ sudo yum install -y https://dl.fedoraproject.org/pub/epel/epel-release-latest-$(< /etc/redhat-release tr -dc '0-9.'|cut -d \. -f1).noarch.rpm
$ sudo yum install -y --enablerepo=epel nodejs npm
Other operating systems Please install Node.js from www.nodejs.org.

Heads-up: sudo vs rvmsudo

One thing you should be aware of when using RVM, is that you should use rvmsudo instead of sudo when executing Ruby-related commands. This is because RVM works by manipulating environment variables. However, sudo nukes all environment variables for security reasons, which intereferes with RVM.

Visit the RVM website to learn more about rvmsudo.

All done!

Congratulations, you have now installed Ruby!

Installing Passenger + on a production server

Now it is time to install Passenger. Please start by selecting the operating system that your server is running on, or an installation method that you prefer.

Loading...

Step 1: install Passenger package

You can install Passenger through Homebrew:

$ brew install nginx passenger

Step 2: enable the Passenger Nginx module and restart Nginx

Passenger is now installed, but it still needs to be enabled inside Nginx. Run brew info passenger and follow the instructions in the "Caveats" section:

$ brew info passenger
...
==> Caveats
...

To activate Passenger, ...
(...more instructions that you should follow...)

When you are done following the instructions, restart Nginx:

$ sudo launchctl unload /usr/local/opt/nginx/*.plist
$ sudo launchctl load /usr/local/opt/nginx/*.plist

Step 3: check installation

After installation, please validate the install by running sudo /usr/local/bin/passenger-config validate-install. For example:

$ sudo /usr/local/bin/passenger-config validate-install
 * Checking whether this Phusion Passenger install is in PATH... ✓
 * Checking whether there are no other Phusion Passenger installations... ✓

All checks should pass. If any of the checks do not pass, please follow the suggestions on screen.

Finally, check whether Nginx has started the Passenger core processes. Run sudo /usr/local/bin/passenger-memory-stats. You should see Nginx processes as well as Passenger processes. For example:

$ sudo /usr/local/bin/passenger-memory-stats
Version: 5.0.8
Date   : 2015-05-28 08:46:20 +0200
...

---------- Nginx processes ----------
PID    PPID   VMSize   Private  Name
-------------------------------------
12443  4814   60.8 MB  0.2 MB   nginx: master process /usr/sbin/nginx
12538  12443  64.9 MB  5.0 MB   nginx: worker process
### Processes: 3
### Total private dirty RSS: 5.56 MB

----- Passenger processes ------
PID    VMSize    Private   Name
--------------------------------
12517  83.2 MB   0.6 MB    PassengerAgent watchdog
12520  266.0 MB  3.4 MB    PassengerAgent server
12531  149.5 MB  1.4 MB    PassengerAgent logger
...

If you do not see any Nginx processes or Passenger processes, then you probably have some kind of installation problem or configuration problem. Please refer to the troubleshooting guide.

Step 1: install Passenger packages

These commands will install Passenger + Nginx module through Phusion's APT repository.

At this point we assume that you already have Nginx installed from your system repository. If not, you should install Nginx with the following command:
sudo apt-get install nginx
If you want to use our packaged Nginx module, you must use your distro's provided Nginx package. If for example you have the repo provided by NGINX setup, you will instead need to compile a dynamic module compatible with that Nginx.

# Install our PGP key and add HTTPS support for APT
sudo apt-get install -y dirmngr gnupg apt-transport-https ca-certificates curl

curl https://oss-binaries.phusionpassenger.com/auto-software-signing-gpg-key.txt | gpg --dearmor | sudo tee /etc/apt/trusted.gpg.d/phusion.gpg >/dev/null

# Add our APT repository
sudo sh -c 'echo deb https://oss-binaries.phusionpassenger.com/apt/passenger bookworm main > /etc/apt/sources.list.d/passenger.list'
sudo apt-get update

# Install Passenger + Nginx module
sudo apt-get install -y libnginx-mod-http-passenger

Step 2: enable the Passenger Nginx module and restart Nginx

Ensure the config files are in-place:

$ if [ ! -f /etc/nginx/modules-enabled/50-mod-http-passenger.conf ]; then sudo ln -s /usr/share/nginx/modules-available/mod-http-passenger.load /etc/nginx/modules-enabled/50-mod-http-passenger.conf ; fi
$ sudo ls /etc/nginx/conf.d/mod-http-passenger.conf

If you don't see a file at /etc/nginx/conf.d/mod-http-passenger.conf; then you need to create it yourself and set the passenger_ruby and passenger_root config options. For example:

passenger_root /usr/lib/ruby/vendor_ruby/phusion_passenger/locations.ini;
passenger_ruby /usr/bin/passenger_free_ruby;

When you are finished with this step, restart Nginx:

$ sudo service nginx restart

Step 3: check installation

After installation, please validate the install by running sudo /usr/bin/passenger-config validate-install. For example:

$ sudo /usr/bin/passenger-config validate-install
 * Checking whether this Phusion Passenger install is in PATH... ✓
 * Checking whether there are no other Phusion Passenger installations... ✓

All checks should pass. If any of the checks do not pass, please follow the suggestions on screen.

Finally, check whether Nginx has started the Passenger core processes. Run sudo /usr/sbin/passenger-memory-stats. You should see Nginx processes as well as Passenger processes. For example:

$ sudo /usr/sbin/passenger-memory-stats
Version: 5.0.8
Date   : 2015-05-28 08:46:20 +0200
...

---------- Nginx processes ----------
PID    PPID   VMSize   Private  Name
-------------------------------------
12443  4814   60.8 MB  0.2 MB   nginx: master process /usr/sbin/nginx
12538  12443  64.9 MB  5.0 MB   nginx: worker process
### Processes: 3
### Total private dirty RSS: 5.56 MB

----- Passenger processes ------
PID    VMSize    Private   Name
--------------------------------
12517  83.2 MB   0.6 MB    PassengerAgent watchdog
12520  266.0 MB  3.4 MB    PassengerAgent server
12531  149.5 MB  1.4 MB    PassengerAgent logger
...

If you do not see any Nginx processes or Passenger processes, then you probably have some kind of installation problem or configuration problem. Please refer to the troubleshooting guide.

Step 4: update regularly

nginx updates, Passenger updates and system updates are delivered through the APT package manager regularly. You should run the following command regularly to keep them up to date:

$ sudo apt-get update
$ sudo apt-get upgrade

You do not need to restart nginx or Passenger after an update, and you also do not need to modify any configuration files after an update. That is all taken care of automatically for you by APT.

Step 1: install Passenger packages

These commands will install Passenger + Nginx module through Phusion's APT repository.

At this point we assume that you already have Nginx installed from your system repository. If not, you should install Nginx with the following command:
sudo apt-get install nginx
If you want to use our packaged Nginx module, you must use your distro's provided Nginx package. If for example you have the repo provided by NGINX setup, you will instead need to compile a dynamic module compatible with that Nginx.

# Install our PGP key and add HTTPS support for APT
sudo apt-get install -y dirmngr gnupg apt-transport-https ca-certificates curl

curl https://oss-binaries.phusionpassenger.com/auto-software-signing-gpg-key.txt | gpg --dearmor | sudo tee /etc/apt/trusted.gpg.d/phusion.gpg >/dev/null

# Add our APT repository
sudo sh -c 'echo deb https://oss-binaries.phusionpassenger.com/apt/passenger bullseye main > /etc/apt/sources.list.d/passenger.list'
sudo apt-get update

# Install Passenger + Nginx module
sudo apt-get install -y libnginx-mod-http-passenger

Step 2: enable the Passenger Nginx module and restart Nginx

Ensure the config files are in-place:

$ if [ ! -f /etc/nginx/modules-enabled/50-mod-http-passenger.conf ]; then sudo ln -s /usr/share/nginx/modules-available/mod-http-passenger.load /etc/nginx/modules-enabled/50-mod-http-passenger.conf ; fi
$ sudo ls /etc/nginx/conf.d/mod-http-passenger.conf

If you don't see a file at /etc/nginx/conf.d/mod-http-passenger.conf; then you need to create it yourself and set the passenger_ruby and passenger_root config options. For example:

passenger_root /usr/lib/ruby/vendor_ruby/phusion_passenger/locations.ini;
passenger_ruby /usr/bin/passenger_free_ruby;

When you are finished with this step, restart Nginx:

$ sudo service nginx restart

Step 3: check installation

After installation, please validate the install by running sudo /usr/bin/passenger-config validate-install. For example:

$ sudo /usr/bin/passenger-config validate-install
 * Checking whether this Phusion Passenger install is in PATH... ✓
 * Checking whether there are no other Phusion Passenger installations... ✓

All checks should pass. If any of the checks do not pass, please follow the suggestions on screen.

Finally, check whether Nginx has started the Passenger core processes. Run sudo /usr/sbin/passenger-memory-stats. You should see Nginx processes as well as Passenger processes. For example:

$ sudo /usr/sbin/passenger-memory-stats
Version: 5.0.8
Date   : 2015-05-28 08:46:20 +0200
...

---------- Nginx processes ----------
PID    PPID   VMSize   Private  Name
-------------------------------------
12443  4814   60.8 MB  0.2 MB   nginx: master process /usr/sbin/nginx
12538  12443  64.9 MB  5.0 MB   nginx: worker process
### Processes: 3
### Total private dirty RSS: 5.56 MB

----- Passenger processes ------
PID    VMSize    Private   Name
--------------------------------
12517  83.2 MB   0.6 MB    PassengerAgent watchdog
12520  266.0 MB  3.4 MB    PassengerAgent server
12531  149.5 MB  1.4 MB    PassengerAgent logger
...

If you do not see any Nginx processes or Passenger processes, then you probably have some kind of installation problem or configuration problem. Please refer to the troubleshooting guide.

Step 4: update regularly

nginx updates, Passenger updates and system updates are delivered through the APT package manager regularly. You should run the following command regularly to keep them up to date:

$ sudo apt-get update
$ sudo apt-get upgrade

You do not need to restart nginx or Passenger after an update, and you also do not need to modify any configuration files after an update. That is all taken care of automatically for you by APT.

Step 1: install Passenger packages

These commands will install Passenger + Nginx module through Phusion's APT repository.

At this point we assume that you already have Nginx installed from your system repository. If not, you should install Nginx with the following command:
sudo apt-get install nginx
If you want to use our packaged Nginx module, you must use your distro's provided Nginx package. If for example you have the repo provided by NGINX setup, you will instead need to compile a dynamic module compatible with that Nginx.

# Install our PGP key and add HTTPS support for APT
sudo apt-get install -y dirmngr gnupg apt-transport-https ca-certificates 

sudo apt-key adv --keyserver hkp://keyserver.ubuntu.com:80 --recv-keys 561F9B9CAC40B2F7

# Add our APT repository
sudo sh -c 'echo deb https://oss-binaries.phusionpassenger.com/apt/passenger buster main > /etc/apt/sources.list.d/passenger.list'
sudo apt-get update

# Install Passenger + Nginx module
sudo apt-get install -y libnginx-mod-http-passenger

Step 2: enable the Passenger Nginx module and restart Nginx

Ensure the config files are in-place:

$ if [ ! -f /etc/nginx/modules-enabled/50-mod-http-passenger.conf ]; then sudo ln -s /usr/share/nginx/modules-available/mod-http-passenger.load /etc/nginx/modules-enabled/50-mod-http-passenger.conf ; fi
$ sudo ls /etc/nginx/conf.d/mod-http-passenger.conf

If you don't see a file at /etc/nginx/conf.d/mod-http-passenger.conf; then you need to create it yourself and set the passenger_ruby and passenger_root config options. For example:

passenger_root /usr/lib/ruby/vendor_ruby/phusion_passenger/locations.ini;
passenger_ruby /usr/bin/passenger_free_ruby;

When you are finished with this step, restart Nginx:

$ sudo service nginx restart

Step 3: check installation

After installation, please validate the install by running sudo /usr/bin/passenger-config validate-install. For example:

$ sudo /usr/bin/passenger-config validate-install
 * Checking whether this Phusion Passenger install is in PATH... ✓
 * Checking whether there are no other Phusion Passenger installations... ✓

All checks should pass. If any of the checks do not pass, please follow the suggestions on screen.

Finally, check whether Nginx has started the Passenger core processes. Run sudo /usr/sbin/passenger-memory-stats. You should see Nginx processes as well as Passenger processes. For example:

$ sudo /usr/sbin/passenger-memory-stats
Version: 5.0.8
Date   : 2015-05-28 08:46:20 +0200
...

---------- Nginx processes ----------
PID    PPID   VMSize   Private  Name
-------------------------------------
12443  4814   60.8 MB  0.2 MB   nginx: master process /usr/sbin/nginx
12538  12443  64.9 MB  5.0 MB   nginx: worker process
### Processes: 3
### Total private dirty RSS: 5.56 MB

----- Passenger processes ------
PID    VMSize    Private   Name
--------------------------------
12517  83.2 MB   0.6 MB    PassengerAgent watchdog
12520  266.0 MB  3.4 MB    PassengerAgent server
12531  149.5 MB  1.4 MB    PassengerAgent logger
...

If you do not see any Nginx processes or Passenger processes, then you probably have some kind of installation problem or configuration problem. Please refer to the troubleshooting guide.

Step 4: update regularly

nginx updates, Passenger updates and system updates are delivered through the APT package manager regularly. You should run the following command regularly to keep them up to date:

$ sudo apt-get update
$ sudo apt-get upgrade

You do not need to restart nginx or Passenger after an update, and you also do not need to modify any configuration files after an update. That is all taken care of automatically for you by APT.

Heads up: limited package support for non-LTS Ubuntu versions

Before we continue, you should know that the Ubuntu version you selected is a non-LTS (Long Term Support) version. This means that Canonical — the company that created Ubuntu — only supports this particular Ubuntu version for 1 year.

Because of this short support cycle by Canonical, we only provide Passenger package updates for this Ubuntu version for 6 months. That's when the next Ubuntu version comes out.

So when the next Ubuntu version is released, you must upgrade your system to that new Ubuntu version. Otherwise you won't receive Passenger updates in the form of .deb packages from us anymore.

If you don't like having to upgrade your Ubuntu system every 6 months, then you should use an LTS version of Ubuntu. Canonical supports LTS versions for 5 years, and we provide Passenger package updates for LTS versions for 5 years too.

Now that you know this, let's move on.

Step 1: install Passenger packages

These commands will install Passenger + Nginx module through Phusion's APT repository.

At this point we assume that you already have Nginx installed from your system repository. If not, you should install Nginx with the following command:
sudo apt-get install nginx
If you want to use our packaged Nginx module, you must use your distro's provided Nginx package. If for example you have the repo provided by NGINX setup, you will instead need to compile a dynamic module compatible with that Nginx.

# Install our PGP key and add HTTPS support for APT
sudo apt-get install -y dirmngr gnupg apt-transport-https ca-certificates curl

curl https://oss-binaries.phusionpassenger.com/auto-software-signing-gpg-key.txt | gpg --dearmor | sudo tee /etc/apt/trusted.gpg.d/phusion.gpg >/dev/null

# Add our APT repository
sudo sh -c 'echo deb https://oss-binaries.phusionpassenger.com/apt/passenger mantic main > /etc/apt/sources.list.d/passenger.list'
sudo apt-get update

# Install Passenger + Nginx module
sudo apt-get install -y libnginx-mod-http-passenger

Step 2: enable the Passenger Nginx module and restart Nginx

Ensure the config files are in-place:

$ if [ ! -f /etc/nginx/modules-enabled/50-mod-http-passenger.conf ]; then sudo ln -s /usr/share/nginx/modules-available/mod-http-passenger.load /etc/nginx/modules-enabled/50-mod-http-passenger.conf ; fi
$ sudo ls /etc/nginx/conf.d/mod-http-passenger.conf

If you don't see a file at /etc/nginx/conf.d/mod-http-passenger.conf; then you need to create it yourself and set the passenger_ruby and passenger_root config options. For example:

passenger_root /usr/lib/ruby/vendor_ruby/phusion_passenger/locations.ini;
passenger_ruby /usr/bin/passenger_free_ruby;

When you are finished with this step, restart Nginx:

$ sudo service nginx restart

Step 3: check installation

After installation, please validate the install by running sudo /usr/bin/passenger-config validate-install. For example:

$ sudo /usr/bin/passenger-config validate-install
 * Checking whether this Phusion Passenger install is in PATH... ✓
 * Checking whether there are no other Phusion Passenger installations... ✓

All checks should pass. If any of the checks do not pass, please follow the suggestions on screen.

Finally, check whether Nginx has started the Passenger core processes. Run sudo /usr/sbin/passenger-memory-stats. You should see Nginx processes as well as Passenger processes. For example:

$ sudo /usr/sbin/passenger-memory-stats
Version: 5.0.8
Date   : 2015-05-28 08:46:20 +0200
...

---------- Nginx processes ----------
PID    PPID   VMSize   Private  Name
-------------------------------------
12443  4814   60.8 MB  0.2 MB   nginx: master process /usr/sbin/nginx
12538  12443  64.9 MB  5.0 MB   nginx: worker process
### Processes: 3
### Total private dirty RSS: 5.56 MB

----- Passenger processes ------
PID    VMSize    Private   Name
--------------------------------
12517  83.2 MB   0.6 MB    PassengerAgent watchdog
12520  266.0 MB  3.4 MB    PassengerAgent server
12531  149.5 MB  1.4 MB    PassengerAgent logger
...

If you do not see any Nginx processes or Passenger processes, then you probably have some kind of installation problem or configuration problem. Please refer to the troubleshooting guide.

Step 4: update regularly

nginx updates, Passenger updates and system updates are delivered through the APT package manager regularly. You should run the following command regularly to keep them up to date:

$ sudo apt-get update
$ sudo apt-get upgrade

You do not need to restart nginx or Passenger after an update, and you also do not need to modify any configuration files after an update. That is all taken care of automatically for you by APT.

Step 1: install Passenger packages

These commands will install Passenger + Nginx module through Phusion's APT repository.

At this point we assume that you already have Nginx installed from your system repository. If not, you should install Nginx with the following command:
sudo apt-get install nginx
If you want to use our packaged Nginx module, you must use your distro's provided Nginx package. If for example you have the repo provided by NGINX setup, you will instead need to compile a dynamic module compatible with that Nginx.

# Install our PGP key and add HTTPS support for APT
sudo apt-get install -y dirmngr gnupg apt-transport-https ca-certificates curl

curl https://oss-binaries.phusionpassenger.com/auto-software-signing-gpg-key.txt | gpg --dearmor | sudo tee /etc/apt/trusted.gpg.d/phusion.gpg >/dev/null

# Add our APT repository
sudo sh -c 'echo deb https://oss-binaries.phusionpassenger.com/apt/passenger jammy main > /etc/apt/sources.list.d/passenger.list'
sudo apt-get update

# Install Passenger + Nginx module
sudo apt-get install -y libnginx-mod-http-passenger

Step 2: enable the Passenger Nginx module and restart Nginx

Ensure the config files are in-place:

$ if [ ! -f /etc/nginx/modules-enabled/50-mod-http-passenger.conf ]; then sudo ln -s /usr/share/nginx/modules-available/mod-http-passenger.load /etc/nginx/modules-enabled/50-mod-http-passenger.conf ; fi
$ sudo ls /etc/nginx/conf.d/mod-http-passenger.conf

If you don't see a file at /etc/nginx/conf.d/mod-http-passenger.conf; then you need to create it yourself and set the passenger_ruby and passenger_root config options. For example:

passenger_root /usr/lib/ruby/vendor_ruby/phusion_passenger/locations.ini;
passenger_ruby /usr/bin/passenger_free_ruby;

When you are finished with this step, restart Nginx:

$ sudo service nginx restart

Step 3: check installation

After installation, please validate the install by running sudo /usr/bin/passenger-config validate-install. For example:

$ sudo /usr/bin/passenger-config validate-install
 * Checking whether this Phusion Passenger install is in PATH... ✓
 * Checking whether there are no other Phusion Passenger installations... ✓

All checks should pass. If any of the checks do not pass, please follow the suggestions on screen.

Finally, check whether Nginx has started the Passenger core processes. Run sudo /usr/sbin/passenger-memory-stats. You should see Nginx processes as well as Passenger processes. For example:

$ sudo /usr/sbin/passenger-memory-stats
Version: 5.0.8
Date   : 2015-05-28 08:46:20 +0200
...

---------- Nginx processes ----------
PID    PPID   VMSize   Private  Name
-------------------------------------
12443  4814   60.8 MB  0.2 MB   nginx: master process /usr/sbin/nginx
12538  12443  64.9 MB  5.0 MB   nginx: worker process
### Processes: 3
### Total private dirty RSS: 5.56 MB

----- Passenger processes ------
PID    VMSize    Private   Name
--------------------------------
12517  83.2 MB   0.6 MB    PassengerAgent watchdog
12520  266.0 MB  3.4 MB    PassengerAgent server
12531  149.5 MB  1.4 MB    PassengerAgent logger
...

If you do not see any Nginx processes or Passenger processes, then you probably have some kind of installation problem or configuration problem. Please refer to the troubleshooting guide.

Step 4: update regularly

nginx updates, Passenger updates and system updates are delivered through the APT package manager regularly. You should run the following command regularly to keep them up to date:

$ sudo apt-get update
$ sudo apt-get upgrade

You do not need to restart nginx or Passenger after an update, and you also do not need to modify any configuration files after an update. That is all taken care of automatically for you by APT.

Step 1: install Passenger packages

These commands will install Passenger + Nginx module through Phusion's APT repository.

At this point we assume that you already have Nginx installed from your system repository. If not, you should install Nginx with the following command:
sudo apt-get install nginx
If you want to use our packaged Nginx module, you must use your distro's provided Nginx package. If for example you have the repo provided by NGINX setup, you will instead need to compile a dynamic module compatible with that Nginx.

# Install our PGP key and add HTTPS support for APT
sudo apt-get install -y dirmngr gnupg apt-transport-https ca-certificates 

sudo apt-key adv --keyserver hkp://keyserver.ubuntu.com:80 --recv-keys 561F9B9CAC40B2F7

# Add our APT repository
sudo sh -c 'echo deb https://oss-binaries.phusionpassenger.com/apt/passenger focal main > /etc/apt/sources.list.d/passenger.list'
sudo apt-get update

# Install Passenger + Nginx module
sudo apt-get install -y libnginx-mod-http-passenger

Step 2: enable the Passenger Nginx module and restart Nginx

Ensure the config files are in-place:

$ if [ ! -f /etc/nginx/modules-enabled/50-mod-http-passenger.conf ]; then sudo ln -s /usr/share/nginx/modules-available/mod-http-passenger.load /etc/nginx/modules-enabled/50-mod-http-passenger.conf ; fi
$ sudo ls /etc/nginx/conf.d/mod-http-passenger.conf

If you don't see a file at /etc/nginx/conf.d/mod-http-passenger.conf; then you need to create it yourself and set the passenger_ruby and passenger_root config options. For example:

passenger_root /usr/lib/ruby/vendor_ruby/phusion_passenger/locations.ini;
passenger_ruby /usr/bin/passenger_free_ruby;

When you are finished with this step, restart Nginx:

$ sudo service nginx restart

Step 3: check installation

After installation, please validate the install by running sudo /usr/bin/passenger-config validate-install. For example:

$ sudo /usr/bin/passenger-config validate-install
 * Checking whether this Phusion Passenger install is in PATH... ✓
 * Checking whether there are no other Phusion Passenger installations... ✓

All checks should pass. If any of the checks do not pass, please follow the suggestions on screen.

Finally, check whether Nginx has started the Passenger core processes. Run sudo /usr/sbin/passenger-memory-stats. You should see Nginx processes as well as Passenger processes. For example:

$ sudo /usr/sbin/passenger-memory-stats
Version: 5.0.8
Date   : 2015-05-28 08:46:20 +0200
...

---------- Nginx processes ----------
PID    PPID   VMSize   Private  Name
-------------------------------------
12443  4814   60.8 MB  0.2 MB   nginx: master process /usr/sbin/nginx
12538  12443  64.9 MB  5.0 MB   nginx: worker process
### Processes: 3
### Total private dirty RSS: 5.56 MB

----- Passenger processes ------
PID    VMSize    Private   Name
--------------------------------
12517  83.2 MB   0.6 MB    PassengerAgent watchdog
12520  266.0 MB  3.4 MB    PassengerAgent server
12531  149.5 MB  1.4 MB    PassengerAgent logger
...

If you do not see any Nginx processes or Passenger processes, then you probably have some kind of installation problem or configuration problem. Please refer to the troubleshooting guide.

Step 4: update regularly

nginx updates, Passenger updates and system updates are delivered through the APT package manager regularly. You should run the following command regularly to keep them up to date:

$ sudo apt-get update
$ sudo apt-get upgrade

You do not need to restart nginx or Passenger after an update, and you also do not need to modify any configuration files after an update. That is all taken care of automatically for you by APT.

Step 1: enable EPEL

The instructions differ depending on whether you are on Red Hat or another Enterprise Linux. The second step is only necessary on Red Hat.

Step 1:
install EPEL package
Passenger requires EPEL.
$ sudo yum install -y yum-utils
$ sudo yum install -y https://dl.fedoraproject.org/pub/epel/epel-release-latest-$(< /etc/redhat-release tr -dc '0-9.'|cut -d \. -f1).noarch.rpm
$ sudo yum-config-manager --enable epel
$ sudo yum clean all && sudo yum update -y
Step 2 (RHEL only):
enable the 'optional' repository
Enable the optional repository (rhel-9-server-optional-rpms). This can be done by enabling the RHEL optional subchannel for RHN-Classic. For certificate-based subscriptions see Red Hat Subscription Management Guide. The following commands may be helpful, but are not thoroughly tested.
$ sudo subscription-manager register --username $RHN_USERNAME --password $RHN_PASSWORD --auto-attach
$ sudo subscription-manager repos --enable rhel-9-server-optional-rpms

Step 2: repair potential system issues

These commands will fix common issues that prevent yum from installing Passenger

# Ensure curl and nss/openssl are sufficiently up-to-date to talk to the repo
sudo yum update -y

date
# if the output of date is wrong, please follow these instructions to install ntp

sudo yum install -y ntp
sudo chkconfig ntpd on
sudo ntpdate pool.ntp.org
sudo service ntpd start


sudo yum -y install chrony
sudo systemctl enable chronyd
sudo firewall-cmd --permanent --add-service=ntp
sudo firewall-cmd --reload
sudo systemctl restart chronyd

Step 3: install Passenger packages

These commands will install Passenger dynamic Nginx module through Phusion's YUM repository.

If you want to use our packaged Nginx module, you must use your distro's provided Nginx package. If for example you have the repo provided by NGINX setup, you will instead need to compile a dynamic module compatible with that Nginx.

# Install various prerequisites
sudo yum install -y  curl

# Add our el9 YUM repository
sudo curl --fail -sSLo /etc/yum.repos.d/passenger.repo https://oss-binaries.phusionpassenger.com/yum/definitions/el-passenger.repo

# Install Passenger dynamic Nginx module
sudo yum module enable -y nginx:$(sudo yum module list nginx | cut -d ' ' -f 2 | grep -Ee '^[0-9\.]+$' | sort -V | tail -1)
sudo yum install -y nginx-mod-http-passenger || { sudo yum-config-manager --enable cr && sudo yum install -y nginx-mod-http-passenger ; }

Step 4: restart Nginx

Now that the Passenger Nginx module is installed, restart Nginx to ensure that Passenger is activated:

$ sudo systemctl restart nginx

Step 5: check installation

After installation, please validate the install by running sudo /usr/bin/passenger-config validate-install. For example:

$ sudo /usr/bin/passenger-config validate-install
 * Checking whether this Phusion Passenger install is in PATH... ✓
 * Checking whether there are no other Phusion Passenger installations... ✓

All checks should pass. If any of the checks do not pass, please follow the suggestions on screen.

Finally, check whether Nginx has started the Passenger core processes. Run sudo /usr/sbin/passenger-memory-stats. You should see Nginx processes as well as Passenger processes. For example:

$ sudo /usr/sbin/passenger-memory-stats
Version: 5.0.8
Date   : 2015-05-28 08:46:20 +0200
...

---------- Nginx processes ----------
PID    PPID   VMSize   Private  Name
-------------------------------------
12443  4814   60.8 MB  0.2 MB   nginx: master process /usr/sbin/nginx
12538  12443  64.9 MB  5.0 MB   nginx: worker process
### Processes: 3
### Total private dirty RSS: 5.56 MB

----- Passenger processes ------
PID    VMSize    Private   Name
--------------------------------
12517  83.2 MB   0.6 MB    PassengerAgent watchdog
12520  266.0 MB  3.4 MB    PassengerAgent server
12531  149.5 MB  1.4 MB    PassengerAgent logger
...

If you do not see any Nginx processes or Passenger processes, then you probably have some kind of installation problem or configuration problem. Please refer to the troubleshooting guide.

Step 6: update regularly

Nginx updates, Passenger updates and system updates are delivered through the YUM package manager regularly. You should run the following command regularly to keep them up to date:

$ sudo yum update

After an update, you should restart Nginx. Doing so will automatically restart Passenger too.

Step 1: enable EPEL

The instructions differ depending on whether you are on Red Hat or another Enterprise Linux. The second step is only necessary on Red Hat.

Step 1:
install EPEL package
Passenger requires EPEL.
$ sudo yum install -y yum-utils
$ sudo yum install -y https://dl.fedoraproject.org/pub/epel/epel-release-latest-$(< /etc/redhat-release tr -dc '0-9.'|cut -d \. -f1).noarch.rpm
$ sudo yum-config-manager --enable epel
$ sudo yum clean all && sudo yum update -y
Step 2 (RHEL only):
enable the 'optional' repository
Enable the optional repository (rhel-8-server-optional-rpms). This can be done by enabling the RHEL optional subchannel for RHN-Classic. For certificate-based subscriptions see Red Hat Subscription Management Guide. The following commands may be helpful, but are not thoroughly tested.
$ sudo subscription-manager register --username $RHN_USERNAME --password $RHN_PASSWORD --auto-attach
$ sudo subscription-manager repos --enable rhel-8-server-optional-rpms

Step 2: repair potential system issues

These commands will fix common issues that prevent yum from installing Passenger

# Ensure curl and nss/openssl are sufficiently up-to-date to talk to the repo
sudo yum update -y

date
# if the output of date is wrong, please follow these instructions to install ntp

sudo yum install -y ntp
sudo chkconfig ntpd on
sudo ntpdate pool.ntp.org
sudo service ntpd start


sudo yum -y install chrony
sudo systemctl enable chronyd
sudo firewall-cmd --permanent --add-service=ntp
sudo firewall-cmd --reload
sudo systemctl restart chronyd

Step 3: install Passenger packages

These commands will install Passenger dynamic Nginx module through Phusion's YUM repository.

If you want to use our packaged Nginx module, you must use your distro's provided Nginx package. If for example you have the repo provided by NGINX setup, you will instead need to compile a dynamic module compatible with that Nginx.

# Install various prerequisites
sudo yum install -y  curl

# Add our el8 YUM repository
sudo curl --fail -sSLo /etc/yum.repos.d/passenger.repo https://oss-binaries.phusionpassenger.com/yum/definitions/el-passenger.repo

# Install Passenger dynamic Nginx module
sudo yum module enable -y nginx:$(sudo yum module list nginx | cut -d ' ' -f 2 | grep -Ee '^[0-9\.]+$' | sort -V | tail -1)
sudo yum install -y nginx-mod-http-passenger || { sudo yum-config-manager --enable cr && sudo yum install -y nginx-mod-http-passenger ; }

Step 4: restart Nginx

Now that the Passenger Nginx module is installed, restart Nginx to ensure that Passenger is activated:

$ sudo systemctl restart nginx

Step 5: check installation

After installation, please validate the install by running sudo /usr/bin/passenger-config validate-install. For example:

$ sudo /usr/bin/passenger-config validate-install
 * Checking whether this Phusion Passenger install is in PATH... ✓
 * Checking whether there are no other Phusion Passenger installations... ✓

All checks should pass. If any of the checks do not pass, please follow the suggestions on screen.

Finally, check whether Nginx has started the Passenger core processes. Run sudo /usr/sbin/passenger-memory-stats. You should see Nginx processes as well as Passenger processes. For example:

$ sudo /usr/sbin/passenger-memory-stats
Version: 5.0.8
Date   : 2015-05-28 08:46:20 +0200
...

---------- Nginx processes ----------
PID    PPID   VMSize   Private  Name
-------------------------------------
12443  4814   60.8 MB  0.2 MB   nginx: master process /usr/sbin/nginx
12538  12443  64.9 MB  5.0 MB   nginx: worker process
### Processes: 3
### Total private dirty RSS: 5.56 MB

----- Passenger processes ------
PID    VMSize    Private   Name
--------------------------------
12517  83.2 MB   0.6 MB    PassengerAgent watchdog
12520  266.0 MB  3.4 MB    PassengerAgent server
12531  149.5 MB  1.4 MB    PassengerAgent logger
...

If you do not see any Nginx processes or Passenger processes, then you probably have some kind of installation problem or configuration problem. Please refer to the troubleshooting guide.

Step 6: update regularly

Nginx updates, Passenger updates and system updates are delivered through the YUM package manager regularly. You should run the following command regularly to keep them up to date:

$ sudo yum update

After an update, you should restart Nginx. Doing so will automatically restart Passenger too.

In May 2020, the CentOS 7 / RHEL 7 packages for Passenger were changed from a static to a dynamic module package. If you have the old package, please uninstall it first:
  • sudo yum remove nginx*

Step 1: enable EPEL

The instructions differ depending on whether you are on Red Hat or another Enterprise Linux. The second step is only necessary on Red Hat.

Step 1:
install EPEL package
Passenger requires EPEL.
$ sudo yum install -y yum-utils
$ sudo yum install -y https://dl.fedoraproject.org/pub/epel/epel-release-latest-$(< /etc/redhat-release tr -dc '0-9.'|cut -d \. -f1).noarch.rpm
$ sudo yum-config-manager --enable epel
$ sudo yum clean all && sudo yum update -y
Step 2 (RHEL only):
enable the 'optional' repository
Enable the optional repository (rhel-7-server-optional-rpms). This can be done by enabling the RHEL optional subchannel for RHN-Classic. For certificate-based subscriptions see Red Hat Subscription Management Guide. The following commands may be helpful, but are not thoroughly tested.
$ sudo subscription-manager register --username $RHN_USERNAME --password $RHN_PASSWORD --auto-attach
$ sudo subscription-manager repos --enable rhel-7-server-optional-rpms

Step 2: repair potential system issues

These commands will fix common issues that prevent yum from installing Passenger

# Ensure curl and nss/openssl are sufficiently up-to-date to talk to the repo
sudo yum update -y

date
# if the output of date is wrong, please follow these instructions to install ntp

sudo yum install -y ntp
sudo chkconfig ntpd on
sudo ntpdate pool.ntp.org
sudo service ntpd start


sudo yum -y install chrony
sudo systemctl enable chronyd
sudo firewall-cmd --permanent --add-service=ntp
sudo firewall-cmd --reload
sudo systemctl restart chronyd

Step 3: install Passenger packages

These commands will install Passenger dynamic Nginx module through Phusion's YUM repository.

If you want to use our packaged Nginx module, you must use your distro's provided Nginx package. If for example you have the repo provided by NGINX setup, you will instead need to compile a dynamic module compatible with that Nginx.

# Install various prerequisites
sudo yum install -y pygpgme curl

# Add our el7 YUM repository
sudo curl --fail -sSLo /etc/yum.repos.d/passenger.repo https://oss-binaries.phusionpassenger.com/yum/definitions/el-passenger.repo

# Install Passenger dynamic Nginx module
sudo yum module enable -y nginx:$(sudo yum module list nginx | cut -d ' ' -f 2 | grep -Ee '^[0-9\.]+$' | sort -V | tail -1)
sudo yum install -y nginx-mod-http-passenger || { sudo yum-config-manager --enable cr && sudo yum install -y nginx-mod-http-passenger ; }

Step 4: restart Nginx

Now that the Passenger Nginx module is installed, restart Nginx to ensure that Passenger is activated:

$ sudo systemctl restart nginx

Step 5: check installation

After installation, please validate the install by running sudo /usr/bin/passenger-config validate-install. For example:

$ sudo /usr/bin/passenger-config validate-install
 * Checking whether this Phusion Passenger install is in PATH... ✓
 * Checking whether there are no other Phusion Passenger installations... ✓

All checks should pass. If any of the checks do not pass, please follow the suggestions on screen.

Finally, check whether Nginx has started the Passenger core processes. Run sudo /usr/sbin/passenger-memory-stats. You should see Nginx processes as well as Passenger processes. For example:

$ sudo /usr/sbin/passenger-memory-stats
Version: 5.0.8
Date   : 2015-05-28 08:46:20 +0200
...

---------- Nginx processes ----------
PID    PPID   VMSize   Private  Name
-------------------------------------
12443  4814   60.8 MB  0.2 MB   nginx: master process /usr/sbin/nginx
12538  12443  64.9 MB  5.0 MB   nginx: worker process
### Processes: 3
### Total private dirty RSS: 5.56 MB

----- Passenger processes ------
PID    VMSize    Private   Name
--------------------------------
12517  83.2 MB   0.6 MB    PassengerAgent watchdog
12520  266.0 MB  3.4 MB    PassengerAgent server
12531  149.5 MB  1.4 MB    PassengerAgent logger
...

If you do not see any Nginx processes or Passenger processes, then you probably have some kind of installation problem or configuration problem. Please refer to the troubleshooting guide.

Step 6: update regularly

Nginx updates, Passenger updates and system updates are delivered through the YUM package manager regularly. You should run the following command regularly to keep them up to date:

$ sudo yum update

After an update, you should restart Nginx. Doing so will automatically restart Passenger too.

Before you begin: a note about Nginx

Before you begin, you should know that installing Passenger in its Nginx integration mode involves extending Nginx with code from Passenger. However, Nginx does not support loadable modules. This means that in order to install Passenger's Nginx integration mode, it is necessary to recompile Nginx from source. And that is exactly what we will do in this installation guide.

The fact that Nginx needs to be recompiled, has some implications:

  • Many users installed Nginx using their operating system's package manager (yum, apt-get, etc). This Nginx is usually located in /usr/sbin/nginx, with configuration file /etc/nginx/nginx.conf. However, if you install Nginx from source, then you will end up with another Nginx installation (that has Passenger enabled) that is located somewhere else. This other Nginx installation does not look for its /etc/nginx/nginx.conf, but somewhere else.

    Some people get confused by having two Nginx installations and end up editing the wrong config file. To avoid confusion, this guide will recommend you to uninstall the OS-installed Nginx before proceeding.

  • Init scripts, e.g. /etc/init.d/nginx and service nginx restart, are not provided by the default Nginx source code. Init scripts are actually extensions provided by the operating system's Nginx package. If you install Nginx from source, then you can't use init scripts to control Nginx anymore. Instead, you will use more generic operating system primitives to control Nginx, such as PID files and signals. Don't worry, this installation guide will teach you.

If you do not like having to recompile Nginx then there are several alternatives you can choose:

  1. Use the Phusion Passenger APT repository (for Debian, Ubuntu) or the YUM repository (RPMs for Enterprise Linux: Red Hat, CentOS, Rocky, Alma) to install Passenger and Nginx. Through our APT/YUM repository, we provide a Passenger-enabled Nginx package that uses the same structure as the Nginx package provided by the OS. This means that you will be able to use the service script, your config files are at places where you expect them, etc.
  2. Consider using Passenger Standalone in a reverse proxy configuration to Nginx. Passenger Standalone + reverse proxy is fully supported and supports the same features as Passenger's Nginx integration mode.

If you understand this and choose to use Passenger with its Nginx integration mode, then read on. :-)

Installation

Step 1: install gem

Install the Passenger gem with:

$ gem install passenger --no-rdoc --no-ri

The --no-rdoc --no-ri argument isn't really necessary, but it makes installation faster by skipping generation of API documentation.

Did gem install abort with a "permission denied" error? Then re-run it with rvmsudo.

Since you are using RVM, don't use sudo! Always use rvmsudo instead when executing Ruby-related commands! Learn more about rvmsudo at the RVM website.

Step 2 (optional): uninstall the OS-installed Nginx

As explained earlier in the introductory notes, you are about to install a new Nginx installation from source. If you already installed Nginx before, using the operating system's package manager, then we recommend that you uninstall that in order to avoid possible confusion caused by having multiple parallel Nginx installations. Of course, you don't have to remove the OS-installed version as long as you know what you're doing.

Here are some examples of how you can uninstall the OS-installed version:

Debian, Ubuntu
sudo apt-get purge nginx nginx-full nginx-light nginx-naxsi nginx-common
sudo rm -rf /etc/nginx
Red Hat, CentOS, Rocky, Alma, Fedora, Scientific Linux, Amazon Linux
sudo yum remove nginx
sudo rm -rf /etc/nginx

Step 3: run the Passenger Nginx module installer

Run the Passenger Nginx module installer and follow the on-screen instructions:

$ passenger-install-nginx-module

Step 4: validate installation

After installation, please validate the install by running rvmsudo passenger-config validate-install. For example:

$ rvmsudo passenger-config validate-install
 * Checking whether this Phusion Passenger install is in PATH... ✓
 * Checking whether there are no other Phusion Passenger installations... ✓

All checks should pass. If any of the checks do not pass, please follow the suggestions on screen.

Finally, check whether Nginx has started the Passenger core processes. Run rvmsudo passenger-memory-stats. You should see Nginx processes as well as Passenger processes. For example:

$ rvmsudo passenger-memory-stats
Version: 5.0.8
Date   : 2015-05-28 08:46:20 +0200
...

---------- Nginx processes ----------
PID    PPID   VMSize   Private  Name
-------------------------------------
12443  4814   60.8 MB  0.2 MB   nginx: master process /usr/sbin/nginx
12538  12443  64.9 MB  5.0 MB   nginx: worker process
### Processes: 3
### Total private dirty RSS: 5.56 MB

----- Passenger processes ------
PID    VMSize    Private   Name
--------------------------------
12517  83.2 MB   0.6 MB    PassengerAgent watchdog
12520  266.0 MB  3.4 MB    PassengerAgent server
12531  149.5 MB  1.4 MB    PassengerAgent logger
...

If you do not see any Nginx processes or Passenger processes, then you probably have some kind of installation problem or configuration problem. Please refer to the troubleshooting guide.

Using Nginx

As explained earlier in the introductory notes, you can't use an init script like /etc/init.d/nginx or service nginx restart. This section teaches you how to control and how to work with the Nginx you installed.

Remember that at some point, passenger-install-nginx-module asked you where to install Nginx to, and asked you for a "prefix", right? The prefix is the directory in which this new Nginx is installed. By default, the installer picks the directory /opt/nginx. In this section we will assume that you installed to the default prefix directory. If you specified a different prefix, simply substitute /opt/nginx with the actual directory.

File locations

Nginx's configuration files are then located in /opt/nginx/conf. Its log files are located in /opt/nginx/logs.

Starting Nginx

You can start Nginx by running:

$ sudo /opt/nginx/sbin/nginx

Shutting down Nginx

You can shut down Nginx by killing its PID with the kill command. To find out what Nginx's PID is, use the ps command. For example:

$ ps auxw | grep nginx
root     25817  0.0  0.1  43248  1172 ?        S    Jan01   0:00 nginx: master process /opt/nginx/sbin/nginx
www-data 25818  0.0  0.3  44240  3484 ?        S    Jan01   0:02 nginx: worker process

Here we see that the Nginx master process has PID 25817 (you can ignore the worker process), so we run:

$ sudo kill 25817

Having to perform two steps is a bit cumbersome. Luckily, there is an easier way to do this. By default, Nginx creates a PID file in /opt/nginx/logs/nginx.pid. This PID file contains Nginx's current PID. So we can use a single command to shutdown Nginx:

$ sudo kill $(cat /opt/nginx/logs/nginx.pid)

Restarting Nginx

Restarting Nginx is the same as shutting down Nginx, and starting it again. For example:

$ sudo kill $(cat /opt/nginx/logs/nginx.pid)
$ sudo /opt/nginx/sbin/nginx

FAQ

I have multiple Ruby versions or gemsets. Does it matter which one I use to install Passenger with?

Not really. Passenger doesn't care which Ruby you used to install it; it can still serve Ruby apps with any Ruby version, as long as you tell Passenger which Ruby interpreter you want to use.

You tell Passenger which Ruby interpreter to use for a specific app, by using the passenger_ruby directive. This can be customized on a per-application basis.

Please also read How having multiple Ruby interpreters affects Passenger. In particular, read the RVM-related caveats.

How do I install Nginx with additional modules?

You can install Passenger as a normal Nginx module.

The installer is interactive. How do I install in an automated, non-interactive manner?

Please refer to Non-interactive, automatic, headless installs or upgrades.

Some of the dependent libraries are installed in non-standard locations. How do I allow the compiler to find them?

Please refer to Customizing the compilation process.

How do I pass additional flags to the compiler?

Please refer to Customizing the compilation process.

Before you begin: a note about Nginx

Before you begin, you should know that installing Passenger in its Nginx integration mode involves extending Nginx with code from Passenger. However, Nginx does not support loadable modules. This means that in order to install Passenger's Nginx integration mode, it is necessary to recompile Nginx from source. And that is exactly what we will do in this installation guide.

The fact that Nginx needs to be recompiled, has some implications:

  • Many users installed Nginx using their operating system's package manager (yum, apt-get, etc). This Nginx is usually located in /usr/sbin/nginx, with configuration file /etc/nginx/nginx.conf. However, if you install Nginx from source, then you will end up with another Nginx installation (that has Passenger enabled) that is located somewhere else. This other Nginx installation does not look for its /etc/nginx/nginx.conf, but somewhere else.

    Some people get confused by having two Nginx installations and end up editing the wrong config file. To avoid confusion, this guide will recommend you to uninstall the OS-installed Nginx before proceeding.

  • Init scripts, e.g. /etc/init.d/nginx and service nginx restart, are not provided by the default Nginx source code. Init scripts are actually extensions provided by the operating system's Nginx package. If you install Nginx from source, then you can't use init scripts to control Nginx anymore. Instead, you will use more generic operating system primitives to control Nginx, such as PID files and signals. Don't worry, this installation guide will teach you.

If you do not like having to recompile Nginx then there are several alternatives you can choose:

  1. Use the Phusion Passenger APT repository (for Debian, Ubuntu) or the YUM repository (RPMs for Enterprise Linux: Red Hat, CentOS, Rocky, Alma) to install Passenger and Nginx. Through our APT/YUM repository, we provide a Passenger-enabled Nginx package that uses the same structure as the Nginx package provided by the OS. This means that you will be able to use the service script, your config files are at places where you expect them, etc.
  2. Consider using Passenger Standalone in a reverse proxy configuration to Nginx. Passenger Standalone + reverse proxy is fully supported and supports the same features as Passenger's Nginx integration mode.

If you understand this and choose to use Passenger with its Nginx integration mode, then read on. :-)

Installation

Step 1: install gem

Install the Passenger gem with:

$ gem install passenger --no-rdoc --no-ri

The --no-rdoc --no-ri argument isn't really necessary, but it makes installation faster by skipping generation of API documentation.

Did gem install abort with a "permission denied" error? Then re-run it with sudo.

Step 2 (optional): uninstall the OS-installed Nginx

As explained earlier in the introductory notes, you are about to install a new Nginx installation from source. If you already installed Nginx before, using the operating system's package manager, then we recommend that you uninstall that in order to avoid possible confusion caused by having multiple parallel Nginx installations. Of course, you don't have to remove the OS-installed version as long as you know what you're doing.

Here are some examples of how you can uninstall the OS-installed version:

Debian, Ubuntu
sudo apt-get purge nginx nginx-full nginx-light nginx-naxsi nginx-common
sudo rm -rf /etc/nginx
Red Hat, CentOS, Rocky, Alma, Fedora, Scientific Linux, Amazon Linux
sudo yum remove nginx
sudo rm -rf /etc/nginx

Step 3: run the Passenger Nginx module installer

Run the Passenger Nginx module installer and follow the on-screen instructions:

$ passenger-install-nginx-module

Step 4: validate installation

After installation, please validate the install by running sudo passenger-config validate-install. For example:

$ sudo passenger-config validate-install
 * Checking whether this Phusion Passenger install is in PATH... ✓
 * Checking whether there are no other Phusion Passenger installations... ✓

All checks should pass. If any of the checks do not pass, please follow the suggestions on screen.

Finally, check whether Nginx has started the Passenger core processes. Run sudo passenger-memory-stats. You should see Nginx processes as well as Passenger processes. For example:

$ sudo passenger-memory-stats
Version: 5.0.8
Date   : 2015-05-28 08:46:20 +0200
...

---------- Nginx processes ----------
PID    PPID   VMSize   Private  Name
-------------------------------------
12443  4814   60.8 MB  0.2 MB   nginx: master process /usr/sbin/nginx
12538  12443  64.9 MB  5.0 MB   nginx: worker process
### Processes: 3
### Total private dirty RSS: 5.56 MB

----- Passenger processes ------
PID    VMSize    Private   Name
--------------------------------
12517  83.2 MB   0.6 MB    PassengerAgent watchdog
12520  266.0 MB  3.4 MB    PassengerAgent server
12531  149.5 MB  1.4 MB    PassengerAgent logger
...

If you do not see any Nginx processes or Passenger processes, then you probably have some kind of installation problem or configuration problem. Please refer to the troubleshooting guide.

Using Nginx

As explained earlier in the introductory notes, you can't use an init script like /etc/init.d/nginx or service nginx restart. This section teaches you how to control and how to work with the Nginx you installed.

Remember that at some point, passenger-install-nginx-module asked you where to install Nginx to, and asked you for a "prefix", right? The prefix is the directory in which this new Nginx is installed. By default, the installer picks the directory /opt/nginx. In this section we will assume that you installed to the default prefix directory. If you specified a different prefix, simply substitute /opt/nginx with the actual directory.

File locations

Nginx's configuration files are then located in /opt/nginx/conf. Its log files are located in /opt/nginx/logs.

Starting Nginx

You can start Nginx by running:

$ sudo /opt/nginx/sbin/nginx

Shutting down Nginx

You can shut down Nginx by killing its PID with the kill command. To find out what Nginx's PID is, use the ps command. For example:

$ ps auxw | grep nginx
root     25817  0.0  0.1  43248  1172 ?        S    Jan01   0:00 nginx: master process /opt/nginx/sbin/nginx
www-data 25818  0.0  0.3  44240  3484 ?        S    Jan01   0:02 nginx: worker process

Here we see that the Nginx master process has PID 25817 (you can ignore the worker process), so we run:

$ sudo kill 25817

Having to perform two steps is a bit cumbersome. Luckily, there is an easier way to do this. By default, Nginx creates a PID file in /opt/nginx/logs/nginx.pid. This PID file contains Nginx's current PID. So we can use a single command to shutdown Nginx:

$ sudo kill $(cat /opt/nginx/logs/nginx.pid)

Restarting Nginx

Restarting Nginx is the same as shutting down Nginx, and starting it again. For example:

$ sudo kill $(cat /opt/nginx/logs/nginx.pid)
$ sudo /opt/nginx/sbin/nginx

FAQ

How do I install Nginx with additional modules?

You can install Passenger as a normal Nginx module.

The installer is interactive. How do I install in an automated, non-interactive manner?

Please refer to Non-interactive, automatic, headless installs or upgrades.

Some of the dependent libraries are installed in non-standard locations. How do I allow the compiler to find them?

Please refer to Customizing the compilation process.

How do I pass additional flags to the compiler?

Please refer to Customizing the compilation process.

Before you begin: a note about Nginx

Before you begin, you should know that installing Passenger in its Nginx integration mode involves extending Nginx with code from Passenger. However, Nginx does not support loadable modules. This means that in order to install Passenger's Nginx integration mode, it is necessary to recompile Nginx from source. And that is exactly what we will do in this installation guide.

The fact that Nginx needs to be recompiled, has some implications:

  • Many users installed Nginx using their operating system's package manager (yum, apt-get, etc). This Nginx is usually located in /usr/sbin/nginx, with configuration file /etc/nginx/nginx.conf. However, if you install Nginx from source, then you will end up with another Nginx installation (that has Passenger enabled) that is located somewhere else. This other Nginx installation does not look for its /etc/nginx/nginx.conf, but somewhere else.

    Some people get confused by having two Nginx installations and end up editing the wrong config file. To avoid confusion, this guide will recommend you to uninstall the OS-installed Nginx before proceeding.

  • Init scripts, e.g. /etc/init.d/nginx and service nginx restart, are not provided by the default Nginx source code. Init scripts are actually extensions provided by the operating system's Nginx package. If you install Nginx from source, then you can't use init scripts to control Nginx anymore. Instead, you will use more generic operating system primitives to control Nginx, such as PID files and signals. Don't worry, this installation guide will teach you.

If you do not like having to recompile Nginx then there are several alternatives you can choose:

  1. Use the Phusion Passenger APT repository (for Debian, Ubuntu) or the YUM repository (RPMs for Enterprise Linux: Red Hat, CentOS, Rocky, Alma) to install Passenger and Nginx. Through our APT/YUM repository, we provide a Passenger-enabled Nginx package that uses the same structure as the Nginx package provided by the OS. This means that you will be able to use the service script, your config files are at places where you expect them, etc.
  2. Consider using Passenger Standalone in a reverse proxy configuration to Nginx. Passenger Standalone + reverse proxy is fully supported and supports the same features as Passenger's Nginx integration mode.

If you understand this and choose to use Passenger with its Nginx integration mode, then read on. :-)

Installation

Step 1: download and extract tarball

Download the latest Passenger source tarball.

Download tarball

Extract the tarball to some place permanent. Replace X.X.X with the Passenger version, and /somewhere-permanent with the actual directory path that you want to extract to. /opt is usually a good directory.

$ tar -xzvf passenger-X.X.X.tar.gz -C /somewhere-permanent

Step 2: install Ruby

Is Ruby already installed? Then skip to the next step.

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 Passenger. Passenger's dependency on Ruby is very minimal. See Lightweight Ruby dependency for details.

Debian, Ubuntu
sudo apt-get update
sudo apt-get install -y ruby rake
Red Hat, CentOS, Rocky, Alma, Fedora, Scientific Linux, Amazon Linux Enable EPEL, then run as root:
yum install -y ruby rubygem-rake
Arch Linux
sudo pacman -S ruby
macOS No action needed. Ruby is installed by default.
Other operating systems Install Ruby from the Ruby website.

Step 3 (optional): uninstall the OS-installed Nginx

As explained earlier in the introductory notes, you are about to install a new Nginx installation from source. If you already installed Nginx before, using the operating system's package manager, then we recommend that you uninstall that in order to avoid possible confusion caused by having multiple parallel Nginx installations. Of course, you don't have to remove the OS-installed version as long as you know what you're doing.

Here are some examples of how you can uninstall the OS-installed version:

Debian, Ubuntu
sudo apt-get purge nginx nginx-full nginx-light nginx-naxsi nginx-common
sudo rm -rf /etc/nginx
Red Hat, CentOS, Rocky, Alma, Fedora, Scientific Linux, Amazon Linux
sudo yum remove nginx
sudo rm -rf /etc/nginx

Step 4: add Passenger to PATH

Add the Passenger bin directory to your PATH, so that your shell can locate the Passenger commands.

Open your shell's system-wide startup file. If you're using bash, this is usually /etc/bashrc or /etc/bash.bashrc. Inside that file, add this to the end:

PATH=/somewhere-permanent/passenger-X.X.X/bin:$PATH
export PATH

Again, replace X.X.X with the Passenger version, and /somewhere-permanent with the actual directory path.

When you're done, restart all your shells so that your new PATH takes effect.

Make sure your bashrc is actually included by your bash profile, which might not be the case if you created the user with useradd instead of adduser for example.

Step 5: run the Passenger Nginx module installer

Run the Passenger Nginx module installer and follow the on-screen instructions:

$ passenger-install-nginx-module

Step 6: validate installation

After installation, please validate the install by running sudo passenger-config validate-install. For example:

$ sudo passenger-config validate-install
 * Checking whether this Phusion Passenger install is in PATH... ✓
 * Checking whether there are no other Phusion Passenger installations... ✓

All checks should pass. If any of the checks do not pass, please follow the suggestions on screen.

Finally, check whether Nginx has started the Passenger core processes. Run sudo passenger-memory-stats. You should see Nginx processes as well as Passenger processes. For example:

$ sudo passenger-memory-stats
Version: 5.0.8
Date   : 2015-05-28 08:46:20 +0200
...

---------- Nginx processes ----------
PID    PPID   VMSize   Private  Name
-------------------------------------
12443  4814   60.8 MB  0.2 MB   nginx: master process /usr/sbin/nginx
12538  12443  64.9 MB  5.0 MB   nginx: worker process
### Processes: 3
### Total private dirty RSS: 5.56 MB

----- Passenger processes ------
PID    VMSize    Private   Name
--------------------------------
12517  83.2 MB   0.6 MB    PassengerAgent watchdog
12520  266.0 MB  3.4 MB    PassengerAgent server
12531  149.5 MB  1.4 MB    PassengerAgent logger
...

If you do not see any Nginx processes or Passenger processes, then you probably have some kind of installation problem or configuration problem. Please refer to the troubleshooting guide.

Using Nginx

As explained earlier in the introductory notes, you can't use an init script like /etc/init.d/nginx or service nginx restart. This section teaches you how to control and how to work with the Nginx you installed.

Remember that at some point, passenger-install-nginx-module asked you where to install Nginx to, and asked you for a "prefix", right? The prefix is the directory in which this new Nginx is installed. By default, the installer picks the directory /opt/nginx. In this section we will assume that you installed to the default prefix directory. If you specified a different prefix, simply substitute /opt/nginx with the actual directory.

File locations

Nginx's configuration files are then located in /opt/nginx/conf. Its log files are located in /opt/nginx/logs.

Starting Nginx

You can start Nginx by running:

$ sudo /opt/nginx/sbin/nginx

Shutting down Nginx

You can shut down Nginx by killing its PID with the kill command. To find out what Nginx's PID is, use the ps command. For example:

$ ps auxw | grep nginx
root     25817  0.0  0.1  43248  1172 ?        S    Jan01   0:00 nginx: master process /opt/nginx/sbin/nginx
www-data 25818  0.0  0.3  44240  3484 ?        S    Jan01   0:02 nginx: worker process

Here we see that the Nginx master process has PID 25817 (you can ignore the worker process), so we run:

$ sudo kill 25817

Having to perform two steps is a bit cumbersome. Luckily, there is an easier way to do this. By default, Nginx creates a PID file in /opt/nginx/logs/nginx.pid. This PID file contains Nginx's current PID. So we can use a single command to shutdown Nginx:

$ sudo kill $(cat /opt/nginx/logs/nginx.pid)

Restarting Nginx

Restarting Nginx is the same as shutting down Nginx, and starting it again. For example:

$ sudo kill $(cat /opt/nginx/logs/nginx.pid)
$ sudo /opt/nginx/sbin/nginx

FAQ

How do I install Nginx with additional modules?

You can install Passenger as a normal Nginx module.

The installer is interactive. How do I install in an automated, non-interactive manner?

Please refer to Non-interactive, automatic, headless installs or upgrades.

Some of the dependent libraries are installed in non-standard locations. How do I allow the compiler to find them?

Please refer to Customizing the compilation process.

How do I pass additional flags to the compiler?

Please refer to Customizing the compilation process.

Next step: Deploying your app

Continue
light mode dark mode
Passenger 6 Passenger 6