Nginx Caching

You are a DevOps engineer or backend developer. The user wants to configure Nginx caching for static assets and API responses to improve application performance and reduce server load.

What to check first

• Run nginx -v to confirm Nginx is installed and check version
• Check /etc/nginx/nginx.conf exists and Nginx process is running with systemctl status nginx
• Verify disk space available for cache with df -h /var/cache (default cache location)

Steps

1. Create a dedicated cache directory with mkdir -p /var/cache/nginx and set permissions with chown -R nginx:nginx /var/cache/nginx && chmod 700 /var/cache/nginx
2. Define cache zones in the http block of /etc/nginx/nginx.conf using proxy_cache_path directive with size, levels, and inactive time parameters
3. Configure cache key using proxy_cache_key to include scheme, host, request_uri, and custom variables like $request_method
4. Set cache validity periods with proxy_cache_valid for different HTTP status codes (200, 301, 404, etc.) with separate TTLs
5. Add proxy_cache directive in server/location blocks to activate caching for specific routes
6. Configure cache control headers with proxy_ignore_headers and proxy_pass_header to respect or override upstream Cache-Control directives
7. Enable cache bypass and purging with proxy_cache_bypass conditions and optional purge module for manual invalidation
8. Test cache behavior with curl -i headers checking X-Cache-Status or Age response headers, then reload Nginx with nginx -s reload

Code

# /etc/nginx/nginx.conf - http block

http {
    # Define cache zones for static assets and API responses
    proxy_cache_path /var/cache/nginx/static levels=1:2 keys_zone=static_cache:10m max_size=1g inactive=60m use_temp_path=off;
    proxy_cache_path /var/cache/nginx/api levels=1:2 keys_zone=api_cache:50m max_size=5g inactive=10m use_temp_path=off;

    # Cache key configuration
    proxy_cache_key "$scheme$request_method$host$request_uri";
    proxy_cache_use_stale error timeout updating http_500 http_502 http_503 http_504;

    # Include other nginx settings
    include /etc/nginx/mime.types;
    default_type application/octet-stream;

    server {
        listen 80;
        server_name example.com;

        # Static assets caching (images, CSS, JS)
        location ~* \.(jpg|jpeg|png|gif|ico|css|js|svg|woff|woff2|ttf|eot)$ {
            proxy_pass http://backend;
            proxy_cache static_cache;

Note: this example was truncated in the source. See the GitHub repo for the latest full version.

Common Pitfalls

• Treating this skill as a one-shot solution — most workflows need iteration and verification
• Skipping the verification steps — you don't know it worked until you measure
• Applying this skill without understanding the underlying problem — read the related docs first

When NOT to Use This Skill

• When a simpler manual approach would take less than 10 minutes
• On critical production systems without testing in staging first
• When you don't have permission or authorization to make these changes

How to Verify It Worked

• Run the verification steps documented above
• Compare the output against your expected baseline
• Check logs for any warnings or errors — silent failures are the worst kind

Production Considerations

• Test in staging before deploying to production
• Have a rollback plan — every change should be reversible
• Monitor the affected systems for at least 24 hours after the change