Tips / Nginx

Nginx Proxy Cache Explained

When you are developing applications, among many things, you must focus in four important things: user experience, security, scalability and performance. And this last thing is not always 100% clear when you are a jr dev or are just starting in this coding world. While having good hardware and fast internet uplinks can help you to gain great speeds, sometimes your app is badly coded and is not performing as expected when you move from development phase to the production servers.

One of the best ways to get a great app performance is adding caching layers to your content and functions, you can add cache to static files (images, javascript, css, etc), to database operations and also to dynamic content delivered by PHP, Python and many other programming languages.

Nginx Proxy Cache

Nginx is a web server, but also a proxy server, and one of the most widely used functions of Nginx is its proxy technology. When you deploy Nginx as reverse proxy or load balancer, you can enable powerful cache features, and that is what this post is about. On this topic we will try to explain what is Nginx Proxy Cache and how you enable it to speed up your web applications.

What is Proxy Cache?

​Proxy cache is basically data stored on a intermediate server between the client and the final server. In our case, Nginx is the proxy server that will save a copy of the original content on the proxy cache, and once the client browser requests the original file, the proxy cache will deliver the copy, allowing faster speeds and reducing system resource usage (CPU, RAM and I/O) on the destination server.

How can I enable Nginx Proxy Cache?

In order to enable proxy cache you need to edit nginx.conf file and set two important variables:

  • proxy_cache_path: the path where you will store your caching data, aldo the place where you will configure your cache settings.
  • proxy_cache: the directive used to activate the proxy cache.

Example of a fully working proxy cache configuration:

proxy_cache_path /var/nginx/cache levels=1:2 keys_zone=app_cache:10m max_size=5g inactive=45m use_temp_path=off;

server {
location /products {
proxy_cache app_cache;
proxy_pass http://app_upstream;

Let’s explain each option we used:

proxy_cache_path /var/nginx/cache levels=1:2 keys_zone=app_cache:10m max_size=5g inactive=45m use_temp_path=off;

/var/nginx/cache/ is the chosen directory to store the cache data, you can set any directory as you like.

levels=1:2 specifies a two-level directory hierarchy under /var/nginx/cache. This is useful when you have a very big number of cached files to avoid slow speeds during file access.

keys_zone=app_cache:10m defines a 10M shared memory zone that will store the cache keys and metadata information. This helps to speed up proxy cache checks.

max_size is the maximum limit of the cache size, in this case we set it to 5G. It’s always recommended to enable the size max limit in order to prevent disk space issues, as if you leave it without any limit, Nginx will keep writing the cache data until all available disk space is used.

inactive=45m is the cache life limit for inactive content, it specifies how long a cached item can remain on cache without being accessed. If a file is not accessed within the last 45 minutes, then it will be removed from the cache.

use_temp_path=off sets the temporary directory to off, this means Nginx will write the temporary files used for cache, into the same directory as defined previously at the proxy_cache_path variable (/var/nginx/cache in this case). To avoid unnecessary I/O operations we set it to off.

proxy_cache enables caching of all the content placed under the location block, in this case was set as “location /products”, but you can place it to cache all your website content, for example:

location / {
proxy_cache app_cache;
proxy_pass http://app_upstream;

I don’t want to cache some objects, what can I do?

If your proxy_cache is set under a location block that includes all the content (location /), you can avoid caching any files that contains the Cache-Control set to Private, No-Cache and No-Store, also headers that contain Set-Cookie will not be cached, this is set on the origin server and Nginx will respect those settings to avoid caching unnecessary files. If you need more information, read this interesting Google doc about Cache-control  and what are the available options.

How can I clear the proxy cache?

There are tricky ways to delete the content of your cache, and there are fast ways. The tricky way is using proxy_cache_purge directive, this directive can be configured to set some conditions where so Nginx can detect if the request is a purge or an access request, and act removing the cache key from the stored cache. This is useful when you have to delete some cache files, and not all of them.

And the fast way to delete all the cache is just by deleting the cache files:

find /var/nginx/cache -type f -delete
service nginx restart

How can I check Nginx proxy cache is working?

Simple: take a look at /var/nginx/cache directory, if the proxy cache is working you should see lot of files created inside that directory. You can do it by running:

ls -alh  /var/nginx/cache


Nginx is a powerful and robust web server that includes many caching options, as we’ve seen on this post using the Proxy Cache feature can help you to cache critical content on your web server and speed up your applications. Remember that performance is not only important to avoid server overload and slow speeds, but also to keep a great user experience.

What is your experience working with Nginx Proxy Cache feature? Please leave your comments below.

Read more about Nginx Proxy Cache from Nginx official docs

Popular search terms:

  • nginx proxy_cache
  • where nginx store cache data
  • nginx proxy path
  • nginx proxy cache

Esteban Borges

Linux Geek, Webperf Addict, Nginx Fan. CTO @Infranetworking

  • Thanks! I’d love to see a post about using proxy_cache for WordPress sites as several of my sites use NGINX as a Proxy to Apache instead of using PHP-FPM directly.

    Cheers & Happy New Year!

  • Anthony Stark

    Apr 24 00:11:33 nginx[15039]: nginx: [emerg] host not found in upstream “app_upstream” in /home/admin/conf/web/nginx.conf:16