Cache Flush Service

Introduction

If a web site is cached and distributed by Web Site Delivery Service like Akamai or Amazon CloudFront these services need to be informed when a page is updated so that the delivery services are reading the new content and distribute it.This is called the invalidation of a page.
The handling of new pages can be done either by adding a hook into the Replication Events inside CQ or by an external service that listens to changes on the CQ Dispatcher Cache. The advantage of the 2nd approach is that it does not impede  on the performance of CQ and it is possible to trigger an invalidation by touching the files in questions.

Prerequisites

First the CQ Dispatcher must be installed and configured so that it is started when Apache starts up. In this page we are referring to the directory where CQ Dispatcher places it files as <docroot> because it is also the Apache Document Root. Then you need access to your delivery service of one of these services:

• Akamai: you need to have the username, password and the root URI where the pages are provided from
• Amazon CloudFront: you need the access key and secret key (which is not the username / password) as well as the distribution id

Finally download and extract the attached service.wrapper.zip attachment which contains the code and libraries.

Installation

Obtain the service.wrapper ZIP file (see above), extract it and place it anywhere you like. We will refer as <service.wrapper> from now. This setup does support Mac OS X, Linux and Windows X86 out of the box. If you need to install this on other boxes then head over to [http://wrapper.tanukisoftware.com/doc/english/download.jsp] and download the setup for your environment. For Linux or Windows you only need to copy its native library (/lib) into this /lib directory. The scripts should work because they automatically check for different architectures. For other systems you might need to copy the native library (/lib), the program (/bin) and the startup script (/src/bin) which must be edited to reflect your environment. To make it easier to support different platforms I suffixed the startup script files (as well as the startup program) with the OS name. This means when it says cache-flusher-service-mac-os-x to cache-flusher-service-linux (for linux) etc.

In order to start the service is must be configured first which should be done and then the service should be tested on the console:

If the service comes up and starts waiting for changes then you can go ahead and "touch" a file which should trigger an invalidation request. If that was successful you can shut down the service with ctrl-c and install it as run level service (startup service) so that it is started when the box comes up:

This will install the service inside the startup directory like /Library/StartupDaemons on Mac OS X or /etc/init.d on Linux. Please start the service through this and check out the <service.wrapper>/logs/wrapper.log file to see if you startup just fine.

Configuration

Inside the <service.wrapper>/bin contains the configuration directory called cache.flusher.configuration.json. This file need to be adjusted so that it work. This file is an example for the Amazon CloudFront but inside the <service.wrapper>/bin/examples contains an example for Akamai as well. These are the things that need to be configured:

1. rootPath: set the value to the "<docroot>"
2. Decide if you want to use a File Checksum or the File Size to decide which files did change. The class name for the File Size checker is: FileSizeChecker within the same package
3. Adjust the Cache Flusher to either Amazon or Akamai. Each have different properties but these are the common:
   1.  batchSize: The maximum number of pages send in one invalidation request. This makes sure the invalidations is not rejected by the Delivery Service. Default is set to 100.
   2. sleepPeriod: The maximum time in milliseconds the service is collecting new invalidation request before sending it to the delivery service. The request is only made if there are any changed files. The actual sleeping time is this time minus the time it took for the previous request. The default is set to 10 seconds.
4. Settings for Amazon CloudFront:
   1.  accessKey: the access key generated on the user administration site. This is not the username.
   2.  secretKey: the secret key generated by the step above. This is not the password.
   3.  distributionId: the distribution id of your side given by Amazon.
5. Settings for Akamai:
   1. userName: the user name of the user having permission to send invalidation requests
   2. password: the password of the user above
   3. rootUri: the root URI of the distributed site. Keep in mind that the root URI as well as the relative path of the file inside the dispatcher cache will determine the path of the page invalidated.
   4. email: email address of the user above
   5. domainName: the domain of the changes. It can be STAGING, PRODUCTION or DEFAULT

The properties with a default value can be removed and the default will be used. All others will make the service crash if they are missing or invalid.