nginx-cache-purge

A tool to help purge Nginx cache. It can either run locally with the purge command, or run as a local unix service to allow for purging by Nginx http requests. The tool supports using wildcard/glob syntax in the purge key to match multiple keys from the cache.

Install

You can install either by downloading the latest binary release, or by building.

Building

Building should be as simple as running:

go build

Usage

The following are some examples of ways to purge cache

Purge a specific key

$ nginx-cache-purge purge /var/nginx/proxy_temp/cache example.com/index.html

Purge all keys for a domain

$ nginx-cache-purge purge /var/nginx/proxy_temp/cache 'example.com/*'

Purge all keys for jpeg and png files

$ nginx-cache-purge purge /var/nginx/proxy_temp/cache 'example.com/*.{jpg,jpeg,png}'

Purge all keys

$ nginx-cache-purge purge /var/nginx/proxy_temp/cache '*'

Running as a service

If you want to run as a service to allow purge requests via http requests, you'll need to create a systemd service file and place it in /etc/systemd/system/nginx-cache-purge.service.

[Unit]
Description=Nginx Cache Purge
After=network.target
 
[Service]
User=nginx
Group=nginx
RuntimeDirectory=nginx-cache-purge
ExecStart=/usr/local/bin/nginx-cache-purge server
Restart=always
RestartSec=3s
 
[Install]
WantedBy=multi-user.target

You can then run the following to start the service:

systemctl daemon-reload
systemctl start nginx-cache-purge.service

Nginx config

If you want to purge via Nginx http requests, you'll need to add configuration to your Nginx config file.

Map PURGE requests

http {
    map $request_method $is_purge {                                                             
        default   0;
        PURGE     1;
    }

    proxy_cache_path /var/nginx/proxy_temp/cache levels=1:2 keys_zone=my_cache:10m;
    proxy_cache_key $server_name$request_uri;

    server {
        location / {
            proxy_cache_bypass $is_purge;
            if ($is_purge) {
                proxy_pass http://unix:/run/nginx-cache-purge/http.sock;
                rewrite ^ /?path=/var/nginx/proxy_temp/cache&key=$server_name$request_uri break;
            }

            proxy_cache my_cache;
            proxy_pass http://upstream;
        }
    }
}

Auth via cookie

http {
    map $cookie_purge_token $is_purge {
        default 0;
        nnCgKUx1p2bIABXR 1;
    }

    proxy_cache_path /var/nginx/proxy_temp/cache levels=1:2 keys_zone=my_cache:10m;
    proxy_cache_key $server_name$request_uri;

    server {
        location / {
            proxy_cache_bypass $is_purge;
            if ($is_purge) {
                proxy_pass http://unix:/run/nginx-cache-purge/http.sock;
                rewrite ^ /?path=/var/nginx/proxy_temp/cache&key=$server_name$request_uri break;
            }

            proxy_cache my_cache;
            proxy_pass http://upstream;
        }
    }
}

Auth via header

http {
    map $http_purge_token $is_purge {
        default 0;
        nnCgKUx1p2bIABXR 1;
    }

    proxy_cache_path /var/nginx/proxy_temp/cache levels=1:2 keys_zone=my_cache:10m;
    proxy_cache_key $server_name$request_uri;

    server {
        location / {
            proxy_cache_bypass $is_purge;
            if ($is_purge) {
                proxy_pass http://unix:/run/nginx-cache-purge/http.sock;
                rewrite ^ /?path=/var/nginx/proxy_temp/cache&key=$server_name$request_uri break;
            }

            proxy_cache my_cache;
            proxy_pass http://upstream;
        }
    }
}

Auth via header and IP white list.

http {
    map $http_purge_token $is_purge {
        default 0;
        nnCgKUx1p2bIABXR 1;
    }

    geo $purge_allowed {
        default 0;
        127.0.0.1 1;
        192.168.0.0/24 1;
    }

    proxy_cache_path /var/nginx/proxy_temp/cache levels=1:2 keys_zone=my_cache:10m;
    proxy_cache_key $server_name$request_uri;

    server {
        location / {
            set $should_purge $purge_allowed;
            if ($is_purge != 1) {
                set $should_purge 0;
            }
            proxy_cache_bypass $should_purge;
            if ($should_purge) {
                proxy_pass http://unix:/run/nginx-cache-purge/http.sock;
                rewrite ^ /?path=/var/nginx/proxy_temp/cache&key=$server_name$request_uri break;
            }

            proxy_cache my_cache;
            proxy_pass http://upstream;
        }
    }
}

Using IP whitelists

http {
    proxy_cache_path /var/nginx/proxy_temp/cache levels=1:2 keys_zone=my_cache:10m;
    proxy_cache_key $server_name$request_uri;

    server {
        location / {
            proxy_cache my_cache;
            proxy_pass http://upstream;
        }
        location ~ /purge(/.*) {
            allow 127.0.0.1;
            deny all;
            proxy_pass http://unix:/run/nginx-cache-purge/http.sock;
            rewrite ^ /?path=/var/nginx/proxy_temp/cache&key=$server_name$1 break;
        }
    }
}

Help

$ nginx-cache-purge --help  
Usage: nginx-cache-purge <command> [flags]

Tool to help purge cache from Nginx

Flags:
  -h, --help       Show context-sensitive help.
      --version    Print version information and quit

Commands:
  server (s)    Run the server
  purge (p)     Purge cache now

Run "nginx-cache-purge <command> --help" for more information on a command.

$ nginx-cache-purge p --help
Usage: nginx-cache-purge purge (p) <cache-path> <key> [flags]

Purge cache now

Arguments:
  <cache-path>    Path to cache directory.
  <key>           Cache key or wildcard match.

Flags:
  -h, --help                           Show context-sensitive help.
      --version                        Print version information and quit

      --exclude-key=EXCLUDE-KEY,...    Key to exclude, can be wild card and can add multiple excludes.

$ nginx-cache-purge s --help
Usage: nginx-cache-purge server (s) [flags]

Run the server

Flags:
  -h, --help             Show context-sensitive help.
      --version          Print version information and quit

      --socket=STRING    Socket path for HTTP communication.
``