Proxy cache basics in Nginx - Commands & Configuration

Introduction

Sometimes web servers get too many requests and slow down. Proxy cache helps by saving copies of web pages so future visitors get them faster without asking the main server again.

When your website gets many visitors asking for the same pages repeatedly.

When you want to reduce the load on your main web server to keep it fast.

When you want to speed up response times for users by serving cached content.

When you have a backend server that is slow or expensive to run for every request.

When you want to save bandwidth by not fetching the same data multiple times.

Config File - nginx.conf

nginx.conf

proxy_cache_path /var/cache/nginx levels=1:2 keys_zone=my_cache:10m max_size=100m inactive=60m use_temp_path=off;

server {
    listen 80;
    server_name example.com;

    location / {
        proxy_pass http://backend_server;
        proxy_cache my_cache;
        proxy_cache_valid 200 302 10m;
        proxy_cache_valid 404 1m;
        proxy_cache_use_stale error timeout updating;
        add_header X-Proxy-Cache $upstream_cache_status;
    }
}

proxy_cache_path defines where cached files are stored, cache size, and cache zone name.

server block listens on port 80 for example.com.

location / proxies requests to backend_server and enables caching using the defined cache zone.

proxy_cache_valid sets how long responses with certain status codes are cached.

proxy_cache_use_stale allows serving stale cache if backend has errors or timeouts.

add_header adds a header to show cache status for debugging.

Commands

Check the nginx configuration file syntax to make sure there are no errors before restarting.

Terminal

sudo nginx -t

Expected Output

nginx: the configuration file /etc/nginx/nginx.conf syntax is ok

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

Restart nginx to apply the new proxy cache configuration.

Terminal

sudo systemctl restart nginx

Expected Output

No output (command runs silently)

Send a request to the server and check the response headers to see if the cache is working (look for X-Proxy-Cache header).

Terminal

curl -I http://example.com

Expected Output

HTTP/1.1 200 OK

Server: nginx

Date: Tue, 27 Jun 2024 12:00:00 GMT

Content-Type: text/html

X-Proxy-Cache: MISS

Connection: keep-alive

Send the same request again to see if the response is served from cache (X-Proxy-Cache should show HIT).

Terminal

curl -I http://example.com

Expected Output

HTTP/1.1 200 OK

Server: nginx

Date: Tue, 27 Jun 2024 12:00:10 GMT

Content-Type: text/html

X-Proxy-Cache: HIT

Connection: keep-alive

Key Concept

If you remember nothing else from this pattern, remember: proxy cache stores copies of responses to serve future requests faster and reduce backend load.

Common Mistakes

Not testing nginx configuration before restart.

This can cause nginx to fail restarting due to syntax errors, making the website unavailable.

Always run 'nginx -t' to check configuration syntax before restarting.

Forgetting to set proxy_cache_path before using proxy_cache.

Without defining proxy_cache_path, nginx will not know where to store cache and caching won't work.

Define proxy_cache_path with proper parameters before enabling proxy_cache in location.

Not checking cache status headers to verify caching.

You won't know if caching is working or not, leading to confusion and troubleshooting delays.

Add a header like X-Proxy-Cache and check it with curl to confirm cache hits or misses.

Summary

Define proxy_cache_path to set cache storage location and size.

Enable proxy_cache in server location to cache backend responses.

Use curl and headers to verify if caching is working as expected.