Nginx configured as a third party internal gateway proxy with cache

default.conf.template

# To be use with https://hub.docker.com/_/nginx or https://hub.docker.com/r/nginxinc/nginx-unprivileged
# COPY this file to /etc/nginx/templates/default.conf.template

# For env var substitution, see "Using environment variables in nginx configuration" at https://hub.docker.com/_/nginx
# Example values:
# environment:
#   - CACHE_FILES_PATH=/mnt/cache
#   - CACHE_FILES_MAX_SIZE=1g
#   - CACHE_MEMORY_SIZE=10m
#   - CACHE_VALID_TIME=1m
#   - CACHE_INACTIVE_MAX_TIME=1w
#   - THIRD_PARTY_URL=https://example.com/
    
proxy_cache_path $CACHE_FILES_PATH/complete
    levels=1:2
    keys_zone=third_party_cache:$CACHE_MEMORY_SIZE
    max_size=$CACHE_FILES_MAX_SIZE
    inactive=$CACHE_INACTIVE_MAX_TIME
    use_temp_path=on;

server {

    listen 8080;
    listen [::]:8080;

    location / {
        opentracing off;
        return 200 'Up and running!';
        add_header Content-Type text/plain;
    }

    location /api/oauth/v1/ {
        proxy_pass $THIRD_PARTY_URL;
    }

    location /api/rest/v1 {
        proxy_cache third_party_cache;

        # This is linked to use_temp_path=on.
        # Ensures files in $CACHE_FILES_PATH/complete are fully written so they can safely be copied to an s3 bucket.
        # This should be in the same file system as $CACHE_FILES_PATH/complete to rely on file renaming and not file copy.
        proxy_temp_path $CACHE_FILES_PATH/tmp;

        # We need to ignore all this headers otherwise nginx will not cache responses,
        # see http://nginx.org/en/docs/http/ngx_http_proxy_module.html#proxy_cache_valid
        proxy_ignore_headers Cache-Control Expires Set-Cookie;

        # Override cache validity for status codes 200, 301 and 302 responses. See:
        # http://nginx.org/en/docs/http/ngx_http_proxy_module.html#proxy_cache_valid
        proxy_cache_valid $CACHE_VALID_TIME;

        proxy_cache_revalidate on;

        # Ensures we always use a cached response if it's available and do not wait for
        # the response from the upstream server to serve a response to the client (even
        # if the cached response is expired)
        proxy_cache_use_stale error timeout updating http_500 http_502 http_503 http_504;
        proxy_cache_background_update on;
        
        # While proxy_cache_background_update looks good, it has a limitation ensuring
        # there is only one background request to the upstream server by client connection!
        # The following line ensures we get one client connection by request, thus ensuring the
        # proxy_cache_use_stale and proxy_cache_background_update behave as expected.
        # See: https://trac.nginx.org/nginx/ticket/1723
        keepalive_timeout 0;

        # Do as few as possible requests to the upstream server
        proxy_cache_lock on;

        proxy_pass $THIRD_PARTY_URL;

        add_header upstream-cache-status $upstream_cache_status;

        # Rewrite all third party self references in responses (usefull for pagination links for example).
        # This will replace 'https:\/\/example.com' by 'http://third-party-gateway'
        sub_filter 'https:\/\/$proxy_host' '$scheme://$http_host';
        # Required because sub_filter is incompatible with gzip reponses:
        proxy_set_header Accept-Encoding "";
        sub_filter_last_modified on;
        sub_filter_once off;
        sub_filter_types application/json;
    }
}