How to enable CDN caching

Learn how to enable the caching of HTTP responses in AEM as a Cloud Service’s CDN. The caching of responses is controlled by Cache-Control, Surrogate-Control, or Expires HTTP response cache headers.

These cache headers are typically set in AEM Dispatcher vhost configurations using mod_headers, but can also be set in custom Java™ code running in AEM Publish itself.

Default caching behavior

When custom configurations are NOT present, the default values are used. In following screenshot, you can see the default caching behavior for AEM Publish and Author when an AEM Project Archetype based mynewsite AEM project is deployed.

Review the AEM Publish - Default cache life and AEM Author - Default cache life for more information.

In summary, AEM as a Cloud Service caches most of the content types (HTML, JSON, JS, CSS, and Assets) in AEM Publish and a few content types (JS, CSS) in AEM Author.

Enable caching

To change the default caching behavior, you can update the cache headers in two ways.

Let’s review each of these options.

Dispatcher vhost configuration

This option is the recommended approach for enabling caching however it is only available for AEM Publish. To update the cache headers, use the mod_headers module and <LocationMatch> directive in the Apache HTTP Server’s vhost file. The general syntax is as follows:

<LocationMatch "$URL$ || $URL_REGEX$">
    # Removes the response header of this name, if it exists. If there are multiple headers of the same name, all will be removed.
    Header unset Cache-Control
    Header unset Surrogate-Control
    Header unset Expires

    # Instructs the web browser and CDN to cache the response for 'max-age' value (XXX) seconds. The 'stale-while-revalidate' and 'stale-if-error' attributes controls the stale state treatment at CDN layer.
    Header set Cache-Control "max-age=XXX,stale-while-revalidate=XXX,stale-if-error=XXX"

    # Instructs the CDN to cache the response for 'max-age' value (XXX) seconds. The 'stale-while-revalidate' and 'stale-if-error' attributes controls the stale state treatment at CDN layer.
    Header set Surrogate-Control "max-age=XXX,stale-while-revalidate=XXX,stale-if-error=XXX"

    # Instructs the web browser and CDN to cache the response until the specified date and time.
    Header set Expires "Sun, 31 Dec 2023 23:59:59 GMT"
</LocationMatch>

The following summarizes the purpose of each header and applicable attributes for the header.

Review the staleness and revalidation details for more information.

Example

To increase the web browser and CDN cache life of the HTML content type to 10 minutes without stale state treatment, follow these steps:

However, to have different values for web browser and CDN cache life, you can use the Surrogate-Control header in above example. Likewise to expire the cache at a specific date and time, you can use the Expires header. Also, using the stale-while-revalidate and stale-if-error attributes, you can control the stale state treatment of the response content. The AEM WKND project has a reference stale state treatment CDN cache configuration.

Similarly, you can update the cache headers for other content types (JSON, JS, CSS, and Assets) as well.

Custom Java™ code

This option is available for both AEM Publish and Author. However, it is not recommended to enable caching in AEM Author and keep the default caching behavior.

To update the cache headers, use the HttpServletResponse object in custom Java™ code (Sling servlet, Sling servlet filter). The general syntax is as follows:

// Instructs the web browser and CDN to cache the response for 'max-age' value (XXX) seconds. The 'stale-while-revalidate' and 'stale-if-error' attributes controls the stale state treatment at CDN layer.
response.setHeader("Cache-Control", "max-age=XXX,stale-while-revalidate=XXX,stale-if-error=XXX");

// Instructs the CDN to cache the response for 'max-age' value (XXX) seconds. The 'stale-while-revalidate' and 'stale-if-error' attributes controls the stale state treatment at CDN layer.
response.setHeader("Surrogate-Control", "max-age=XXX,stale-while-revalidate=XXX,stale-if-error=XXX");

// Instructs the web browser and CDN to cache the response until the specified date and time.
response.setHeader("Expires", "Sun, 31 Dec 2023 23:59:59 GMT");