Getting Started with Nginx

In this article by the author, Valery Kholodkov, of the book, Nginx Essentials, we learn to start digging a bit deeper into Nginx, we will quickly go through most common distributions that contain prebuilt packages for Nginx.

Installing Nginx

Before you can dive 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.

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:

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:

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.

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 https://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:

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.

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.

Summary

Here, you learned how to install Nginx from a number of available sources, the structure of Nginx installation and the purpose of various files, the elements and structure of the Nginx configuration file, and how to create a minimal working Nginx configuration file. You also learned about some best practices for Nginx configuration.