Tips / Nginx

How to Configure Nginx FASTCGI Cache

Nginx has many cool features enabled by default. One of those is something called the FastCGI cache. As you can imagine, the FastCGI cache is a cache system built for your dynamic requests, such as the ones made from popular CMS like WordPress, Drupal, Joomla, or your own hand-made web developments.

The best thing about this cache system is that it doesn’t depend on any external PHP-MySQL apps or plugins to serve your content fast. You don’t even have to rely on proxy cache solutions like Varnish because the FastCGI Cache is hosted and served by the Nginx core without any external interaction with other apps or system daemons.

It works the same as most cache mechanisms. Nginx defines a FastCGI shared memory zone that is used to store your cache files. Then, you can configure PHP-FPM to use that cache location.

Today, you will learn how to configure the FastCGI cache + PHP-FPM and optionally serve it from RAM memory, which is a lot faster than disks.

How to enable FastCGI cache on Nginx

nano -w /etc/nginx/nginx.conf

Add these lines at the end of the file, inside the http {} block section:

fastcgi_cache_path /etc/nginx/cache levels=1:2 keys_zone=YOURAPP:100m inactive=60m;
fastcgi_cache_key "$scheme$request_method$host$request_uri";

Reload Nginx to apply changes:

service nginx reload

Explanation of FastCGI cache options

The path defined is the location where the cached content will be stored. The keys_zone is a unique name (YOURAPP in this case) to identify the cache location.

The defined size is 100Mb.

The inactive time option is set to 60 minutes. This directive is very important for specifying the amount of time that a cached file can be stored in the cache directory before it’s removed. If the file hasn’t been accessed within the last 60 minutes, it will be removed from the FastCGI cache directory.

The “fastcgicachekey” directive specifies how long the cache files will be hashed.

Integrating the FastCGI cache with PHP-FPM

PHP-FPM is one of the most popular PHP daemons used with Nginx. To let PHP-FPM serve its files from the FastCGI cache, you will have to add two simple lines at the end of its configuration, inside the server {} block section:

fastcgi_cache YOURAPP;
fastcgi_cache_valid 200 60m;

Here, the “fastcgi_cache_valid” variable is used to specify the caching time for different response codes. In this example, you will see the “200” header response code. Here is another example:

fastcgi_cache_valid 200 302 60m;
fastcgi_cache_valid 404      1m;

Here, the “302” response is added under the 60 minutes rule, and the “404” response has a 1 minute cache lifetime. Tweak as needed.

A complete PHP-FPM configuration with this directive should look similar to this:

location ~ .php$ {
            try_files $uri =404;
            fastcgi_pass   unix:/tmp/php5-fpm.sock;
            fastcgi_index  index.php;
            fastcgi_param  SCRIPT_FILENAME  $document_root$fastcgi_script_name;
            include        fastcgi_params;
            fastcgi_buffer_size 128k;
            fastcgi_buffers 256 4k;
            fastcgi_busy_buffers_size 256k;
            fastcgi_temp_file_write_size 256k;
            fastcgi_cache YOURAPP;
            fastcgi_cache_valid 200 60m;

Run a config test to see if everything is okay with your Nginx configuration:

service nginx configtest

If everything is good, reload Nginx to apply changes:

service nginx reload

How to check that the FastCGI cache is working

Running an ls -alhR over your cache directory should show the cache files that Nginx has generated:

ls -alhR /etc/nginx/cache

How to serve FastCGI cache from RAM memory

RAM memory is faster than a disk, and you will get the best response times by working from RAM memory. Here, you will edit your /etc/fstab file and then add your cache directory like this:

nano -w /etc/fstab

Then, paste this at the end of the file:

tmpfs /etc/nginx/cache tmpfs defaults,size=100M 0 0

In this example, you assign 100MB of RAM for the cache. Tweak as needed. One thing that is important to remember about the RAM cache compared to the disk cache is that rebooting the Linux system causes the cache to be deleted. Your site will have to start generating the cache files again, so be aware of that before putting your cache files into RAM.

Mount the new RAM partition:

mount -a

Check to make sure it’s working:

df -ah | grep tmpfs

You should see something like this:

tmpfs              100M  4K  100M   0% /etc/nginx/cache


Cache systems are evolving, and built in cache mechanisms like FastCGI Cache from Nginx are letting developers get rid of old PHP based caches. Those were good, but only added extra layers of information to get to the final destination. Nginx has changed that concept and allows the developer to take full control of the cache system with simple but effective configurations.

Have you used FastCGI Cache? How does it compare with other traditional caching systems like Varnish and others like W3TC from WordPress? Please share your thoughts.

Read more from FastCGI Cache at Nginx’s official documentation 

Popular search terms:

  • fastcgi cache nginx
  • NGINX FastCGI Cache
  • FastCgi Cache
  • fastcgi_cache zone is unknown

Esteban Borges

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

  • /etc is never the place to put a cache
    /etc is meant to be portable, caches are not

    It’s usually /var/cache/appname/cachename

    • Esteban Borges

      Ideally yes, you are right, but in terms of practice you /etc can be used for cache and works fine as well as /var.

    • That’s the ideal, you are right. However, it works fine at /etc too.

      • Why would you plan to do it wrong in the first place?

  • Marechal Golfinho

    I’m using /var/run/cache to store my cache files, altough everytime the server reboots i have to create the cache folder again… What can i do so this happens automatically??

    • Esteban Borges

      Try changing the cache directory to /var/cache or /etc/nginx/cache

    • Use another directory like /var/cache/nginx or /etc/nginx to store your cache files.

      • Marechal Golfinho

        I used to do it altough i wanted more speed by using the RAM to serve the files

        • You can create another mount point for your RAM directories, outside /var/run. Just make sure your tmpfs mount point is located inside your /etc/fstab file, that should mount it automatically after reboot.

    • you can create it as a tmpfs in fstab

    • /etc/tmpfiles.d/nginx.conf: “d /run/nginx 0775 root root – -”
      /etc/nginx/sites-available/yoursite: “fastcgi_cache_path /run/nginx levels=1:2 keys_zone=WORDPRESS:500m inactive=1440m use_temp_path=off;”

      Runs fast like hell. 😉

  • osfranzitro

    Hello, I am trying to configure fastCGI cache with nginx, but it does not save anything in the destination folder /var/cache/nginx. Is it possible that because I use CDN I’m not frisking anything?


    • Yes. CDN should serve your files after you upload them once.