NginxHow-ToBeginner · 4 min read

How to Use Microcaching in Nginx for Faster Responses

Use proxy_cache_path to define a cache zone and proxy_cache with a short proxy_cache_valid time (like 1-5 seconds) in your Nginx config to enable microcaching. This caches responses briefly, reducing load and speeding up repeated requests.

📐

Syntax

Microcaching in Nginx uses these main directives:

proxy_cache_path: Defines where and how the cache is stored.
proxy_cache: Enables caching for a location using the defined cache zone.
proxy_cache_valid: Sets how long responses are cached.
proxy_cache_key: Defines the cache key, usually based on request URI.

nginx

proxy_cache_path /tmp/nginx_cache levels=1:2 keys_zone=microcache:10m max_size=100m inactive=60s use_temp_path=off;

server {
    location / {
        proxy_cache microcache;
        proxy_cache_key "$scheme$request_method$host$request_uri";
        proxy_cache_valid 200 5s;
        proxy_pass http://backend_server;
    }
}

💻

Example

This example shows microcaching setup that caches successful responses for 5 seconds to reduce backend load and speed up repeated requests.

nginx

proxy_cache_path /var/cache/nginx/microcache levels=1:2 keys_zone=microcache:10m max_size=50m inactive=60s use_temp_path=off;

server {
    listen 80;
    server_name example.com;

    location / {
        proxy_cache microcache;
        proxy_cache_key "$scheme$request_method$host$request_uri";
        proxy_cache_valid 200 5s;
        proxy_cache_use_stale error timeout updating;
        proxy_pass http://127.0.0.1:8080;
    }
}

⚠️

Common Pitfalls

Common mistakes when using microcaching include:

Setting too long cache times, which can serve stale content.
Not defining proxy_cache_key properly, causing cache misses.
Forgetting to create the cache directory or setting wrong permissions.
Not handling cache for error responses, which can cause serving errors repeatedly.

Always test cache behavior and tune proxy_cache_valid for your app's needs.

nginx

## Wrong: No cache key defined, causing cache misses
location / {
    proxy_cache microcache;
    proxy_cache_valid 5s;
    proxy_pass http://backend;
}

## Right: Define cache key including URI
location / {
    proxy_cache microcache;
    proxy_cache_key "$scheme$request_method$host$request_uri";
    proxy_cache_valid 200 5s;
    proxy_pass http://backend;
}

📊

Quick Reference

Directive	Purpose	Example Value
proxy_cache_path	Defines cache storage and zone	/tmp/nginx_cache levels=1:2 keys_zone=microcache:10m max_size=100m inactive=60s use_temp_path=off
proxy_cache	Enables cache zone in location	microcache
proxy_cache_key	Sets cache key for requests	"$scheme$request_method$host$request_uri"
proxy_cache_valid	Sets cache duration per status	200 5s
proxy_cache_use_stale	Serve stale content on errors	error timeout updating

✅

Key Takeaways

Define a cache zone with proxy_cache_path before using microcaching.

Set proxy_cache_valid to a few seconds (1-5s) for effective microcaching.

Always specify proxy_cache_key to avoid cache misses.

Use proxy_cache_use_stale to serve stale content during backend issues.

Ensure cache directory exists with correct permissions.