Our Life Together  >  Thoughts  >  Adding Brotli to an Already-built NGINX Instance  —  { code }

Do you have a running instance of NGINX and wanted to add Brotli compression? What if you don’t want to recompile a custom web server from source or replace your auto-updating repo-installed version? You can create dynamic Brotli modules which upgrade whenever NGINX does.

The bash script below explains the installation steps. Feel free to study and execute the codes step-by-step. That may help you troubleshoot any peculiarities in your system. Otherwise, simply run the script.

/usr/local/sbin/mkbrotli

You may choose to automate the installation by simply running the script above. In its default settings, it will process the version number you will pass to it. To get your NGINX’s version number run this command:


nginx -v
nginx version: nginx/1.17.1

Since the version number in this example is 1.17.1, after you have downloaded the bash script above, go to the directory where the script is and run these commands:


chmod +x mkbrotli
./mkbrotli 1.17.1

You may now chill and relax as the script automagically downloads, builds, and installs the dynamic modules for you. If the script runs through errors please let me know in the comments below so I may make adjustments to it.

Activating the modules

Now that we have the modules, there are two configuration steps needed to activate Brotli compression. First, load the modules in NGINX’s main configuration file (mine was at /etc/nginx/nginx.conf). You can get your config file path by running this command:


nginx -V 2>&1 | grep -o 'conf-path=[^ ]*' | sed 's/conf-path=//'

Now edit NGINX’s conf file. Outside any block { ... }, maybe on the top section of the file, add these lines:

nginx/nginx.conf

load_module modules/ngx_http_brotli_filter_module.so;
load_module modules/ngx_http_brotli_static_module.so;

# http {
#   ...
# }

Second, activate Brotli (and set its configuration directives, aka settings) either inside the http block of NGINX’s conf file, or the server block of your domain configs (e.g. files in nginx/sites-enabled/). As for me, I placed these directives in the nginx/snippets/ folder and called them via include in my domain configs.

nginx/nginx.conf
Auto-update with NGINX

One potential problem with dynamic modules is when NGINX automatically upgrades via a package manager (e.g. apt, yum, or pacman). If you’re like me, all upgrades in my server are automated by scripts. You see, dynamic modules are version-specific. NGINX is set not to load modules that were built for a different version. So how will Brotli modules automatically upgrade together with NGINX?

The answer is to hook on the package manager during upgrades. In apt this may be a two- or three-step process:

  1. Hook to apt and call a worker script. (Alternatively, the hook could directly call mkbrotli and thus skip the need for a worker script.)
  2. The worker script calls one or more build scripts to update the dynamic modules.
  3. Build scripts will build and install the new modules right before NGINX upgrades.

Here is my hook file in /etc/apt/apt.conf.d/:

/etc/apt/apt.conf.d/05nginxmodules

The worker script I use:

/usr/local/sbin/nginx-mod-preinstall

And finally the build script for this one is… (drum roll please)… of course mkbrotli. 😉 I hope that Brotli could be natively supported by NGINX in the future. It’s awesome. For now, we have this workaround. Enjoy the compression!

Google PageSpeed

Another project that aims to speed things up on the web is Google’s best-practices optimization called PageSpeed. I also made a Bash script to automate installation of PageSpeed on a running NGINX server. If you’re interested, check out this post: Adding PageSpeed to an Already-running NGINX Instance.

</>

Categories: Thoughts

Majal Mirasol

Servant of the Creator happily married to Jehovah’s slave girl.

While Majal was absorbed in training for a good foundation in the Maths and Sciences, he learned that there is more to life than simply elucidating complex designs in our universe. He realized that there is a Designer. The Source of our order, an order much superior than what our human brains could conceive.

6 Comments

Nigel · July 27, 2019 at 11:18 pm

I get this error on nginx test

module “/usr/share/nginx/modules/ngx_http_brotli_filter_module.so” is not binary compatible in /etc/nginx/nginx.conf

Any ideas?

    Majal Mirasol · July 28, 2019 at 5:49 pm

    Hi Nigel! We should supply to the script the same version of NGINX we are running. Have you checked via nginx -v? The warning will also show the version number the module was built for, and your running NGINX’s version number. Can you please post the full warning message here along with the mismatched version numbers?

      Lowi · August 8, 2019 at 10:13 pm

      Hi, thanks for the script. I get the same error and I’m sure I installed the correct version


      Sucessfully built Brotli for NGINX 1.14.0 in /usr/lib/nginx/modules

      ####################################################################

      $ nginx -t
      nginx: [emerg] module “/usr/share/nginx/modules/ngx_http_brotli_filter_module.so” is not binary compatible in /etc/nginx/nginx.conf test failed
      $ nginx -v
      nginx version: nginx/1.14.0 (Ubuntu)

        Majal Mirasol · August 8, 2019 at 10:21 pm

        That’s interesting… I’m pretty sure it works in my system. In fact it is running on this very website’s server. Hmmm… I’ll try to look more into this. Can you please supply more relevant details of your system? It may help us pinpoint and troubleshoot this issue. Thanks for the help!

        Looking again, I’d just like to confirm also that your test command should be: $ sudo nginx -t rather than $ nginx -t?

        Just guessing. Or the problem may be deeper than this… Thank you for your inputs! 🙂

Igor «InoY» Z. · August 8, 2019 at 7:45 pm

Thank you! I do not try this manual yet but it is exactly what I’ve been looking for!

Also I have a question: can I translate this manual to Russian? Of course with mention to you and links to your blog?

    Majal Mirasol · August 8, 2019 at 9:28 pm

    You’re welcome to do so Igor. I haven’t completed the Terms of Use for the site yet, but I’m planning that while others aspects of the site remains in copyright, the codes be released under GNU General Public License v3.0 copyleft. I love open source, and I’m happy to give back small contributions to make our world a better place. 🙂

Leave a comment