A quick installation guide

Since the mainline release (currently 1.11.19) has all of the latest features, you'll need to install it directly from the NGINX repositories. Thankfully, NGINX is kind enough to provide Red Hat Enterprise Linux (RHEL), CentOS, SUSE Linux Enterprise Server (SLES), Debian, and Ubuntu repositories, as well as OS X and Windows binaries.

Mainline versus stable

(source: https://nginx-com-uploads.s3.amazonaws.com/wp-content/uploads/2016/04/NGINX-1.11-mainline-1.10-stable.png)

The stable and mainline branches don't necessarily reflect system stability, but configuration and module integration stability. Unless you have third-party integration which requires the stable release, we highly recommend the mainline release.

How to do it...

Different Linux distributions have varying package managers, so we'll briefly cover the installation procedures for the more commonly used ones. If the distribution you use isn't covered here, refer to the official NGINX documentation for further guidance.

Packages – RHEL/CentOS

To install the latest NGINX release, add the NGINX mainline repository by adding the following to /etc/yum.repos.d/nginx.repo:

[nginx]
name=nginx repo
baseurl=http://nginx.org/packages/mainline/OS/OSRELEASE/$basearch/
gpgcheck=0
enabled=1

You'll also need to replace OS with either rhel or centos, and replace OSRELEASE with 5, 6, or 7, for your correct release.

You can check your version by running cat /etc/redhat-release.

Once you have the repository installed, refresh the packages and then install NGINX.

yum update
yum install nginx

If you have any issues, double check your repository for the correct syntax.

For further information, refer to the official documentation at http://nginx.org/en/linux_packages.html#mainline.

Packages – Debian/Ubuntu

First, download the NGINX signing key for the packages and install it:

wget http://nginx.org/keys/nginx_signing.key
apt-key add nginx_signing.key

Then, using your preferred Linux editor, we can add the sources to /etc/apt/sources.list.d/nginx.list:

deb http://nginx.org/packages/mainline/debian/ codename nginx
deb-src http://nginx.org/packages/mainline/debian/ codename nginx

Replace codename with the release name; for example, if you're using Debian 8, this will be set to jessie.

For Ubuntu-based systems, you'll need to use the following:

deb http://nginx.org/packages/mainline/ubuntu/ codename nginx
deb-src http://nginx.org/packages/mainline/ubuntu/ codename nginx

Replace codename with the release name; for example, if you're using Ubuntu 14.04, this will be set to trusty.

After adding the new source, we can then update the apt database and install NGINX:

apt-get update
apt-get install nginx

Installation should now be complete.

Compiling from scratch

Although having the precompiled packages is nice, not all of the modules are available out of the box. NGINX requires you to compile these into the NGINX installation and it's not a simple module like Apache.

You can simply build from source without any of the packaging tools for CentOS or Debian, however, it makes upgrades and compatibility more difficult. By default, user compiled programs will default to /usr/local, which means that any documentation which refers to the package defaults (/usr/etc) will be incorrect.

My preference is to base the build on the official package sources, rather than the plain source code. There aren't many extra steps involved, but it makes the ongoing management much easier. If you're looking for vanilla build instructions (without packages), these are easily available on the web.

These examples require you to have the mainline repositories already installed.

Debian/Ubuntu

On Ubuntu/Debian, install the required build tools:

apt-get install devscripts

This will install quite a few packages on your system, so if you're trying to keep your production environment lean, then I'd recommend that you use a separate build box to complete this.

We can now install the build prerequisites for NGINX:

apt-get build-dep nginx

Once you have the required build dependencies, we can now get a copy of the source code. Again, rather than the plain TAR file, we're going to get the packaged variant so that we can easily build them. Here's how we do it:

mkdir ~/nginxbuild
cd ~/nginxbuild
apt-get source nginx

You should now have a directory with the original TAR file, the Debian description, and any Debian specific patches. The apt-get source command will automatically extract and apply patches, as required, into a source directory.

To build without any changes, enter the directory and create the packages:

cd nginx-1.9.10/
fakeroot debian/rules binary

Compiling the code may take a while, depending on how many processors your workstation or server has. Once it has compiled, you should see two binaries in the parent (nginxbuild) directory. The resulting files should be:

• nginx-dbg_1.9.10-1~jessie_amd64.deb
• nginx_1.9.10-1~jessie_amd64.deb

You can now install NGINX via the newly compiled package:

sudo dpkg -i nginx_1.9.10-1~jessie_amd64.deb

CentOS/RHEL

Like the Debian build process, first we'll need to install the package build tools and the additional Extra Packages For Enterprise Linux (EPEL) repository:

sudo yum install yum-utils epel-release mock

Next, update /etc/yum.repos.d/nginx.repo and add the additional source repository:

[nginx-source]
name=nginx source repo
baseurl=http://nginx.org/packages/mainline/centos/7/SRPMS/
gpgcheck=0 
enabled=1 

In this example, we'll be using a CentOS 7-based release. Refer to the Packages – RHEL/CentOS section for how to modify it for other CentOS versions.

With the updated repository, we then create a directory for the build, and download the Source RPM (SRPM):

mkdir ~/nginxbuild
cd ~/nginxbuild
yumdownloader --source nginx

Next, download the required packages to complete the build:

yum-builddep nginx

Once all of the development packages have been downloaded, we can now extract the files from the SRPM:

rpm2cpio nginx-1.9.10-1.el7.ngx.src.rpm | cpio -idmv

Note that the name of your directory may vary based on the version of NGINX you have installed. For instance, here it is nginx-1.9.10 as I have installed NGINX 1.9.10.

You should see an output of the source files similar to this:

If we want to update the configuration and apply a patch or change one of the defaults, then this can simply be done by editing the files.

We can now rebuild these files from source using mock, which is a tool for building packages. The advantage of mock is that all of the development dependencies are contained within a chrooted environment, so it doesn't clutter your main installation. This chrooted environment can be cleaned and removed without any impact on the host system, which is great if you want repeatable builds.

To build, we run the following command:

mock --buildsrpm --spec ~/nginxbuild/nginx.spec --sources ~/nginxbuild

This generates the SRPMs, and they will be located in the /var/lib/mock/epel-7-x86_64/result directory, along with the associated log files. Now that we have a rebuilt SRPM, we can now compile it. Again, we're going to use mock so that everything is neatly contained:

mock --no-clean --rebuild var/lib/mock/epel-7-x86_64/result/nginx-1.9.11-1.el7.ngx.src.rpm

Depending on your processing power, this may take five minutes or more to complete. Once the build is complete, you should see the resultant binary RPM as well as a debug RPM in the /var/lib/mock/epel-7-x86_64 directory. Here's an example:

-rw-rw-r-- 1 demo mock 159K Feb 10 20:59 build.log
-rw-r--r-- 1 demo mock 889K Feb 10 20:57 nginx-1.9.11-1.el7.ngx.src.rpm
-rw-r--r-- 1 demo mock 803K Feb 10 20:59 nginx-1.9.11-1.el7.ngx.x86_64.rpm
-rw-r--r-- 1 demo mock 3.1M Feb 10 20:59 nginx-debuginfo-1.9.11-1.el7.ngx.x86_64.rpm
-rw-rw-r-- 1 demo mock 45K Feb 10 20:59 root.log
-rw-rw-r-- 1 demo mock 1000 Feb 10 20:59 state.log

Now that we have the new binary file, we can install it via yum:

sudo yum install /var/lib/mock/epel-7-x86_64/result/nginx-1.9.11-1. ngx.x86_64.rpm

It's preferable to use yum over rpm to install the packages, as it can also install any dependencies.

You should now have a fully installed NGINX installation, which you compiled from source.

Testing

Regardless of your installation method, once you have NGINX up and running, you should be able to browse to it via the IP address and/or Fully Qualified Domain Name (FQDN) and see something very similar to what is shown here:

Default NGINX page

To start, stop, and restart NGINX (if installed using official binaries), you can use the standard Linux init systems. There's a very slight variance between the different OS versions, so it's important to ensure you're using the correct command for the correct variant.

As Ubuntu switched to systemd as the default init system from 15.04, make sure you double check the version you're using.

How to do it...

Here's a quick reference table of the available commands:

Activity/OS	CentOS / RedHat 6	CentOS / RedHat 7	Ubuntu 14.04 / Debian 8
Start NGINX	service nginx start	systemctl start nginx	service nginx start
Stop NGINX	service nginx stop	systemctl stop nginx	service nginx stop
Restart NGINX	service nginx restart	systemctl restart nginx	service nginx restart
Reload NGINX	service nginx reload	N/A	N/A

Some modifications to NGINX will require a full restart, whereas others only need the configuration reloaded. In most instances where a configuration file has been modified, a reload is all which is required. NGINX will fork a new set of worker processes, allowing existing workers to complete and cleanly exit so that there is no downtime.

There's more...

We can check the NGINX configuration files after changes are made to ensure the syntax is correct. To do this, we run the following:

/usr/sbin/nginx -t

You should see the following if everything is correct:

nginx: the configuration file /etc/nginx/nginx.conf syntax is ok
nginx: configuration file /etc/nginx/nginx.conf test is successful

If you have any errors, double check your configuration for syntax errors on the lines indicated.