Thoughts on Software Engineering

Licensed under creative commons.
© Copyright 2017 Babak Mahmoudy.

Babak Mahmoudy

Thoughts on Software Engineering

Babak Mahmoudy

Thoughts on Software Engineering

How to add Brotli support to Nginx on Ubuntu 16.04


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.

Conflict warning

Before starting make sure you do not already have Nginx installed as this will cause conflicts.
Check using the following command: dpkg --list 'nginx*'

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


This package provides the development tools (including dpkg-source) required to unpack, build and upload Debian source packages.


This package contains a list of packages which are considered essential for building Debian packages.

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

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 an extra new line there:


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 \

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

in there.

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.