Proxy cache basics in Nginx - Deep Dive

Overview - Proxy cache basics

What is it?

Proxy cache is a way for a server to save copies of responses from another server. When a user asks for the same content again, the server can give the saved copy instead of asking the original server again. This makes websites faster and reduces the load on the original server. Nginx is a popular tool that can act as a proxy cache.

Why it matters

Without proxy cache, every user request goes to the original server, which can slow down responses and overload the server. Proxy cache speeds up websites by serving saved content quickly and reduces internet traffic. This improves user experience and saves resources for website owners.

Where it fits

Before learning proxy cache, you should understand basic web servers and how HTTP requests and responses work. After mastering proxy cache, you can learn advanced caching strategies, load balancing, and content delivery networks (CDNs).

Mental Model

Core Idea

Proxy cache stores copies of server responses to quickly serve repeated requests without contacting the original server each time.

Think of it like...

Imagine a library that keeps popular books on a special shelf. Instead of ordering the book from another city every time someone wants it, the library gives the book from the shelf immediately. This saves time and effort.

┌───────────────┐       ┌───────────────┐       ┌───────────────┐
│   Client      │──────▶│  Proxy Cache  │──────▶│  Origin Server│
│ (User's web  │       │ (Nginx server │       │ (Original web │
│  browser)    │       │  with cache)  │       │  server)      │
└───────────────┘       └───────────────┘       └───────────────┘
       ▲                      │  ▲                     │
       │                      │  │                     │
       └──────────────────────┘  └─────────────────────┘

Build-Up - 7 Steps

1

Foundation

What is Proxy Cache in Nginx

Concept: Introduce the basic idea of proxy cache and its role in Nginx.

Proxy cache in Nginx saves copies of responses from an upstream server. When a client requests the same content again, Nginx serves the cached copy instead of forwarding the request. This reduces response time and server load.

Result

Nginx can serve repeated requests faster by using stored responses.

Understanding proxy cache as a middleman that remembers answers helps grasp why it speeds up web traffic.

2

Foundation

Basic Nginx Proxy Cache Setup

Concept: Learn how to configure proxy cache in Nginx with simple directives.

To enable proxy cache, define a cache path and zone, then use proxy_cache directive in a server block. Example: proxy_cache_path /tmp/nginx_cache levels=1:2 keys_zone=my_cache:10m max_size=100m inactive=60m; server { location / { proxy_pass http://backend; proxy_cache my_cache; proxy_cache_valid 200 302 10m; } } This tells Nginx to save responses in /tmp/nginx_cache and reuse them for 10 minutes.

Result

Nginx stores and serves cached responses for matching requests.

Knowing the minimal config needed to start caching makes the concept practical and approachable.

3

Intermediate

Cache Key and How It Works

🤔Before reading on: do you think Nginx caches responses based only on the URL or also on headers? Commit to your answer.

Concept: Understand how Nginx decides which requests share the same cached response using cache keys.

Nginx uses a cache key to identify cached items. By default, it uses the full request URL including query parameters. You can customize the key with proxy_cache_key directive to include headers or cookies. This controls cache granularity and avoids serving wrong content.

Result

Nginx caches responses correctly for different requests based on the cache key.

Knowing cache keys prevents cache mix-ups and helps tailor caching to your app's needs.

4

Intermediate

Cache Control and Expiration

🤔Before reading on: do you think Nginx ignores origin server cache headers or respects them by default? Commit to your answer.

Concept: Learn how Nginx decides when cached content expires and when to fetch fresh content.

Nginx respects HTTP headers like Cache-Control and Expires by default to decide cache lifetime. You can override this with proxy_cache_valid to set custom expiration times. Also, inactive directive removes cache items not requested for a set time. This keeps cache fresh and efficient.

Result

Cached content expires properly, balancing freshness and speed.

Understanding cache expiration avoids serving stale content and controls resource use.

5

Intermediate

Cache Bypass and Purging

🤔Before reading on: do you think cached content can be removed manually or only expires automatically? Commit to your answer.

Concept: Explore how to skip cache for certain requests and how to clear cached content when needed.

You can bypass cache using proxy_cache_bypass with conditions like cookies or headers. To remove cached items immediately, Nginx supports cache purging with extra modules or by deleting cache files manually. This is useful when content changes and cache must update instantly.

Result

You control when cache is used or cleared, ensuring content accuracy.

Knowing how to bypass and purge cache prevents serving outdated or wrong content.

6

Advanced

Cache Storage and Performance Tuning

🤔Before reading on: do you think cache files are stored in memory or on disk by default? Commit to your answer.

Concept: Understand where Nginx stores cached data and how to optimize cache performance.

Nginx stores cache files on disk in the specified path. The levels parameter controls directory structure to avoid too many files in one folder. You can tune max_size to limit cache size and inactive to remove old files. Using fast storage like SSD improves speed. Proper tuning balances disk use and response time.

Result

Cache storage is efficient and fast, improving overall server performance.

Knowing storage details helps avoid slowdowns and disk overload in production.

7

Expert

Handling Cache in Complex Architectures

🤔Before reading on: do you think proxy cache works the same with HTTPS and load balancers? Commit to your answer.

Concept: Learn how proxy cache behaves with HTTPS, load balancers, and multiple backend servers.

With HTTPS, Nginx can cache responses after decrypting traffic. When using load balancers, cache keys must consider backend differences to avoid wrong content. In multi-server setups, cache synchronization or shared storage is needed to keep cache consistent. Misconfiguration can cause stale or incorrect data delivery.

Result

Proxy cache works reliably in complex, secure, and distributed environments.

Understanding these complexities prevents subtle bugs and ensures cache correctness at scale.

Under the Hood

Nginx intercepts client requests and checks if a cached response exists for the cache key. If yes and valid, it serves the cached file from disk without contacting the origin server. If not, it forwards the request upstream, saves the response to cache, and then serves it. Cache files are stored in a directory structure to optimize file system performance.

Why designed this way?

Nginx was designed for high performance and low resource use. Storing cache on disk avoids memory exhaustion and allows large caches. Using a cache key ensures correct content delivery. The modular design lets users customize caching behavior for different needs.

┌───────────────┐
│ Client Request│
└──────┬────────┘
       │
       ▼
┌───────────────┐
│ Check Cache   │───Yes──▶ Serve Cached Response
│ (Disk lookup) │
└──────┬────────┘
       │No
       ▼
┌───────────────┐
│ Forward to    │
│ Origin Server │
└──────┬────────┘
       │
       ▼
┌───────────────┐
│ Save Response │
│ to Cache Disk │
└──────┬────────┘
       │
       ▼
┌───────────────┐
│ Serve Response│
└───────────────┘

Myth Busters - 4 Common Misconceptions

Quick: Does proxy cache always serve the latest content without delay? Commit yes or no.

Common Belief: Proxy cache always serves the newest content immediately after origin updates.

Reality: Proxy cache serves stored content until it expires or is purged, so updates on origin may not appear instantly.

Why it matters: Assuming instant updates can cause users to see outdated content, leading to confusion or errors.

Quick: Do you think proxy cache stores content in memory by default? Commit yes or no.

Common Belief: Proxy cache keeps cached responses in memory for fastest access.

Reality: Nginx proxy cache stores cached responses on disk, not memory, to handle large caches efficiently.

Why it matters: Expecting memory caching can lead to wrong performance assumptions and misconfiguration.

Quick: Can proxy cache serve different content for the same URL based on headers without configuration? Commit yes or no.

Common Belief: Proxy cache automatically differentiates cached content by headers like cookies or user-agent.

Reality: By default, proxy cache keys only include the URL; headers must be explicitly added to the cache key to vary cache content.

Why it matters: Ignoring this can cause wrong content to be served to users with different headers.

Quick: Does enabling proxy cache guarantee reduced load on origin server in all cases? Commit yes or no.

Common Belief: Proxy cache always reduces origin server load once enabled.

Reality: If cache is misconfigured or bypassed often, origin load may not reduce and can even increase.

Why it matters: Overestimating cache benefits can lead to unexpected server overload and downtime.

Expert Zone

1

Cache keys can include variables like headers, cookies, or request body parts to finely control caching behavior.

2

Inactive cache items are removed only after not being requested for a set time, which can cause disk space to fill if not tuned.

3

Cache purging requires extra modules or manual file deletion; Nginx does not support it natively in the core.

When NOT to use

Proxy cache is not suitable for highly dynamic content that changes per user or request, such as personalized dashboards. In such cases, use application-level caching or edge caching with user-aware logic.

Production Patterns

In production, proxy cache is combined with load balancers and CDNs. Cache keys are customized to handle multi-tenant apps. Cache purging is automated via API calls. Monitoring cache hit ratios and tuning expiration times are standard practices.

Connections

Content Delivery Networks (CDNs)

Proxy cache is a local caching layer similar to CDNs but usually closer to the origin server.

Understanding proxy cache helps grasp how CDNs cache content globally to speed up delivery worldwide.

HTTP Protocol

Proxy cache relies on HTTP headers like Cache-Control and Expires to manage caching behavior.

Knowing HTTP caching headers is essential to configure proxy cache correctly and avoid stale content.

Library Book Lending Systems

Both systems store and lend copies to save time and resources instead of fetching originals repeatedly.

Recognizing this pattern across domains shows how caching optimizes resource use in many fields.

Common Pitfalls

#1 Serving stale content because cache expiration is not set properly.

Wrong approach:

proxy_cache_valid 200 302 9999m;

Correct approach:

proxy_cache_valid 200 302 10m;

Root cause:

Misunderstanding that very long cache times cause outdated content to be served.

#2 Cache mix-up by not including necessary headers in cache key.

Wrong approach:

proxy_cache_key "$scheme://$host$request_uri";

Correct approach:

proxy_cache_key "$scheme://$host$request_uri$http_cookie";

Root cause:

Assuming URL alone is enough to differentiate cached content.

#3 Cache never purges because inactive time is too long or not set.

Wrong approach:

proxy_cache_path /cache levels=1:2 keys_zone=zone:10m max_size=1g inactive=0;

Correct approach:

proxy_cache_path /cache levels=1:2 keys_zone=zone:10m max_size=1g inactive=60m;

Root cause:

Not setting inactive time causes cache files to accumulate indefinitely.

Key Takeaways

Proxy cache stores server responses to speed up repeated requests and reduce load.

Nginx proxy cache saves cached data on disk using keys based on request details.

Cache expiration and bypass rules control freshness and accuracy of served content.

Proper cache key design prevents serving wrong content to different users.

Advanced setups require careful tuning and understanding of cache behavior in complex environments.