Why can't Phusion Passenger extend my existing Nginx?

Note! This document is outdated. As of 2017 dynamic modules are available in Nginx.

You're probably reading this page because you ran passenger-install-nginx-module, and it warned you that it's about to install an entirely new Nginx installation, one that exists in parallel to your existing one. There's probably one big question in your mind:

"I already installed Nginx through my operating system, using apt-get or yum. Why can't Phusion Passenger use that?"

It's because Nginx does not support dynamically loadable modules. If you've ever used Apache (or indeed, almost any web server besides Nginx), then you're used to the fact that you can install add-ons for Apache, without having to reinstall Apache. Nginx can't do that. To extend Nginx with any kind of functionality, it has to be recompiled and reinstalled.

If you've ever installed an add-on module for Nginx, then you know that it involves the following steps:

1. Download the Nginx source code.
2. Run the configure script with --add-module parameters, like this: ./configure --prefix=/somewhere --add-module=/path-to-your-module
3. Run make && sudo make install to compile and install Nginx.

If you do that then you will install an entirely new Nginx installation to /somewhere. The passenger-install-nginx-module program is actually just an easy way to perform the above 3 steps for you. It does not extend your already-installed Nginx, because there's no way to do that.

Table of contents

• "Why did you guys do this? I just want to use my existing Nginx!"
• "Okay, I understand that my existing Nginx can't be extended. What now?"
  • Uninstall your existing Nginx
  • Using the newly installed Nginx
  • Starting Nginx
  • Shutting down Nginx
  • Restarting Nginx
  • Using an init script
• "But I don't want to recompile Nginx. Are there alternatives?"

"Why did you guys do this? I just want to use my existing Nginx!"

We -- the Phusion Passenger authors -- didn't choose to do this. We don't like this either.

Unfortunately, there is absolutely nothing that we can do to prevent the need to recompile/reinstall Nginx. This is a deliberate design decision made by the Nginx authors. We are very sorry.

However, if you're on Debian or Ubuntu, then you can use our Debian/Ubuntu APT packages. We provide Nginx packages that override the default Debian/Ubuntu Nginx packages, but our packages already have Phusion Passenger compiled in. By using our packages:

• You do not have to run passenger-install-nginx-module (which is just a convenient way to compile Nginx). Using apt-get will provide you with everything you need. You will not have to compile Nginx.
• Upgrades of both Phusion Passenger and Nginx are automatically taken care of.
• You will not end up with multiple Nginx installations. You will only have one.
• In general, everything will work exactly as you expect. Using our Debian/Ubuntu packages is strongly recommended.

If you're not using Debian/Ubuntu, read on.

"Okay, I understand that my existing Nginx can't be extended. What now?"

Use our APT packages if you can.

Otherwise, you should let passenger-install-nginx-module install Nginx for you. At some point, it 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. In this section, we'll teach you how to use that new Nginx.

If you don't want to recompile Nginx, then we have a solution for that as well. See the next section.

Uninstall your existing Nginx

Since passenger-install-nginx-module installs an entirely new Nginx installation for you, you'll end up with two Nginx binaries, two sets of Nginx configuration files, two sets of Nginx log files, etc. So to avoid confusion, you should uninstall the Nginx that you had installed via apt-get, yum, etc.

# Debian, Ubuntu:
sudo apt-get remove nginx nginx-full nginx-light nginx-naxsi nginx-common

# Red Hat, CentOS, Fedora, Amazon Linux:
sudo yum remove nginx

Using the newly installed Nginx

Suppose that you've told passenger-install-nginx-module that you want to install Nginx to the prefix /opt/nginx. Its 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

Nginx will immediately daemonize into the background.

Shutting down Nginx

You can shut down Nginx by killing its PID with the kill command. How do you know Nginx's PID? You can use the ps command, like this:

$ 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

Luckily, there's 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.

Using an init script

If you installed Nginx with apt-get or yum, then you were used to starting, stopping and restarting Nginx using an init script, like this:

sudo /etc/init.d/nginx start|stop|restart
sudo service nginx start|stop|restart

What happened to that? Where is the init script in this new installation?

Well, init scripts are actually operating system specific. Nginx does not supply an init script by itself. Instead, your operating system vendor did that, and bundled the init script along with their Nginx packages.

Fortunately, you can download existing init scripts and reuse them for the newly installed Nginx:

• Init script for Ubuntu 8.04-9.10
• Init script for Ubuntu 12.04 and later
• Init script for Red Hat, Fedora and CentOS

However, you must edit the init script and make sure that the paths inside the script are correct! In particular, you must ensure that the paths to the Nginx binary, to the PID file and to the configuration file must match the actual locations of your Nginx installation.

"But I don't want to recompile Nginx. Are there alternatives?"

Yes. Use Phusion Passenger's Standalone mode. Phusion Passenger Standalone is a standalone server. It does not extend Nginx so it does not need to recompile Nginx. It will therefore work perfectly with your existing Nginx installation.

When using Passenger Standalone, you are supposed to:

1. Start Passenger Standalone on a certain port or socket file.
2. Add reverse proxy rules to your Nginx configuration file, to forward requests to Passenger Standalone.

If you've ever used Unicorn and Puma, then using Passenger Standalone will be very familiar: usage is almost the same.

Please refer to section Installing Passenger Standalone behind Nginx in the Passenger Standalone manual.