NGINX FastCGI Cache Purging & Management Guide

Overview

This comprehensive guide covers the procedures for managing and purging FastCGI cache in NGINX. When working with FastCGI caching, you have two primary options for cache management: complete cache deletion or selective post purging. Understanding both methods is essential for efficient WordPress site management.

Cache Purging Workflow

Cache Management Decision

↓

Full Cache Purge
(All Content)

↓

Bash Script Method

Selective Purge
(Single Post)

↓

URL Purge Method

Method 1: Selective Cache Purging

Selective cache purging allows you to remove individual posts from the cache without affecting other cached content. This is particularly useful for large sites with thousands of posts where clearing the entire cache would be inefficient.

Step 1: Configure NGINX Server Block

First, you need to add the purge location context to your NGINX server block configuration file.

cd /etc/nginx/sites-available

sudo nano example.com.conf

Important: Add the following location context underneath the add_header X-FastCGI-Cache directive. Replace NAME with your actual keys_zone name (e.g., expert_WP).

location ~ /purge(/.*) {
fastcgi_cache_purge NAME "$scheme$request_method$host$1";
}

Configuration Example

If your keys_zone name is expert_WP, your configuration should look like:

location ~ /purge(/.*) {
fastcgi_cache_purge expert_WP "$scheme$request_method$host$1";
}

Step 2: Test and Reload NGINX

After adding the purge configuration, you must test the syntax and reload NGINX.

sudo nginx -t

Expected Output: nginx: configuration file /etc/nginx/nginx.conf test is successful

sudo systemctl reload nginx

Step 3: Verify Cache Status

Check the cache status of your pages to confirm they are being cached properly.

curl -I https://example.com

curl -I https://example.com/test-post-one/

curl -I https://example.com/test-post-two/

Cache Status Headers:

HIT - Content served from cache
MISS - Content not in cache, served from origin
BYPASS - Cache bypassed due to exclusion rules

Step 4: Selectively Purge a Single Post

To purge a specific post from cache, use the curl command with the /purge/ prefix before the post slug.

curl -I https://example.com/purge/test-post-one/

Result: Only test-post-one will be removed from cache. All other cached content remains intact.

Step 5: Verify Selective Purge

Confirm that only the targeted post was purged while others remain cached.

curl -I https://example.com/test-post-one/

Expected: MISS (post was purged, needs to be re-cached)

curl -I https://example.com/test-post-two/

Expected: HIT (post remains in cache)

curl -I https://example.com

Expected: HIT (homepage remains in cache)

Practical Use Case

If you modify a single blog post on a site with thousands of posts, you can selectively purge only that post from the cache. This approach is much more efficient than clearing the entire cache and forcing all pages to be regenerated.

Method 2: Complete Cache Purging with Bash Script

For situations where you need to clear all cached content, a bash script provides an automated and reliable solution. This method is useful during major site updates, theme changes, or plugin installations.

Step 1: Create Scripts Directory

First, create a dedicated directory in your user's home directory for storing NGINX bash scripts.

cd ~

mkdir nginx_bash_scripts

cd nginx_bash_scripts

Step 2: Create Cache Clearing Script

Create a bash script file with a descriptive name that includes your domain name.

nano 1_clear_cache_example.com.sh

Naming Convention: Starting the filename with a number (e.g., 1_) makes it easier to run using tab autocompletion.

Step 3: Add Script Contents

Add the following content to your bash script file:

#!/bin/bash
rm -rf /var/run/expert_WP/*

Important: Replace expert_WP with your actual keys_zone name. The path format is: /var/run/YOUR_KEYS_ZONE_NAME/*

Component	Description
`#!/bin/bash`	Shebang line specifying the bash interpreter
`rm -rf`	Remove command with recursive and force flags
`/var/run/expert_WP/`	Path to your FastCGI cache directory
`*`	Wildcard to delete all files in the directory

Step 4: Make Script Executable

Grant executable permissions to your script file.

sudo chmod +x 1_clear_cache_example.com.sh

Step 5: Execute the Script

Run the script using sudo privileges.

sudo ./1_clear_cache_example.com.sh

Pro Tip: You can use tab autocompletion after typing sudo ./1_ and pressing Tab to complete the filename automatically.

Step 6: Verify Cache Clearance

Confirm that all cached content has been removed.

curl -I https://example.com

Expected: MISS

curl -I https://example.com/test-post-one/

Expected: MISS

curl -I https://example.com/test-post-two/

Expected: MISS

Step 7: Verify Cache Regeneration

Run the curl commands again to verify that pages are being re-cached.

curl -I https://example.com/test-post-two/

Expected: HIT (page has been re-cached)

curl -I https://example.com/test-post-one/

Expected: HIT (page has been re-cached)

curl -I https://example.com

Expected: HIT (page has been re-cached)

Step 8: Inspect Cache Directory

Verify the cache directory contents to see cached files.

sudo ls -l /var/run/expert_WP

Run the script again to clear the cache:

sudo ./1_clear_cache_example.com.sh

Verify the directory is empty:

sudo ls -l /var/run/expert_WP

Result: The directory should be empty after running the script.

Method Comparison

Feature	Selective Purging	Complete Purge (Bash Script)
Scope	Single post/page	Entire cache
Efficiency	High (minimal impact)	Low (all content must be re-cached)
Use Case	Single post update	Major site changes
Server Load	Minimal	Higher during re-caching
Execution Method	curl command	Bash script
Best For	Large sites with frequent updates	Site-wide updates or troubleshooting

Removing FastCGI Caching Completely

When migrating to a different caching solution (such as WP Super Cache or W3 Total Cache), you must properly remove FastCGI caching from your NGINX configuration. This process involves removing configuration directives from multiple files.

Warning: If you have multiple sites using FastCGI caching, do NOT remove shared configuration files or directives from nginx.conf. Only remove site-specific configurations.

Step 1: Remove Cache Clearing Script

Delete the bash script used for clearing the cache.

cd ~/nginx_bash_scripts

rm 1_clear_cache_example.com.sh

cd ~

Note: Keep the nginx_bash_scripts directory for future use with other caching solutions.

Step 2: Edit NGINX Server Block

Remove FastCGI caching directives from your site's NGINX configuration file.

cd /etc/nginx/sites-available

sudo nano example.com.conf

Remove the Following Directives:

1. Include Directive (Top of File)

include /etc/nginx/includes/fastcgi_cache_excludes.conf;

Action: Remove this entire line using Ctrl+K

2. Cache Status Header

add_header X-FastCGI-Cache $upstream_cache_status;

Action: Remove this entire line

3. Purge Location Context

location ~ /purge(/.*) {
fastcgi_cache_purge NAME "$scheme$request_method$host$1";
}

Action: Remove the entire location block

4. PHP Location Context Directives

Remove these directives from within the PHP location block:

fastcgi_cache_bypass $skip_cache;
fastcgi_no_cache $skip_cache;
fastcgi_cache NAME;
fastcgi_cache_valid 60m;

Action: Remove all four lines

Step 3: Remove Cache Excludes Include File

Delete the FastCGI cache exclusions configuration file.

cd /etc/nginx/includes

sudo rm fastcgi_cache_excludes.conf

Step 4: Edit nginx.conf (If Applicable)

If this is your only site using FastCGI caching, remove the global directives.

cd /etc/nginx

sudo nano nginx.conf

Important Multi-Site Warning: If you have other sites using FastCGI caching, do NOT remove these directives from nginx.conf. Only remove directives for the specific site being transitioned.

Remove These Directives (Single Site Only):

fastcgi_cache_path /var/run/expert_WP levels=1:2 keys_zone=expert_WP:100m inactive=60m;
fastcgi_cache_key "$scheme$request_method$host$request_uri";
fastcgi_cache_use_stale error timeout invalid_header http_500;
fastcgi_ignore_headers Cache-Control Expires Set-Cookie;

Step 5: Test and Reload NGINX

Verify the configuration and reload NGINX.

sudo nginx -t

Expected: nginx: configuration file /etc/nginx/nginx.conf test is successful

sudo systemctl reload nginx

Completion: FastCGI caching has been successfully removed from your WordPress site. You can now implement an alternative caching solution such as WP Super Cache or W3 Total Cache.

Multi-Site Configuration Considerations

FastCGI Cache Removal Decision Tree

Removing FastCGI Cache?

↓

Do you have multiple sites using FastCGI?

↓

YES
Multiple Sites

↓

Keep nginx.conf directives
Keep includes file
Remove only site-specific config

NO
Single Site

↓

Remove all directives
Remove includes file
Remove nginx.conf directives

Multi-Site Removal Guidelines

Configuration Element	Single Site	Multiple Sites
Site Server Block	✓ Remove all directives	✓ Remove all directives
fastcgi_cache_excludes.conf	✓ Delete file	✗ Keep file (shared)
nginx.conf cache_path	✓ Remove site's cache_path	✓ Remove only this site's cache_path
nginx.conf global directives	✓ Remove all FastCGI directives	✗ Keep global directives
Bash clearing script	✓ Delete script	✓ Delete script

Multiple Site Example

If you have two sites (site1.com and site2.com) both using FastCGI caching, and you want to remove caching from site1.com only:

Remove FastCGI directives from site1.com.conf
Remove site1.com cache_path from nginx.conf
Keep fastcgi_cache_excludes.conf (site2.com still uses it)
Keep global FastCGI directives in nginx.conf
Keep site2.com cache_path in nginx.conf

Best Practices and Recommendations

When to Use Each Method

Use Selective Purging When:

Updating individual blog posts
Modifying specific pages
Fixing typos or minor content changes
Managing large sites with thousands of posts
Minimizing server load is critical

Use Complete Cache Purge When:

Changing themes or layouts
Installing/updating major plugins
Modifying site-wide settings
Troubleshooting cache-related issues
Performing database migrations

Performance Optimization Tips

Tip 1: Cache Warming
After clearing the entire cache, consider implementing a cache warming strategy by pre-loading critical pages. This can be done using a sitemap crawler or custom script.

Tip 2: Monitoring Cache Status
Regularly monitor cache hit/miss ratios using server logs or monitoring tools. High miss rates may indicate configuration issues or excessive cache purging.

Tip 3: Automation
Consider integrating cache purging with your deployment pipeline or content management workflow to automate cache management during updates.

Common Troubleshooting

Issue	Cause	Solution
Purge URL returns 404	Purge location not configured	Verify purge location context in server block
Cache not clearing	Incorrect keys_zone name	Match keys_zone name in all directives
Permission denied error	Script lacks execute permissions	Run: sudo chmod +x script_name.sh
NGINX test fails after removal	Incomplete directive removal	Check for orphaned FastCGI references

Summary

This guide has covered comprehensive methods for managing NGINX FastCGI cache, including:

Selective Cache Purging: Remove individual posts using the /purge/ URL method for efficient, targeted cache management
Complete Cache Clearing: Use bash scripts to remove all cached content when site-wide updates are necessary
Complete Removal: Properly remove FastCGI caching configuration when migrating to alternative caching solutions
Multi-Site Management: Understand the differences between single-site and multi-site configuration requirements

Key Takeaway: Choose the appropriate cache management method based on your specific needs. Selective purging is ideal for routine content updates, while complete cache clearing is reserved for major site changes. Always follow proper removal procedures when transitioning to different caching solutions.

Next Steps: After mastering FastCGI cache management, you can explore alternative caching solutions such as WP Super Cache or W3 Total Cache, which offer plugin-based management through the WordPress dashboard.