Chapter 2
Installation, Builds, and Platform Optimization

Every Nginx deployment starts with a crucial decision: what should you build, and how should you optimize for the unique demands of your infrastructure? In this chapter, we navigate the trade-offs between official packages and custom builds, reveal advanced options for module inclusion, and explore how to tune Nginx for peak performance on a variety of operating systems and deployment targets. Whether targeting bare metal, cloud instances, containers, or Windows, your journey to a rock-solid, optimized Nginx begins here.

2.1 Building from Source with Custom Modules

Obtaining the Nginx source code is the initial step when aiming to customize the server with a specific set of modules, whether standard or third-party. The recommended approach is to download the latest stable version from the official Nginx website or mirror repositories:

wget http://nginx.org/download/nginx-1.24.0.tar.gz
tar -zxvf nginx-1.24.0.tar.gz
cd nginx-1.24.0

Once the source tree is prepared, configuration precedes compilation. Nginx employs a modular architecture, where standard modules are often included by default but can be selectively enabled or disabled, while third-party modules require explicit inclusion. The ./configure script governs this process, accepting a multitude of options to shape the binary according to precise operational requirements.

Key configuration flags include:

• -prefix=PATH: Defines the installation directory, controlling where Nginx will reside post-build.
• -with-http_ssl_module: Enables the standard SSL/TLS module.
• -with-http_v2_module: Enables HTTP/2 support.
• -add-module=PATH: Incorporates a third-party module from the specified local directory.
• -without-MODULE: Explicitly disables any built-in module.

To illustrate the integration of a third-party module alongside standard modules, consider adding the ngx_brotli module for Brotli compression support. This necessitates cloning the module repository, ensuring it is placed adjacent or within the source directory, followed by configuration with -add-module. The exact steps are:

git clone https://github.com/google/ngx_brotli.git
cd ngx_brotli
git submodule update --init
cd ../nginx-1.24.0

./configure \
--prefix=/etc/nginx \
--with-http_ssl_module \
--with-http_v2_module \
--add-module=../ngx_brotli

The above configuration enables SSL, HTTP/2, and appends the Brotli module. The order of modules is significant if multiple third-party modules are added-place -add-module flags consecutively.

For a tailored build excluding certain default modules, use the -without-MODULE directive. For example, to exclude the mail proxy module, append:

--without-mail_pop3_module --without-mail_imap_module --without-mail_smtp_module

After configuration, compile using make, which invokes gcc with the defined options set during configuration. Compilation can be expedited by parallelizing jobs according to processor cores, e.g.:

make -j4

Successful compilation yields an Nginx binary in the objs directory. Installation is finalized by:

make install

This stage requires appropriate permissions; typically, root or sudo access is necessary when installing into system directories.

Verifying the build involves executing the compiled binary with the -V flag, which outputs the configuration arguments, activated modules, and other build options. For instance:

nginx version: nginx/1.24.0
built by gcc 10.2.1 20210110 (Red Hat 10.2.1-9)
built with OpenSSL 1.1.1k 25 Mar 2021
configure arguments: --prefix=/etc/nginx --with-http_ssl_module --with-http_v
2_module --add-module=../ngx_brotli
 

This output serves to confirm the presence of both standard and third-party modules as integrated during compilation.

When integrating multiple third-party modules, it is crucial to assess compatibility. Some modules rely on specific Nginx API versions or conflict due to overlapping functionality. Careful review of module documentation and, if necessary, patching of source code or adjustment of compile-time flags might be needed. Where patching is necessary, apply patches prior to configuration using standard patch utilities:

patch -p1 < module_fix.patch

Handling third-party modules hosted externally often requires maintenance vigilance to track upstream updates that may alter APIs or introduce new features. Automated build systems, such as Makefile or CMake wrappers, can streamline source retrieval and patch application.

Advanced configurations may also involve specifying optimization flags by setting environment variables before ./configure, for example:

export CFLAGS='-O2 -march=native'
./configure ...

This allows the generation of binaries optimized for the target processor architecture, enhancing runtime performance.

Once installed, manually configured modules may also require enabling in the Nginx configuration files. For instance, Brotli support needs to be activated by directives inside the http context:

brotli on;
brotli_comp_level 6;
brotli_types text/plain text/css application/javascript application/json application/xml+rss application/atom+xml image/svg+xml;

Thus, source-level integration and runtime configuration jointly govern module behavior to tailor server capabilities precisely.

Building Nginx from source with custom modules involves a deliberate sequence: download and prepare source, incorporate third-party modules by path during the ./configure invocation, selectively enable or disable built-in modules, compile with optimization flags as needed, install with appropriate privileges, and verify the active build configuration. Mastery of this procedure enables an adaptable Nginx installation optimized for security, performance, and extensibility tailored to the unique demands of complex server environments.

2.2 Official Packages vs. Custom Builds

In Linux system administration and software deployment, the choice between using official packages from distribution repositories and compiling software from source or custom builds plays a critical role in achieving desired levels of stability, flexibility, and security. Each approach embodies distinct philosophies and operational trade-offs, influencing update cadence, customization capacity, and risk exposure.

Official packages are pre-built binaries curated by Linux distribution maintainers. They are typically available through a package manager such as apt, yum, or pacman, which handles dependency resolution, installation, and updates in a centralized and consistent manner. The primary advantage of official packages originates from their integration within the distribution's ecosystem, enabling seamless compatibility and streamlined maintenance. Packages are generally vetted for security issues and tested against the specific runtime environments of the distribution's supported architectures. This vetting process mitigates the risk of introducing unstable or malicious software. The update cadence of these packages usually aligns with the distribution's release cycle, ranging from rolling-release models offering continuous updates to fixed-release models updating every six months or annually.

...