How to Fix NGINX Cache Purge on Debian 12 with Custom PHP-FPM Users

Olvy Cache Purger (Purge Nginx FastCGI Cache)

When running NGINX with caching on Debian 12, you may discover that cache purging doesn’t work if your PHP-FPM pool runs under a custom system user instead of the default www-data. This problem becomes very real in multi-tenant environments or whenever you separate applications into isolated users for security.

Contents

The Problem: Purge Fails with Default Setup

By default, Debian’s packaged NGINX plus the ngx_http_cache_purge module cannot properly purge cache entries if your PHP-FPM is not running as www-data. The reason is simple:

The NGINX cache directory (e.g., /var/cache/nginx/) belongs to www-data.
Purge requests routed via PHP-FPM running as another user (say myusername) cannot remove cache files, because of a permissions mismatch.
The purge appears to “fail silently” – often returning 404 Not Found instead of actually deleting cache entries.

In short: if your PHP-FPM pools run under custom users (a best practice), the stock Debian module just won’t cut it.

Before You Begin

This guide assumes that you already have NGINX installed and configured with a working cache (e.g. using proxy_cache_path or fastcgi_cache_path). The steps below focus only on adding purge functionality, so we won’t cover the initial cache configuration itself. If your NGINX is already caching responses successfully, you’re ready to proceed with building and enabling the purge module.

The Solution: Build the Cache Purge Module from Source

Debian provides official source packages that make it straightforward to rebuild additional modules. This ensures your compiled ngx_http_cache_purge_module matches the exact NGINX version and build flags shipped with Debian 12.

1. Enable Source Repositories

Make sure /etc/apt/sources.list includes deb-src entries. For Debian 12 (Bookworm), you should have lines like:

deb http://deb.debian.org/debian bookworm main
deb-src http://deb.debian.org/debian bookworm main

deb http://deb.debian.org/debian bookworm-updates main
deb-src http://deb.debian.org/debian bookworm-updates main

deb http://security.debian.org/debian-security bookworm-security main
deb-src http://security.debian.org/debian-security bookworm-security main

Update your package lists:

apt update

2. Install Build Dependencies

You’ll need development tools and the dependencies required to compile NGINX:

apt install dpkg-dev build-essential libpcre3-dev libssl-dev zlib1g-dev libxml2-dev libxslt1-dev libgd-dev libgeoip-dev libperl-dev

3. Fetch the NGINX Source

Download the NGINX source package:

apt source nginx

This will create a directory like nginx-1.22.1/ in your current working folder.

4. Download the Purge Module

Get the module source from GitHub:

wget https://github.com/torden/ngx_cache_purge/archive/refs/tags/v2.3.1.tar.gz

Unpack the module sources:

tar xzf v2.3.1.tar.gz

5. Build the Module

Go into the unpacked NGINX source directory and re-run the configure step with the same flags Debian uses, adding the purge module:

cd nginx-1.22.1

./configure --add-dynamic-module=../ngx_cache_purge-2.3.1 --with-cc-opt='-g -O2 -ffile-prefix-map=/build/nginx-nduIyd/nginx-1.22.1=. -fstack-protector-strong -Wformat -Werror=format-security -fPIC -Wdate-time -D_FORTIFY_SOURCE=2' --with-ld-opt='-Wl,-z,relro -Wl,-z,now -fPIC' --prefix=/usr/share/nginx --conf-path=/etc/nginx/nginx.conf --http-log-path=/var/log/nginx/access.log --error-log-path=stderr --lock-path=/var/lock/nginx.lock --pid-path=/run/nginx.pid --modules-path=/usr/lib/nginx/modules --http-client-body-temp-path=/var/lib/nginx/body --http-fastcgi-temp-path=/var/lib/nginx/fastcgi --http-proxy-temp-path=/var/lib/nginx/proxy --http-scgi-temp-path=/var/lib/nginx/scgi --http-uwsgi-temp-path=/var/lib/nginx/uwsgi --with-compat --with-debug --with-pcre-jit --with-http_ssl_module --with-http_stub_status_module --with-http_realip_module --with-http_auth_request_module --with-http_v2_module --with-http_dav_module --with-http_slice_module --with-threads --with-http_addition_module --with-http_flv_module --with-http_gunzip_module --with-http_gzip_static_module --with-http_mp4_module --with-http_random_index_module --with-http_secure_link_module --with-http_sub_module --with-mail_ssl_module --with-stream_ssl_module --with-stream_ssl_preread_module --with-stream_realip_module --with-http_geoip_module=dynamic --with-http_image_filter_module=dynamic --with-http_perl_module=dynamic --with-http_xslt_module=dynamic --with-mail=dynamic --with-stream=dynamic --with-stream_geoip_module=dynamic

When finished, you should have:

objs/ngx_http_cache_purge_module_custom.so

6. Install and Enable the Module

(a) Copy the compiled .so module to any Debian 12 machine with NGINX 1.22.1 installed, into the Debian modules directory, like:

/usr/lib/nginx/modules/ngx_http_cache_purge_module_custom.so

(b) Create configuration file:

/etc/nginx/modules-available/50-mod-http-cache-purge-custom.conf

With content:

load_module modules/ngx_http_cache_purge_module_custom.so;

(c) Remove (“disable”) the symbolic link to the configuration file that loads the default ngx_http_cache_purge_module.so in /etc/nginx/modules-enabled/ to avoid loading the default and custom modules at the same time:

rm /etc/nginx/modules-enabled/50-mod-http-cache-purge.conf

(d) Create a symbolic link to the configuration file that loads the custom ngx_http_cache_purge_module_custom.so :

ln -s /etc/nginx/modules-available/50-mod-http-cache-purge-custom.conf /etc/nginx/modules-enabled/50-mod-http-cache-purge-custom.conf

(e) Test and reload:

nginx -t
systemctl reload nginx

Why This Matters

With the custom-built purge module:

Cache purge requests succeed even when PHP-FPM pools run under non-www-data users.
WordPress and other CMS plugins that rely on cache invalidation start working reliably again.
You keep the security and isolation benefits of per-site system users without breaking cache management.

Rebuilding the purge module from Debian sources gives you both compatibility and reliability, ensuring your cache strategy works seamlessly in secure, multi-user environments.

About Olvy ( www.olvy.net / www.olvy.eu ) :

Olvy is a private and independent Limited Liability Company based in Bratislava, Slovakia, in the heart of Europe. We combined our invaluable 20+ years experience to develop innovative and reliable, lightning-fast and affordable Managed Cloud Hosting services for Everyone. From a small blog to a growing eCommerce – Olvy takes care of your website 24/7.