Dynamic Loading of the ngx_brotli Module in Nginx

Brotli is a widely used compression algorithm. We’ll configure it in Nginx and make it work.

Contents

• We assume you’re using Nginx 1.26.2 on a server running Debian 12.7.
• You can find related documentation at ngx_brotli and Nginx Docs.
• If you run into permission issues, prepend your commands with sudo. It’s not recommended to operate as the root user directly.

Setting Up the Development Environment

First, make sure you’ve the necessary development tools installed:

apt install build-essential git cmake

Next, install the required libraries:

apt install libpcre3-dev libssl-dev

Fetching the Source Code for Nginx and ngx_brotli

To keep things organized, create a dedicated folder in any directory:

mkdir -p Nginx/core Nginx/modules

In the core folder, run the following:

apt source nginx

This will download the Nginx source code to the current directory.

• You can delete any files except the nginx-1.26.2 folder.
• If you haven’t configured deb-src in the /etc/apt/sources.list.d/nginx.list file, you’ll encounter an error.

Next, in the modules folder, run the following to clone the ngx_brotli source code:

git clone --recurse-submodules -j8 https://github.com/google/ngx_brotli

This will download the ngx_brotli source code to the current directory.

Here’s the resulting directory structure:

Nginx
├── core
│   └── nginx-1.26.2
└── modules
    └── ngx_brotli

Building Nginx and ngx_brotli

In the ngx_brotli folder, run the following commands to build Brotli:

cd deps/brotli
mkdir out && cd out
cmake -DCMAKE_BUILD_TYPE=Release -DBUILD_SHARED_LIBS=OFF -DCMAKE_C_FLAGS="-Ofast -m64 -march=native -mtune=native -flto -funroll-loops -ffunction-sections -fdata-sections -Wl,--gc-sections" -DCMAKE_CXX_FLAGS="-Ofast -m64 -march=native -mtune=native -flto -funroll-loops -ffunction-sections -fdata-sections -Wl,--gc-sections" -DCMAKE_INSTALL_PREFIX=./installed ..
cmake --build . --config Release --target brotlienc

Next, in the nginx-1.26.2 folder, configure and build the module:

./configure conf-args --with-compat --add-dynamic-module=../../modules/ngx_brotli
make modules

Replace conf-args with the value of the configure arguments field from the output of nginx -V.

This will create the ngx_http_brotli_filter_module.so file in the Nginx/core/nginx-1.26.2/objs directory. Move this file to /usr/lib/nginx/modules/.

Configuration

To load the ngx_brotli module dynamically, edit your nginx.conf file (located at /etc/nginx/nginx.conf) and add the following at the top:

load_module modules/ngx_http_brotli_filter_module.so;

# ...

If this line is not placed at the top, you’ll encounter an emergency error.

Next, edit your server configuration file under /etc/nginx/conf.d/ to enable and configure Brotli:

server {
    # ...
    brotli on;
    brotli_comp_level 11;
    brotli_types text/css application/javascript;
    # ...
}

Brotli is enabled for text/html by default. If you redefine it, you’ll get a MIME warning.

Verifying the Configuration and Restarting Nginx

To check for any issues in your Nginx configuration, run the following:

nginx -t
# If everything is fine...
systemctl restart nginx