The first in a series of Nginx posts. The information here is heavily inspired from my reading of Clément Nedelcu’s excellent book Nginx HTTP Server and can be considered as my own personal reference.

There are five main steps involved in installing Nginx, as outlined below:

  1. Install dependencies
  2. Download
  3. Configure
  4. Compile
  5. Install

Nginx should be compiled from source, because:

  1. It may not be available in the enabled repositories of your Linux distro,
  2. Even if it is, it’s often an outdated version, and
  3. certain options and flags can only be configured at compile time.

1. Install dependencies

Nginx dependencies vary, according to the modules you require. Core dependencies include:

GNU Compiler Collection (GCC)

Nginx is written in C, so we need a C compiler.

It’s quite likely that you already have GCC installed on your system. Test if gcc is installed:

$ gcc

Success: gcc: no input files
Failure: gcc: command not found

To install it:

$ apt-get install build-essential

Perl Compatible Regular Expression (PCRE)

The Rewrite and HTTP Core modules need PCRE for parsing their regular expressions. We need to install both the library and its source: pcre and pcre-devel:

To install it:

$ apt-get install libpcre3 libpcre3-dev

zlib

The zlib library contains compression algorithms and is required in Nginx for gzip compression. Like PCRE, we need both the library and its source.

To install it:

$ apt-get install zlib1g zlib1g-dev

OpenSSL

Nginx relies on OpenSSL to serve secure pages.

To install it:

$ apt-get install openssl libssl-dev

2. Download

Nginx has three main branches: stable, mainline and legacy. It’s generally fine to use the mainline branch.

Download and extract Nginx onto a directory of your choice:

$ wget http://nginx.org/download/nginx-1.9.2.tar.gz
$ tar zxf nginx-1.9.2.tar.gz

3. Configure

The configuration process consists of appending switches to the ./configure command. Some of these options affect the project binaries and cannot be changed post-compilation.

objs/autoconf.err contains configuration error logs.

Below is a brief overview of the available configuration switches.

Path Options

Configuration that tells Nginx where to put things.

--prefix=

Default: /usr/local/nginx

Specify an absolute path on which to install Nginx to. If a relative path is specified, it will be taken as relative to /usr/local/nginx.

Paths can also be specified for the Nginx binary (--sbin-path=), the main configuration file (--conf-path=), the pid file1 (--pid-path=), the lock file2 (--lock-path=), fallback log files (--http-log-path=, --error-log-path=), as well as paths where Nginx should look for its dependencies.

Since the default --prefix path does not include a version number, upgrading Nginx will override the existing directory. It is recommended to override --prefix to include a version number, like this: --prefix=/usr/local/nginx-1.9.2, then create a symbolic link /usr/local/nginx to point to the latest versioned Nginx folder.

Make sure the path specified by --prefix= exists and is read/writable by the user running the configuration and compilation.

Prerequisites Options

Configuration that tells Nginx where to look for dependencies and how to build them. You will need to configure this if you install dependencies in non-standard locations.

For example, to configure an alternative path for the C compiler: --with-cc=, or to specify options for building zlib: --with-zlib-opt=.

Module Options

Configuration that tells Nginx which modules to include and exclude. Nginx has a modular architecture, which allows you to pick which functionalities you need easily.

Here, I split Nginx modules by whether they are enabled or disabled by default.

Modules Enabled By Default

To disable these modules, the switch is of the syntax --without-http_<MODULE_NAME>_module, for example --without-http_rewrite_module.

  • Access (access)
    • “The ngx_http_access_module module allows limiting access to certain client addresses.”
  • Basic Authentication (auth_basic)
    • “The ngx_http_auth_basic_module module allows limiting access to resources by validating the user name and password using the “HTTP Basic Authentication” protocol.”
  • Automatic Index (autoindex)
    • “The ngx_http_autoindex_module module processes requests ending with the slash character (‘/’) and produces a directory listing.”
  • Browser (browser)
    • “The ngx_http_browser_module module creates variables whose values depend on the value of the “User-Agent” request header field.”
  • Charset (charset)
    • “The ngx_http_charset_module module adds the specified charset to the “Content-Type” response header field.”
  • Empty Gif (empty_gif)
    • “The ngx_http_empty_gif_module module emits single-pixel transparent GIF.”
  • FastCGI, uWSGI, SCGI (fastcgi, uwsgi, scgi)
    • “The ngx_http_fastcgi_module module allows passing requests to a FastCGI server.”
    • “The ngx_http_uwsgi_module module allows passing requests to a uwsgi server.”
    • “The ngx_http_scgi_module module allows passing requests to an SCGI server.”
  • Geo (geo)
    • “The ngx_http_geo_module module creates variables with values depending on the client IP address.”
  • Gzip (gzip)
    • “The ngx_http_gzip_module module is a filter that compresses responses using the “gzip” method.”
  • Headers (headers)
    • “The ngx_http_headers_module module allows adding the “Expires” and “Cache-Control” header fields, and arbitrary fields, to a response header.”
  • Limit Connections (limit_conn)
    • “The ngx_http_limit_conn_module module is used to limit the number of connections per the defined key, in particular, the number of connections from a single IP address.”
  • Limit Requests (limit_req)
    • “The ngx_http_limit_req_module module (0.7.21) is used to limit the request processing rate per a defined key, in particular, the processing rate of requests coming from a single IP address.”
  • Log (log)
    • “The ngx_http_log_module module writes request logs in the specified format.”
  • Map (map)
    • “The ngx_http_map_module module creates variables whose values depend on values of other variables.”
  • Memcached (memcached)
    • “The ngx_http_memcached_module module is used to obtain responses from a memcached server.”
  • Proxy (proxy)
    • “The ngx_http_proxy_module module allows passing requests to another server.”
  • Referer (referer)
    • “The ngx_http_referer_module module is used to block access to a site for requests with invalid values in the “Referer” header field.”
  • Rewrite (rewrite)
    • “The ngx_http_rewrite_module module is used to change request URI using regular expressions, return redirects, and conditionally select configurations.”
  • Split Clients (split_clients)
    • “The ngx_http_split_clients_module module creates variables suitable for A/B testing, also known as split testing.”
  • Server Side Include (SSI) (ssi)
    • “The ngx_http_ssi_module module is a filter that processes SSI (Server Side Includes) commands in responses passing through it.”
  • Upstream (upstream)
    • “The ngx_http_upstream_module module is used to define groups of servers that can be referenced by the proxy_pass, fastcgi_pass, uwsgi_pass, scgi_pass, and memcached_pass directives.”
  • User ID (userid)
    • “The ngx_http_userid_module module sets cookies suitable for client identification.”

Modules Disabled By Default

To enable these modules, the switch is of the syntax --with-http_<MODULE_NAME>_module, for example --with-http_xslt_module.

  • Addition (addition)
    • “The ngx_http_addition_module module is a filter that adds text before and after a response.”
  • Auth Request (auth_request)
    • “The ngx_http_auth_request_module module (1.5.4+) implements client authorization based on the result of a subrequest.”
  • WebDAV (dav)
    • “The ngx_http_dav_module module is intended for file management automation via the WebDAV protocol.”
  • FLV (flv)
    • “The ngx_http_flv_module module provides pseudo-streaming server-side support for Flash Video (FLV) files.”
  • GeoIP (geoip) (requires libgeoip library dependency)
    • “The ngx_http_geoip_module module (0.8.6+) creates variables with values depending on the client IP address, using the precompiled MaxMind databases.”
  • Gunzip (gunzip)
    • “The ngx_http_gunzip_module module is a filter that decompresses responses with “Content-Encoding: gzip” for clients that do not support “gzip” encoding method.”
  • Gzip Static (gzip_static)
    • “The ngx_http_gzip_static_module module allows sending precompressed files with the “.gz” filename extension instead of regular files.”
  • Image Filter (image_filter) (requires libgd library dependency)
    • “The ngx_http_image_filter_module module (0.7.54+) is a filter that transforms images in JPEG, GIF, and PNG formats.”
  • MP4 (mp4)
    • “The ngx_http_mp4_module module provides pseudo-streaming server-side support for MP4 files.”
  • Perl (perl)
    • “The ngx_http_perl_module module is used to implement location and variable handlers in Perl and insert Perl calls into SSI.”
  • Random Index (random_index)
    • “The ngx_http_random_index_module module processes requests ending with the slash character (‘/’) and picks a random file in a directory to serve as an index file.”
  • Real IP (realip)
    • “The ngx_http_realip_module module is used to change the client address to the one sent in the specified header field.”
  • Secure Link (secure_link)
    • +The ngx_http_secure_link_module module (0.7.18) is used to check authenticity of requested links, protect resources from unauthorized access, and limit link lifetime.
  • SPDY (SPDY)
    • “The ngx_http_spdy_module module provides experimental support for SPDY.”
  • SSL (ssl)
    • “The ngx_http_ssl_module module provides the necessary support for HTTPS.”
  • Stub Status (stub_status)
    • “The ngx_http_stub_status_module module provides access to basic status information.”
  • Substitution (sub)
    • “The ngx_http_sub_module module is a filter that modifies a response by replacing one specified string by another.”
  • XSLT (XSLT) (requires libxml2 and libxslt library dependencies)
    • “The ngx_http_xslt_module (0.7.8+) is a filter that transforms XML responses using one or more XSLT stylesheets.”

There are also third-party modules can be added on. --add-module=path will compile the module located at path into the binary.

Miscellaneous Options

There are some options that don’t fall in the above categories, mostly concerning mail server proxy or event management behavior.

The most notable options that fall under this category are --user= and --group=, which specifies the user and group for starting Nginx worker processes.

Running a ./configure --with-http_ssl_module --with-http_gzip_static_module produces some output that looks like this:

$ ./configure --with-http_ssl_module --with-http_gzip_static_module

checking for OS
 + Linux 3.13.0-52-generic x86_64
checking for C compiler ... found
 + using GNU C compiler
 + gcc version: 4.8.4 (Ubuntu 4.8.4-2ubuntu1~14.04)
checking for gcc -pipe switch ... found
checking for gcc builtin atomic operations ... found
checking for C99 variadic macros ... found

...(redacted)-...

Configuration summary
  + using system PCRE library
  + using system OpenSSL library
  + md5: using OpenSSL library
  + sha1: using OpenSSL library
  + using system zlib library

  nginx path prefix: "/usr/local/nginx"
  nginx binary file: "/usr/local/nginx/sbin/nginx"
  nginx configuration prefix: "/usr/local/nginx/conf"
  nginx configuration file: "/usr/local/nginx/conf/nginx.conf"
  nginx pid file: "/usr/local/nginx/logs/nginx.pid"
  nginx error log file: "/usr/local/nginx/logs/error.log"
  nginx http access log file: "/usr/local/nginx/logs/access.log"
  nginx http client request body temporary files: "client_body_temp"
  nginx http proxy temporary files: "proxy_temp"
  nginx http fastcgi temporary files: "fastcgi_temp"
  nginx http uwsgi temporary files: "uwsgi_temp"
  nginx http scgi temporary files: "scgi_temp"

4. Compile

Once the ./configure command is executed successfully, a makefile is generated in the same directory, which can be used to compile Nginx by running make:

$ make

Success: make[1]: leaving directory...

Any errors that occur here may be due to incorrect folder permissions or missing/too-recent/too-old dependencies.

5. Install

$ make install

The command will copy the compiled files as well as other resources to the installation directory specified by --prefix. This may require root privileges, depending on the folder permissions for /usr/local.

This step rarely presents problems.

Next, we will look at how to control the Nginx demon, oops I meant daemon.

Footnotes

  1. The pid file is a text file that contains the process ID. ↩

  2. The lock file allows other programs to check if Nginx is already running and prevent Nginx from being started more than once. ↩