Caching

Cache Purge

Flush the exact cache entry you want. Not the whole cache.

nginx-module-cache-purge

Install

Make sure you have the official nginx.org repository configured first. These packages require nginx from nginx.org, not the distro-bundled version.

Add the Blendbyte repository if you haven't already:

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

Then install this module:

$ sudo apt install nginx-module-cache-purge

Most modules auto-enable on install. If yours didn't, enable it manually:

$ sudo ln -s /etc/nginx/modules-available/50-mod-cache-purge.conf \
  /etc/nginx/modules-enabled/
$ sudo nginx -t && sudo systemctl reload nginx

What it does

Nginx's built-in caching is powerful but blunt: wait for TTL, or nuke everything. Cache Purge adds precision. Send a request to a purge endpoint and nginx immediately removes the matching cache entry. Nothing else touched. Works with both proxy_cache (reverse proxy) and fastcgi_cache (PHP-FPM). The typical pattern is a restricted purge endpoint that your CMS, deployment pipeline, or CDN webhook calls when content changes. Cache entries are matched by cache key, which usually maps directly to URL. Long TTLs with instant on-demand invalidation: that's the combination most caching setups actually want.

When to use it

Instantly invalidate CMS content on publish without flushing unrelated cache
Integrate with deployment pipelines to purge affected URLs on release
Use long TTLs with selective purge instead of short TTLs as a workaround
Cache invalidation APIs for headless CMS and Jamstack setups
Purge fastcgi_cache entries from PHP application hooks

Configuration

A starting-point configuration. Adjust to your setup.

proxy_cache_path /var/cache/nginx
                 levels=1:2
                 keys_zone=main_cache:10m
                 max_size=1g;

server {
  location / {
    proxy_cache       main_cache;
    proxy_cache_valid 200 7d;
    proxy_pass        http://backend;
  }

  # Purge endpoint (restrict by IP in production)
  location ~ /purge(/.*) {
    allow  127.0.0.1;
    deny   all;
    proxy_cache_purge main_cache "$scheme$request_method$host$1";
  }
}

Replacing a Sury package?

This module replaces libnginx-mod-http-cache-purge from the Sury nginx repository. The package declares Replaces and Conflicts so apt handles the swap automatically in one transaction.

# If you were using Sury, this upgrades in place:
sudo apt install nginx-module-cache-purge

See the full migration guide for the complete Sury-to-Blendbyte migration steps.

Upstream project

This module is packaged from the upstream open-source project. Bug reports about module behaviour (not packaging) should go upstream.

https://github.com/FRiCKLE/ngx_cache_purge ↗

← All modules