Setup

Installation guide

Three steps. Two minutes if you already have the nginx.org repo set up. Less if you're fast.

Step 0: nginx.org, not your distro

These modules are compiled against nginx.org packages. They won't load on the nginx that ships with Debian or Ubuntu. That's a different binary, different ABI, different everything.

Did a apt install nginx and called it a day? That's the distro version. Switch to nginx.org first, then come back.

Quick check: Run nginx -v. Something like nginx/1.30.x from nginx.org? You're good. nginx/1.18.0 or similar ancient version? That's the distro package. Time to switch.

Step 1: Add the Blendbyte repository

One-time setup per machine. Add the signing key and source list.

Add repository 
sudo install -d -m 0755 /etc/apt/keyrings

curl -fsSL https://apt.blendbyte.net/nginx/blendbyte-archive-keyring.gpg \
  | sudo tee /etc/apt/keyrings/blendbyte.gpg >/dev/null

echo "deb [signed-by=/etc/apt/keyrings/blendbyte.gpg] https://apt.blendbyte.net/nginx $(lsb_release -cs) main" \
  | sudo tee /etc/apt/sources.list.d/blendbyte.list

sudo apt update

Step 2: Install modules

Grab what you need. Mix and match.

Install modules 
# Install individual modules
sudo apt install nginx-module-brotli
sudo apt install nginx-module-geoip2
sudo apt install nginx-module-headers-more

# Or several at once
sudo apt install nginx-module-brotli nginx-module-geoip2 nginx-module-modsecurity

All available packages:

Install all modules 
sudo apt install \
  nginx-module-brotli \
  nginx-module-brotli-static \
  nginx-module-zstd \
  nginx-module-zstd-static \
  nginx-module-modsecurity \
  nginx-module-geoip2 \
  nginx-module-stream-geoip2 \
  nginx-module-headers-more \
  nginx-module-substitutions \
  nginx-module-cache-purge \
  nginx-module-fancyindex \
  nginx-module-dav-ext

Step 3: Enable the module

Most packages drop a config into /etc/nginx/modules-enabled/ on install and you're done. Quick check to be sure:

Check enabled modules 
$ ls /etc/nginx/modules-enabled/

Nothing there? Create the symlink yourself:

Enable module manually 
# Replace brotli with your module name
$ sudo ln -s /etc/nginx/modules-available/50-mod-brotli.conf \
  /etc/nginx/modules-enabled/

$ sudo nginx -t && sudo systemctl reload nginx

Pinning (recommended)

If you have multiple nginx module sources (nginx.org ships njs, otel, and a few others), pinning makes sure apt always picks ours for nginx-module-* packages without you having to think about it.

Pin Blendbyte packages 
cat <<EOF | sudo tee /etc/apt/preferences.d/blendbyte-nginx
Package: nginx-module-*
Pin: origin apt.blendbyte.net
Pin-Priority: 1001
EOF

Keeping modules up to date

When nginx drops a new stable version, rebuilt modules are usually up within 24 hours. The packages have ABI version constraints baked in, so apt won't let you run a module built for nginx 1.26 on nginx 1.28. It'll tell you to upgrade both at once.

A standard upgrade is all you need:

Update 
$ sudo apt update && sudo apt upgrade

Supported distros

All combinations of:

  • Debian Bookworm (12)
  • Debian Trixie (13)
  • Ubuntu 22.04 LTS (Jammy)
  • Ubuntu 24.04 LTS (Noble)
  • Ubuntu 26.04 LTS (Resolute Raccoon)

On both amd64 and arm64 architectures.

What's not included

Things that come up and why we don't ship them:

  • Lua: Just use OpenResty. Bolting the Lua module onto stock nginx is a world of hurt.
  • VTS: The nginx-prometheus-exporter sidecar does more and doesn't require patching nginx.
  • GeoIP v1: MaxMind killed those databases in 2018. Use GeoIP2.
  • PageSpeed: Google archived it in 2020. Let it go.
  • njs, otel, acme, image-filter, perl, xslt: These already come from the official nginx.org repo. Grab them there.
Got questions? Open an issue on GitHub. Bug reports get read. Good ones get fixed fast.