NGINX Configuration

Below you will find detailed NGINX configuration recommendations for the features provided by this library. The examples are tested with NGINX version 1.4.6.

NGINX cache is a set of key/value pairs. The key is built with elements taken from the requests (URI, cookies, http headers etc) as specified by proxy_cache_key directive.

When we interact with the cache to purge/refresh entries we must send to NGINX a request which has the very same values, for the elements used for building the key, as the request that create the entry. In this way NGINX can build the correct key and apply the required operation to the entry.

By default NGINX key is built with $scheme$proxy_host$request_uri. For a full list of the elements you can use in the key see this page from the official documentation.

Purge

NGINX does not support purge functionality out of the box but you can easily add it with ngx_cache_purge module. You just need to compile NGINX from sources adding ngx_cache_purge with --add-module.

You can check the script install-nginx.sh to get an idea about the steps you need to perform.

Then configure NGINX for purge requests:

worker_processes 4;

events {
    worker_connections 768;
}

http {

    log_format proxy_cache '$time_local '
        '"$upstream_cache_status | X-Refresh: $http_x_refresh" '
        '"$request" ($status) '
        '"$http_user_agent" ';

    error_log /tmp/fos_nginx_error.log debug;
    access_log /tmp/fos_nginx_access.log proxy_cache;

    proxy_cache_path /tmp/foshttpcache-nginx keys_zone=FOS_CACHE:10m;

    # Add an HTTP header with the cache status. Required for FOSHttpCache tests.
    add_header X-Cache $upstream_cache_status;

    server {

        listen 127.0.0.1:8088;

        server_name localhost
                    127.0.0.1
                    ;

        proxy_set_header   Host             $host;
        proxy_set_header   X-Real-IP        $remote_addr;
        proxy_set_header   X-Forwarded-For  $proxy_add_x_forwarded_for;

        location / {
            proxy_cache FOS_CACHE;
            proxy_pass http://localhost:8080;
            proxy_set_header Host $host;
            proxy_cache_key $uri$is_args$args;
            proxy_cache_valid 200 302 301 404 1m;

            proxy_cache_purge PURGE from 127.0.0.1;

            # For refresh
            proxy_cache_bypass $http_x_refresh;
        }

        # This must be the same as the $purgeLocation supplied
        # in the Nginx class constructor
        location ~ /purge(/.*) {
            allow 127.0.0.1;
            deny all;
            proxy_cache_purge FOS_CACHE $1$is_args$args;
        }
    }
}

Please refer to the ngx_cache_purge module documentation for more on configuring NGINX to support purge requests.

Refresh

If you want to invalidate cached objects by forcing a refresh you have to use the built-in proxy_cache_bypass directive. This directive defines conditions under which the response will not be taken from a cache. This library uses a custom HTTP header named X-Refresh, so add a line like the following to your config:

            proxy_cache_bypass $http_x_refresh;

Debugging

Configure your Nginx to set a custom header (X-Cache) that shows whether a cache hit or miss occurred:

add_header X-Cache $upstream_cache_status;