Installing Nginx

Before you can pe into specific features of Nginx, you need to learn how to install Nginx on your system.

It is strongly recommended that you use prebuilt binary packages of Nginx if they are available in your distribution. This ensures best integration of Nginx with your system and reuse of best practices incorporated into the package by the package maintainer. Prebuilt binary packages of Nginx automatically maintain dependencies for you and package maintainers are usually fast to include security patches, so you don't get any complaints from security officers. In addition to that, the package usually provides a distribution-specific startup script, which doesn't come out of the box.

Refer to your distribution package directory to find out if you have a prebuilt package for Nginx. Prebuilt Nginx packages can also be found under the download link on the official Nginx.org site.

In this chapter, we will quickly go through most common distributions that contain prebuilt packages for Nginx.

Installing Nginx on Ubuntu

The Ubuntu Linux distribution contains a prebuilt package for Nginx. To install it, simply run the following command:

$ sudo apt-get install nginx

The preceding command will install all the required files on your system, including the logrotate script and service autorun scripts. The following table describes the Nginx installation layout that will be created after running this command as well as the purpose of the selected files and folders:

Note

Default virtual host files will be placed into /usr/share/nginx/html. Please keep in mind that this directory is only for the default virtual host. For deploying your web application, use folders recommended by Filesystem Hierarchy Standard (FHS).

Now you can start the Nginx service with the following command:

$ sudo service nginx start

This will start Nginx on your system.

Alternatives

The prebuilt Nginx package on Ubuntu has a number of alternatives. Each of them allows you to fine tune the Nginx installation for your system.

Installing Nginx on Red Hat Enterprise Linux or CentOS/Scientific Linux

Nginx is not provided out of the box in Red Hat Enterprise Linux or CentOS/Scientific Linux. Instead, we will use the Extra Packages for Enterprise Linux (EPEL) repository. EPEL is a repository that is maintained by Red Hat Enterprise Linux maintainers, but contains packages that are not a part of the main distribution for various reasons. You can read more about EPEL at https://fedoraproject.org/wiki/EPEL.

To enable EPEL, you need to download and install the repository configuration package:

• For RHEL or CentOS/SL 7, use the following link:

  http://download.fedoraproject.org/pub/epel/7/x86_64/repoview/epel-release.html

• For RHEL/CentOS/SL 6 use the following link:

  http://download.fedoraproject.org/pub/epel/6/i386/repoview/epel-release.html

• If you have a newer/older RHEL version, please take a look at the How can I use these extra packages? section in the original EPEL wiki at the following link:

  https://fedoraproject.org/wiki/EPEL

Now that you are ready to install Nginx, use the following command:

# yum install nginx

The preceding command will install all the required files on your system, including the logrotate script and service autorun scripts. The following table describes the Nginx installation layout that will be created after running this command and the purpose of the selected files and folders:

Note

Default virtual host files will be placed into /usr/share/nginx/html. Please keep in mind that this directory is only for the default virtual host. For deploying your web application, use folders recommended by FHS.

By default, the Nginx service will not autostart on system startup, so let's enable it. Refer to the following table for the commands corresponding to your CentOS version:

Installing Nginx from source files

Traditionally, Nginx is distributed in the source code. In order to install Nginx from the source code, you need to download and compile the source files on your system.

Note

It is not recommended that you install Nginx from the source code. Do this only if you have a good reason, such as the following scenarios:

• You are a software developer and want to debug or extend Nginx
• You feel confident enough to maintain your own package
• A package from your distribution is not good enough for you
• You want to fine-tune your Nginx binary

In either case, if you are planning to use this way of installing for real use, be prepared to sort out challenges such as dependency maintenance, distribution, and application of security patches.

In this section, we will be referring to the configuration script. Configuration script is a shell script similar to one generated by autoconf, which is required to properly configure the Nginx source code before it can be compiled. This configuration script has nothing to do with the Nginx configuration file that we will be discussing later.

Downloading the Nginx source files

The primary source for Nginx for an English-speaking audience is Nginx.org. Open http://nginx.org/en/download.html in your browser and choose the most recent stable version of Nginx. Download the chosen archive into a directory of your choice (/usr/local or /usr/src are common directories to use for compiling software):

$ wget -q http://nginx.org/download/nginx-1.7.9.tar.gz

Extract the files from the downloaded archive and change to the directory corresponding to the chosen version of Nginx:

$ tar xf nginx-1.7.9.tar.gz
$ cd nginx-1.7.9

To configure the source code, we need to run the ./configure script included in the archive:

$ ./configure
checking for OS
 + Linux 3.13.0-36-generic i686
checking for C compiler ... found
+ using GNU C compiler
[...]

This script will produce a lot of output and, if successful, will generate a Makefile file for the source files.

Notice that we showed the non-privileged user prompt $ instead of the root # in the previous command lines. You are encouraged to configure and compile software as a regular user and only install as root. This will prevent a lot of problems related to access restriction while working with the source code.

Troubleshooting

The troubleshooting step, although very simple, has a couple of common pitfalls. The basic installation of Nginx requires the presence of OpenSSL and Perl-compatible Regex (PCRE) developer packages in order to compile. If these packages are not properly installed or not installed in locations where the Nginx configuration script is able to locate them, the configuration step might fail.

Then, you have to choose between disabling the affected Nginx built-in modules (rewrite or SSL, installing required packages properly, or pointing the Nginx configuration script to the actual location of those packages if they are installed.

Building Nginx

You can build the source files now using the following command:

$ make

You'll see a lot of output on compilation. If build is successful, you can install the Nginx file on your system. Before doing that, make sure you escalate your privileges to the super user so that the installation script can install the necessary files into the system areas and assign necessary privileges. Once successful, run the make install command:

# make install

The preceding command will install all the necessary files on your system. The following table lists all locations of the Nginx files that will be created after running this command and their purposes:

Note

Unlike installations from prebuilt packages, installation from source files does not harness Nginx folders for the custom configuration files or virtual host configuration files. The main configuration file is also very simple in its nature. You have to take care of this yourself.

Nginx must be ready to use now. To start Nginx, change your working directory to the /usr/local/nginx directory and run the following command:

# sbin/nginx

This will start Nginx on your system with the default configuration.

Troubleshooting

This stage works flawlessly most of the time. A problem can occur in the following situations:

• You are using nonstandard system configuration. Try to play with the options in the configuration script in order to overcome the problem.
• You compiled in third-party modules and they are out of date or not maintained.

Switch off third-party modules that break your build or contact the developer for assistance.

Copying the source code configuration from prebuilt packages

Occasionally you might want to amend Nginx binary from a prebuilt packages with your own changes. In order to do that you need to reproduce the build tree that was used to compile Nginx binary for the prebuilt package.

But how would you know what version of Nginx and what configuration script options were used at the build time? Fortunately, Nginx has a solution for that. Just run the existing Nginx binary with the -V command-line option. Nginx will print the configure-time options. This is shown in the following:

$ /usr/sbin/nginx -V
nginx version: nginx/1.4.6 (Ubuntu)
built by gcc 4.8.2 (Ubuntu 4.8.2-19ubuntu1)
TLS SNI support enabled
configure arguments: --with-cc-opt='-g -O2 -fstack-protector --param=ssp-buffer-size=4 -Wformat -Werror=format-security -D_FORTIFY_SOURCE=2' --with-ld-opt='-Wl,-Bsymbolic-functions -Wl,-z,relro' …

Using the output of the preceding command, reproduce the entire build environment, including the Nginx source tree of the corresponding version and modules that were included into the build.

Note

Here, the output of the Nginx -V command is trimmed for simplicity. In reality, you will be able to see and copy the entire command line that was passed to the configuration script at the build time.

You might even want to reproduce the version of the compiler used in order to produce a binary-identical Nginx executable file (we will discuss this later when discussing how to troubleshoot crashes).

Once this is done, run the ./configure script of your Nginx source tree with options from the output of the -V option (with necessary alterations) and follow the remaining steps of the build procedure. You will get an altered Nginx executable on the objs/ folder of the source tree.

The structure of the Nginx installation

When Nginx is installed, we can quickly study the structure of the installation. This will help you to know your installation better and manage it more confidently.

For each installation method, we have a set of generic locations and default paths. Let's see what these default locations contain.

The Nginx configuration folder

This folder contains the main configuration file and a set of parameter files. The following table describes the purpose of each of the default parameter files:

The default virtual host folder

The default configuration contains references to this site as root. It is not recommended that you use this directory for real sites, as it is not a good practice for the Nginx folders hierarchy to contain the site hierarchy. Use this directory for testing purposes or for serving auxiliary files.

The virtual hosts configuration folder

This is the location of virtual host configuration files. The recommended structure of this folder is to have one file per virtual host in this folder or one folder per virtual host, containing all files related to this virtual host. In this way, you will always know which files were used and which are now being used, and what each of the files contain and which files can be purged.

The log folder

This is the location for Nginx log files. The default access log file and error log file will be written to this location. For installation from source files, it is not recommended that you use the default location /usr/local/nginx/logs for real sites. Instead, make sure all your log files are stored in the system log file location, such as /var/log/nginx, to provide better overview and management of your log files.

The temporary folder

Nginx uses temporary files for receiving large request bodies, and proxies large files from upstream. Files that are created for this purpose can be found in this folder.