In this post I show you how to add support for the Brotli compression algorithm to Nginx on Ubuntu 16.04 (Xenial Xerus).

Unfortunately as of the time of writing this post Nginx does not come with built-in support for Brotli. So it needs to be built from source with an additional custom module.

The basics

I walk you through the steps one by one. First create a new working directory and switch to it.

mkdir /opt/nginx_custom_build
cd /opt/nginx_custom_build

Update the package index.

apt-get update

Install some necessary packages if you don't have them already.

apt-get install dpkg-dev build-essential git

Install necessary packages for building Nginx from source.

apt-get build-dep nginx

Download Nginx source files.

apt-get source nginx

You may see an error similar to the one below.

W: Can't drop privileges for downloading as file 'nginx_1.10.3-0ubuntu0.16.04.2.dsc' couldn't be accessed by user '_apt'. - pkgAcquire::Run (13: Permission denied)

If you see that error you can safely ignore it and continue.

Download the ngx_brotli module from GitHub. Note that we use the --recursive flag to git clone because the submodules are required as well.

git clone --recursive https://github.com/google/ngx_brotli.git

Now you should have some new files and directories like below.

• nginx-1.10.3 (directory)
• nginx_1.10.3-0ubuntu0.16.04.2.debian.tar.xz
• nginx_1.10.3-0ubuntu0.16.04.2.dsc
• nginx_1.10.3.orig.tar.gz
• ngx_brotli (directory)

Configure the build rules

There is a file in nginx-1.10.3/debian/rules. Open this file and find full_configure_flags. It should look like this:

full_configure_flags := \
    $(common_configure_flags) \
    --with-http_addition_module \
    --with-http_dav_module \
    --with-http_geoip_module \
    --with-http_gunzip_module \
    --with-http_gzip_static_module \
    --with-http_image_filter_module \
    --with-http_v2_module \
    --with-http_sub_module \
    --with-http_xslt_module \
    --with-stream \
    --with-stream_ssl_module \
    --with-mail \
    --with-mail_ssl_module \
    --with-threads \
    --add-module=$(MODULESDIR)/nginx-auth-pam \
    --add-module=$(MODULESDIR)/nginx-dav-ext-module \
    --add-module=$(MODULESDIR)/nginx-echo \
    --add-module=$(MODULESDIR)/nginx-upstream-fair \
    --add-module=$(MODULESDIR)/ngx_http_substitutions_filter_module

Add an extra new line there:

--add-module=/opt/nginx_custom_build/ngx_brotli

Note that the lines before the last line need to end with a backslash.

Now switch to the Nginx directory and build the ".deb" files. Be patient as this will take a while.

cd nginx-1.10.3/
dpkg-buildpackage -b

Install your custom build of Nginx

Switch back to the parent folder.

cd /opt/nginx_custom_build

You should see a bunch of ".deb" files in this folder. Now install Nginx using the command below.

dpkg --install \
nginx_1.10.3-0ubuntu0.16.04.2_all.deb \
nginx-full_1.10.3-0ubuntu0.16.04.2_amd64.deb \
nginx-common_1.10.3-0ubuntu0.16.04.2_all.deb

Now Nginx should be installed and running. Confirm everything is ok by running the following commands.

dpkg --list nginx nginx-full nginx-common
nginx -v
systemctl status nginx
nginx -V

nginx -V displays the configuration that nginx was built with. You must see

--add-module=/opt/nginx_custom_build/ngx_brotli

Hold Nginx upgrades

Now we should ensure that we are protected against the risk of an accidental upgrade to a newer release in the future.
Otherwise we could accidentally land up with a newer version of Nginx in the future that unlike our custom-built version would not have the Brotli module included and it would cause the server to crash.

Use apt-mark hold nginx to set the Nginx package on hold. You will see a confirmation like nginx set on hold.. You can also double check using apt-mark showhold.

You are done!

Congratulations your custom build of Nginx is now capable of handling Brotli compression.
In a future post I will show you how to configure Nginx correctly to use Brotli.