Configuring Acquia Purge for Drupal 7

Issue

How do I configure Acquia Purge? (This article applies to the Drupal 7 version of Acquia Purge) 

Resolution

When you need to purge cache selectively, the Acquia Purge module is one of your best choices on Acquia Cloud. There are a number of steps you can take to optimize the usage of Acquia Purge and ensure that it is doing the job in the best way possible for your site.

Evaluating non-purged content

Every website is unique and there will be sections on your site that won't be caught by the Cache Expiration module's automatic detection. Ensuring the best usage for a given site requires a test and fine-tune phase before you bring this into production.

The Cache Expiration module detects ordinary changes (including creation, updates, or deletion) to content (such as nodes, comments, and user accounts). Whenever changes are made, the module provides the HTTP path for Acquia Purge to clear. In practice, however, the Cache expiration module can detect only about 90% of your website's content changes without additional configuration.

To evaluate the Cache Expiration module with your website, test your website as an anonymous user on either your Development or Staging environment. To do this anonymous user testing, you can use your browser's incognito browsing features (if available), or a different browser entirely, to look for changes that aren't detected by the Cache Expiration module. Make small page changes and then observe the behavior in the incognito browser window. For example, if you change the title of a content node, examine the pages that refer to that node to ensure that they display the updated title, including news sections and R feeds. Note any HTTP paths for pages that are having problems. The following are some examples that you might have:

• news
• news?page=1
• products
• products/toys
• contact
• about-us/team-overview

There are often common elements to pages that are not automatically purged. Pay close attention to any special caching that might be set up for Drupal, especially the following:

• Although the page is usually cleared by the Cache Expiration module, in some cases it may not be. Be sure to direct additional attention to it.
• The Views module allows you to aggregate content, either directly on paths (such as /news), in blocks, or in RSS feeds. Because the Cache Expiration module cannot easily detect where a changed piece of content is displayed in a view, views are not automatically purged.
• Blocks can be placed on one or more pages on your site and show dynamic content (such as a view). Watch for blocks with dynamic content and note the pages on which they are rendered. One example is a "product of the day" block displayed on both the and /products.
• The Contact page itself does not show any content from your site, but can contain blocks that use dynamic content.
• Pages generated by custom code or modules are less likely to be detected. Whenever your site actively exposes pages through Drupal's hook_menu system, include them in your tests.

Purging identified paths

After you have identified pages that aren't purged, you can configure Acquia Purge to handle them. To do this, you'll use the Rules module and the Clear pages on Acquia Cloud rule action. You can then trigger the rule based on whatever condition you set. As a best practice, configure the rule to purge specific pages often instead of regenerating the cache for your entire site every few minutes.

Select from the following choices to handle the custom paths collected during testing:

• Purge all of the paths after every content change by using one rule. Although this is the simplest method, it can cause large amounts of unnecessary cache rebuilding.
• Create multiple rules that purge relevant paths. For example, a rule specifically for news nodes could clear all of the /news* paths. This requires more configuration up front, but is more efficient for your site over time.
• Write custom code that calls the Acquia Purge API upon events. While this can provide very specific results, it can also require significantly more development effort. For more information, see the Acquia Purge FAQ.

Encouraging Varnish to serve your site

Drupal provides the Expiration of cached pages setting (page_cache_maximum_age), which controls how long generated pages and other ts can be kept in a cache like Varnish. Usually this setting is on the low end, a habit especially seen on news websites. You can set this by going to Admin > Configuration > Performance and changing the Expiration of cached pages menu.

If this setting is low, your web servers and Drupal have to do more work and the load balancer is less effective. This is why proactive purging exists. With the expire and Acquia Purge modules tested and tuned, you can increase this value. Sites vary, but we suggest setting this value to a minimum of 6 hours once you have identified an ideal configuration for purging your site and have completed successful testing of purging. The higher this value is set, the more efficient the process becomes.

Note for Shield module users

The Shield module sets up basic HTTP authentication, which is incompatible with Varnish and prevents Acquia Purge from working. Attempting to use the two modules together may also return unexpected errors.

Using Acquia Purge in production

After you've made your changes and finished testing in your development and staging environments, be sure to properly configure your production environment in an identical fashion and perform similar validation tests.

Regularly examine and test your website's cache clearing rules to ensure that they're working properly and that new pages are not failing to clear. If you see a specific page that needs to be cleared from the cache, you can use the administrative interface to do a spot clear of a cached page.

Note

This page may be available only if you are on an Acquia Cloud site.

To perform a spot purge:

• Navigate to Configuration > Performance > Manual Purge.
• Under Paths to be purged, enter a path value in the text box.
• If there is more than one path to purge, click Add.
• When all of the paths are added, click Refresh.

There are also two blocks that can be made available on every page, for administrative purposes. These make it easy to purge a single path or page quickly:

• Manual purge form (current page)
• Manual purge form (paths)

Configuration variables

By strict design this module has no UI-exposed settings or configuration forms. The reason behind this philosophy is that, as a utility module, only site administrators should be able to change settings and these changes should be traceable in the settings.php file. Although Acquia Purge is intended to be turnkey, with minimal configuration, the following options exist:

$conf['acquia_purge_allriskmode'] = TRUE;

$conf['acquia_purge_base_path'] = '/sub/';

$conf['acquia_purge_cron'] = TRUE;

$conf['acquia_purge_errorlimit'] = 500;

Drush commands for Acquia Purge

These are the current Acquia Purge commands available using Drush. Several of these commands have been presented in use cases previously.

• ap-diagnosis - Perform a series of diagnostic self-tests
• ap-domains - List all domains Acquia Purge will purge against
• ap-forget - Forget all scheduled purges and empty the queue
• ap-list - List all the items that are in the queue
• ap-process - Purge all queued items from the command line
• ap-purge - Purge a specified path from your balancers

Module questions and comments

If you have any questions or comments about the module for its maintainer, or you've found a bug or some other issue, you can file an issue in the Acquia Purge issue queue.