What is a cacheable item?

First, let's cover the kind of web items that can and should be cached.

• static content (images and JavaScript)
• content for anonymous users. Items (such as Plone-generated HTML) can be cached with little danger.
• selected content for logged in users.

Warning Incorrect configuration of caching has the potential for authenticated requests being cached (which is bad). Generally, the two Plone products discussed below have sensible policies about not caching authenticated requests. Nonetheless, if you are customizing your cache settings in Plone Site Setup --> Caching, it's a good idea to confirm that authenticated requests are not being cached. Also, it's a good idea to purge your cache or your proxy definition after you make a change to your cache settings on the Plone side.

First Step: Install and Activate a Caching Add-On

Before you can cache, you must install and activate a product in Plone specifically for caching. With this product you can configure and customize cache settings. Currently the caching add-on of choice is plone.app.caching. (The older Plone caching product CacheFu is currently deprecated). Complete instructions for how to install,enable and configure this add-on are located here at http://plone.org/products/plone.app.caching.

After you have installed and enabled plone.app.caching, you can do this basic configuration.

1. Go to Plone Site Setup --> Caching.
2. On Global Settings, choose Enable caching.
3. Go to the upper tab on this configuration screen (green in the default style defaults). Choose Import Settings.
4. Choose to import one of the profiles. Either With caching proxy or With caching proxy (and split-view caching) will be appropriate.

That should be sufficient for Enfold Proxy to start caching content.

Note: if you wish to enable split-level caching, you need to add an extra line to your eep.ini file. Read more about split-level caching.

List of HTTP Headers supported by Enfold Proxy

See the HTTP Header Reference Guide.

Enable Cache in your Proxy Definition

By default, when you create a proxy definition in EP, caching is enabled. However, you might need to change your settings to suit your hardware.

See a description of each cache setting.

Enfold Proxy will keep a lot of "stale" cached files inside the cache directory corresponding to a specific proxy definition. These stale cache files will accumulate in the cache directory until it approaches the maximum cache size. That is actually a good thing. For example, a type of content might cached for one hour. After one hour (or even after five years), whenever the browser requests the same resource, EP will check with Plone and ask, "is this stale item still valid?" Plone will give one of two responses. Either:

• Plone will reply, "it's still good." (In this case, EP will return the stale item to the browser and update its own records to indicate that this stale cache is now valid. This process is called, revalidating the cache). The HTTP headers to the user will say: X-Cache: HIT from www.originalfunsite.com
• Plone will reply, "Nope. That's an outdated version." (In this case, Plone will send the updated version to Enfold Proxy, which will pass it on to the browser and also replace the outdated version with the newer version). X-Cache: MISS from www.originalfunsite.com .

Enfold Proxy now has an easy button in its interface to purge cached items for proxy definition(s).

Enable split-level caching in the Proxy Definition

If your Plone caching add-on supports it, it is generally a good idea to enable split-level caching for a proxy definition. It only adding a single line to the eep.ini file. Read more about split-level caching.

Next Step: Verify that Your Cache Settings are in Effect

The easiest way to verify your cache settings is to view the Enfold Proxy logs themselves. That allows you to see the responses from Plone and also prevents browser issues from misleading you. When viewing the Enfold Proxy logs, be sure to activate the new Headers log level which is easier to read than typical HTTP headers.

To verify that caching is taking place from the browser, look for this line in your HTTP response header: X-Cache: HIT from www.originalfunsite.com

• If you see X-Cache: HIT, then yes, Enfold Proxy has sent you a cached version of this content item.
• If you see X-Cache: MISS, then no, Enfold Proxy has sent you this content which was not in its cache.

Generally HIT's indicate successful caching.

Keep in mind that X-Cache: MISS is not always a bad thing. For example, if logged in as an administrator, many resources will not be cached on purpose. It's best to test as an anonymous web surfer (i.e., someone who is not logged in). If an item contains a modification, then a MISS reply is mandatory. Also, object-based caching (like XSLT caching )doesn't modify these headers, so EP can be properly caching XSLT pages and still be sending out X-Cache: MISS headers.

Careful: When testing, it's a good idea to use two different browsers. In Browser A (such as Internet Explorer), log in as Admin. In Browser B (i.e., Firefox), log in as anonymous or as a logged in user. It's also important to clear cache the right way and even to close the browser entirely (if you don't, the http headers you see won't be accurate). Consult the troubleshooting checklist for caching.

To see the HTTP headers directly, see Tools for Viewing Headers . You should probably pick two or three sample items to check for headers. Anything will do, but at least one should be a graphic and one should be a Zope page (such as http://www.originalfunsite.com/events ).

Optimize Cache Settings and Measure Caching Performance

(See also: Caching Goals and Strategies).

Many of your cache settings can be tweaked in whatever Plone product you are using to cache web items. Note: if you suspect your cache settings are misconfigured, purging your cache can often eliminate the problem. (See Purging Cache).

But EP also offers some cache settings to tweak.

Here are some default settings for each proxy definition as set by Enfold Proxy:

• Maximum Size of the Cache: 20 gigabytes for each proxy definition
• Maximum number of items in the cache for each proxy definition: 50,000
• Maximum size of an item which can be cached: 100K
• Default-Age: 0

The main thing you can adjust here is storage amount and item size. The larger the storage amount you have, the more cacheable items EP can keep at once. Increasing maximum item size is recommended if your Plone server returns a lot of web items (which is not the same thing as "web pages") over 100K. If the maximum is increased to a very large size, this will also consume RAM on the machine with EP. Also, when you cache larger files, that will cause the maximum size of the cache to fill up more quickly. Theoretically, if your cache directory for your proxy definition is always at maximum and the hit percentage is declining, that could indicate you need to increase your maximum here.

If Plone includes max-age=0 in the headers, EP will store cachable items and always check to make sure if it is current before serving cached content to the browser. Even so, EP will not cache an item which is forbidden to be cached (according to Plone or whatever Plone Product is setting these commands). (For more about how EP handles HTTP headers, see the Cache Headers Reference.

If you check Enfold Proxy's cache.log messages for your proxy definition (and set the log level to Information), you will see every minute or so some statistics about caching:

2008-02-18 10:31:45,250|cache.host originalfunsite|STATS|3500|2856|Cache statistics:
        gets: 88, hits: 65 (33 validated), misses: 23 (0 uncachable)
        hitrate: 73% (58% excluding validations)
        size: 1943668 bytes, 324 items

The most important number here is the 58% in parenthesis. It refers to requests that EP returned without forwarding it to Plone (thus resulting in the most time-saving). The 73% number includes those occasions when the item was stale and EP needed to make a conditional request to Plone. So 15% (i.e., 73-58) is the percentage of times when EP had to revalidate stale cache by checking with Plone. These revalidation requests generally do not result in significant time savings, so for all practical purposes the only number you need to worry about is the number in parenthesis.

To improve this percentage, you would need to configure caching to allow EP to serve cached items without validating them. In general this is done either by specifying a "max-age" or an expires date in the future (ensuring that the content item will never expire). You can increase the value of max-age to increase the amount of time necessary to pass before the browser will revalidate it.

Made a mistake? Purging Cached Content will prevent the person's browser from relying on a cached version of content on Enfold Proxy. Doing this is helpful for testing your cache settings.

Note: Another option which improves performance is split-level caching. Read more about split-level caching.

The cache directory

The proxy allows you to configure the directory where cached items are stored for a particular proxy definition.

1. Open EP configuration tool
2. Select your proxy definition. Select the Caching tab.
3. Leave this blank if you want your cache directory to exist under the application directory. The directory will be created if it does not exist. If you wish to put your cache files elsewhere, you should copy the complete path to the directory here (e.g., C:\My Documents\proxy definition 1\cache).

Important: IIS must be restarted before a change to this option will take effect.

When you change the cache_directory, the old cache is not migrated to the new location (i.e., the old cache remains and a new empty cache is created at the new location.)

Migrating your cache to a different place:

1. Stop IIS.
2. Move the cache directory into a new location.
3. Copy the absolute path into the Cache Directory field of your proxy definition. Press the Save button.
4. restart IIS.

After you press Save, Enfold Proxy will make the cache directory writable by the user running Enfold Proxy.

IIS6 Considerations

For normal operation, the Enfold Proxy process requires access to the logs and cache directories. The Network Service account under IIS6 does not have this permission. Even if Enfold Proxy has no access to these directories it will still run as a proxy - although no logging information will be written, and it will not operate as a cache.

The Enfold Proxy configuration tool attempts to ensure that directory permissions are set appropriately, but depending on local policies, this may not be effective. It may be necessary to manually configure the IIS application pool or the permissions on the directories to enable these facilities.