Installation guide

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

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

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

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

Grab what you need. Mix and match.

# 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

Or every package we ship:

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

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

$ ls /etc/nginx/modules-enabled/

Nothing there? Create the symlink yourself:

# 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

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.

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

When nginx drops a new stable version, rebuilt modules are usually up within 24 hours. Each package is pinned to the exact nginx version it was built for, so apt won't let you run a module built for nginx 1.30.4 on nginx 1.30.5. It upgrades both together.

A standard upgrade is all you need:

$ sudo apt update && sudo apt upgrade

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.

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.