--- BOOST/README.txt Sun Oct 18 04:49:44 2009 +++ BOOST/README.txt Mon Oct 19 16:52:46 2009 @@ -1 +1 @@ -// $Id: README.txt,v 1.2.2.1.2.5.2.8 2009/10/18 08:49:44 mikeytown2 Exp $ +// $Id: README.txt,v 1.2.2.1.2.5.2.7 2009/09/08 07:22:48 mikeytown2 Exp $ @@ -3,43 +3,87 @@ -DESCRIPTION ------------ -This module provides static page caching for Drupal 6.x, enabling a -potentially very significant performance and scalability boost for -heavily-trafficked Drupal sites. - -For an introduction, read the original blog post at: - http://bendiken.net/2006/05/28/static-page-caching-for-drupal - - -FEATURES --------- -* Maximally fast page serving for the anonymous visitors to your Drupal - site, reducing web server load and boosting your site's scalability. -* On-demand page caching (static file created after first page request). -* Full support for multi-site Drupal installations. - - -REQUIREMENTS ------------- -This version of Boost is designed for Drupal 6.x running with Apache on any platform. -Drupal's clean URLs MUST be enabled and working properly. - -The following modules are recommended. - path - pathauto - globalredirect - transliteration - -In order for the static files to be correctly expired, the Drupal cron job -must be correctly setup to execute more often than, or as often as, the -cache lifetime interval you specify. - -Since the static page caching is implemented with mod_rewrite directives, -Apache version 1.3 or 2.x with mod_rewrite enabled is required (if Drupal's -clean URLs work for you, you're fine; if not, get them working first). -Other web servers, such as Lighttpd, are NOT officially supported at present. -Lighttpd: http://drupal.org/node/150909 -Nginx: http://drupal.org/node/244072 - -INSTALLATION ------------- - 1. Go to [Administer >> Site configuration >> Clean URLs] and ensure that + BOOST MODULE FOR DRUPAL 6.x + --------------------------- + + CONTENTS OF THIS README + ----------------------- + * Description + * Features + * Requirements + * Recommended Modules + * Installation + * System Check & Verify Functions + * Boost Administrative and Stats Blocks + * Configuration Tips + * Important Notes & Troubleshooting + * File System Cache + * How Boost Works + * Dispatch Mechanism + * Limitations + * Boost Handbook Links + * Boost Project & Drupal Links + * Credits + + + DESCRIPTION + ----------- + This module provides static page caching for Drupal 6.x websites. + It provides a significant performance increase as well as + scalability for sites that receive mostly anonymous traffic. + Web pages load very fast from the cache instead of waiting on + PHP and Drupal to serve them from the database. If the page is + not found in the cache, then the request is passed to Drupal. + The built-in crawler makes sure expired content is quickly + regenerated to insure fast page loading at all times. + The guy that is writing this could brag about Boost, + but he will let you do that part. Enjoy! + + + FEATURES + -------- + *** This is a partial list, because it could take the whole page. + * Fast page serving for anonymous visitors to your Drupal website. + * Reduces web server load and increases your site's scalability. + * On-demand page caching (static file created after first page request). + * Uses cron run to trigger cleaning of cached files. + * Built in crawler to automatically regenerate cached files. + * Adjustable cache lifetimes for different parts of the website. + * Supports HTML, XML, CSS, JavaScript, JSON/AJAX. + * Injects HTML comment to provide easy verification of Boost. + * Supports shared, VPS and dedicated hosting. + * Supports sub-directory Installations. + * Full support for multi-site Drupal installations. + + + REQUIREMENTS + ------------ + Boost is designed for Drupal 6.x served by Apache on any platform. + + Drupal's clean URLs MUST be enabled and working properly. + + If the cached files and pages must be cleared at their expired time, + the cron run for Drupal must be correctly setup to execute more often than, + or as often as the cache lifetime you specify in the settings. + + Since the static page caching is implemented with mod_rewrite directives, + Apache version 1.3 or 2.x with mod_rewrite enabled is required (if Drupal's + clean URLs work for you, you're fine; if not, get them working first). + + Other web servers, such as Lighttpd, are NOT officially supported at present. + Lighttpd: http://drupal.org/node/150909 + Nginx: http://drupal.org/node/244072 + + + RECOMMENDED MODULES + ------------------- + Path (Drupal Core) + Global Redirect http://drupal.org/project/globalredirect + Transliteration http://drupal.org/project/transliteration + Pathauto http://drupal.org/project/pathauto + Token http://drupal.org/project/token + + Optional if cron configuration is not available on your server. + Poormanscron -dev http://drupal.org/project/poormanscron + + + INSTALLATION + ------------ + 1. Goto: [Administer > Site configuration > Clean URLs] and ensure that @@ -48,2 +92,2 @@ - 2. Copy all the module files into a subdirectory called - sites/all/modules/boost/ under your Drupal installation directory. + 2. Unzip and upload the module folder (as is) to the sites/all/modules + folder in your Drupal installation directory. @@ -51 +95 @@ - 3. Go to [Administer >> Site building >> Modules] and enable the Boost + 3. Goto: [Administer > Site building > Modules] and enable the Boost @@ -54 +98 @@ - 4. Go to [Administer >> Site configuration >> Performance >> Boost] + 4. Goto: [Administer > Site configuration > Performance > Boost settings] @@ -56,17 +100,22 @@ - cache/www.example.com (keeping the default directory is highly recommended) - and must be writable by the web server: you may need to create the - directory, and set the permissions so it is writable. If you choose to use - gzip, for compression of files cached by Boost, you also specify and may - need to create the folder for this; the default is of the format - cache/gz/www.example.com - - Default minimum cache lifetime setting. As cached pages are created, they - are given an expire by date and time, which is the current date and time - plus the minimum cache lifetime. These dates and times are checked on each - cron run; and if a page is expired, the cache is cleared, and a new cached - version will be created the next time the page is created by an anonymous - user (including bots). - - 5. IMPORTANT: after backing up the original .htaccess file in your Drupal - installation directory, add the rules found in boosted1.txt - right below + cache/normal/www.example.com (keeping the default directory is recommended) + and must be writeable by the web server: you may need to create the + directory, and set the permissions so it is writeable. If you choose to use + gzip, for compression of files cached by Boost, you may also need to + need to create the folder for this. The default is cache/gz/www.example.com + + On the [Administer > Site configuration > Performance > Boost settings] + page is the Default minimum cache lifetime setting. As cached pages are + created, they are given an expire by date and time, which is the current + date and time plus the minimum cache lifetime. These dates and times are + checked on each cron run; and if a page is expired, the cache is cleared, + and a new cached version will be created the next time the page is + called upon by an anonymous user (including bots). The page will be + regenerated by the Boost crawler if enabled on the Boost settings page. + + 5. IMPORTANT: + --- This step is easy and required for Boost to work! --- + Back up the original .htaccess file from your Drupal installation directory + for safe keeping. Copy the custom generated htaccess rule from + [Administer > Site configuration > Performance > htaccess rules generation] + page and paste the rules into the Drupal htaccess file as shown below. + @@ -74 +123 @@ - and above + -------paste the rules right here-------- @@ -76,18 +124,0 @@ - boosted1.txt is found in the sites/all/modules/boost/htaccess/ directory. - The default.txt file shows you the exact placement of where the rules go, - in case your not sure. If you fail to do this step, static page caching - will NOT work! Generated rules can also be found on the Boost Settings page - [Administer >> Site configuration >> Performance >> Boost >> Rules]. If - Drupal is installed in a subdirectory, you have to get the rules from this - page. - - Should you have any trouble getting static pages served using the - boosted1.txt configuration, try the boosted2.txt file before posting a - support issue on drupal.org; or try the different radio buttons on the - admin/settings/performance/boost page under "Boost Apache .htaccess - settings generation." field group. - - (For the technically inclined, the difference between the two supplied - .htaccess templates is due to boosted1.txt relying on SERVER_NAME - versus boosted2.txt using HTTP_HOST. There exist valid use cases for - both, especially in more advanced, multi-site Drupal installations.) @@ -95 +126,17 @@ - 6. Log out from Drupal (or use another browser) to browse around your site + In the boost/htaccess/ folder, the default.txt file shows you + the exact placement of the rules, in case your not sure. + + The module package has 3 htaccess templates included in the Boost/htaccess + folder (boosted1.txt, boosted2.txt and default.txt). These templates may + be helpful in some cases and are good for reference. For the technically + inclined, the difference between the two .htaccess templates is due + to boosted1.txt relying on SERVER_NAME versus boosted2.txt using HTTP_HOST. + There are valid use cases for both in more advanced multi-site installations. + + 6. Goto: [Administer > Site configuration > Performance] + Check and set the Drupal cache settings as desired. + + + SYSTEM CHECK AND VERIFY FUNCTIONS + --------------------------------- + 1. Log out from Drupal (or use another browser) to browse around your site @@ -99,80 +146,121 @@ - the directory you specified for this. The performance settings page shows - how many pages are being cached by Boost, and (for pages Boost cannot - cache) by Drupal core. - - 7. Set $base_url variable in /sites/default/settings.php (line 125 or so) - so cron runs error free and clears the cache properly when invoked like - 'php /path/to/cron.php' or 'drush cron'. This should be something like - http://www.example.com - - Guide for editing settings.php - http://drupal.org/node/367081#comment-1504894 - - 8. Check the status page [Administer >> Reports >> Status report] for any - errors or notices. - - -CONFIGURATION TIPS ------------------- -i18n, Domain module: - Enable - [x] Do not store the cache file path in the database - [x] Flush all sites caches in this database (singe db, multisite) - Disable - [ ] Only allow ASCII characters in path - -Enable XML & AJAX/JSON caches - Enable - [x] Cache .xml & /feed - [x] Cache ajax/json - -Use Cron Crawler - Enable - [x] Overwrite the cached file if it already exits - [x] Expire content in DB, do not flush file. - [x] Enable the cron crawler - - -HOW IT WORKS ------------- -Once Boost has been installed and enabled, page requests by anonymous -visitors will be cached as static HTML pages on the server's file system. -Periodically (when the Drupal cron job runs) stale pages (i.e. files -exceeding the maximum cache lifetime setting) will be purged, allowing them -to be recreated the first time that the next anonymous visitor requests that -page again. - -New rewrite rules are added to the .htaccess file supplied with Drupal, -directing the web server to try and fulfill page requests by anonymous -visitors first and foremost from the static page cache, and to only pass the -request through to Drupal if the requested page is not cacheable, hasn't yet -been cached, or the cached copy is stale. - - -FILE SYSTEM CACHE ------------------ -The cached files are stored (by default) in the cache/ directory under your -Drupal installation directory. The Drupal pages' URL paths are translated -into file system names in the following manner: - - http://mysite.com/ - => cache/mysite.com/_.html - - http://mysite.com/about - => cache/mysite.com/about_.html - - http://mysite.com/about/staff - => cache/mysite.com/about/staff_.html - - http://mysite.com/node/42 - => cache/mysite.com/node/42_.html - -You'll note that the directory path includes the Drupal site name, enabling -support for multi-site Drupal installations. - - -DISPATCH MECHANISM ------------------- -For each incoming page request, the new Apache mod_rewrite directives in -.htaccess will check if a cached version of the requested page should be -served as per the following simple rules: + the directory you specified for this. + The Administer > Performance > Boost settings page shows how many pages + are cached by Boost. + + 2. Check the Drupal status page [Administer > Reports > Status report] + for any errors or notices. + + 3. To check whether you have a cached or dynamic version of a page, + look at the very end of the page's HTML source. You have the cached + version if the last line looks like this: + + + + BOOST ADMINISTRATIVE AND STATS BLOCKS + ------------------------------------- + There are 2 blocks that you can add to help with the administrative + side (status, page configuration), and 1 block to support core stats. + Goto: (administer > Site building > Blocks > List) to place them. + + * Status Block + This block shows the current status of the page as far as Boost is + concerned. It will state if the page is served 'live' or by 'Boost', + the expiration of the page and has a Flush Page button to clear the + page from the cache manually. The block only appears if your not user + 0 and provides useful information about PHP errors on the page. + + * Page configuration Block + This block allows the administrator to set pages individually. + Including setting for minimum cache lifetime(select box), preemptive + cache(on or off), scope(page ID, content type or content container). + + * Stats Block + Drupal's core stats is supported. Configure the "Popular content" block, but + then disable it. Place the "Boost: AJAX core statistics" in its place. If ajax + stats are loading too slowly, copy stats/boost_stats.php to your webroot and + enable "Cache Statistics Block". The cache gets updated on cron runs. + + + CONFIGURATION TIPS + ------------------ + For the (i18n) and the (Domain) modules: + Enable + [x] Do not store the cache file path in the database + [x] Flush all sites caches in this database (singe db, multi-site) + Disable + [ ] Only allow ASCII characters in path + + Enable XML & AJAX/JSON caches + Enable + [x] Cache .xml & /feed + [x] Cache ajax/json + + To Use the Cron Crawler + Enable + [x] Overwrite the cached file if it already exits + [x] Expire content in DB, do not flush file. + [x] Enable the cron crawler + + + IMPORTANT NOTES AND TROUBLESHOOTING + ----------------------------------- + * If cron is not clearing the cache as expected. + Set $base_url variable in /sites/default/settings.php (line 125 or so) + so cron runs error free and clears the cache properly when invoked like + 'php /path/to/cron.php' or 'drush cron'. This should be something like + http://www.example.com + + Guide for editing settings.php + http://drupal.org/node/367081#comment-1504894 + + * If your Drupal URL paths contain non-ASCII characters, you may have to + tweak your locate settings on the server in order to ensure the URL paths + get correctly translated into directory paths in the file system. + You can also turn off the ASCII filter in the Boost Advanced Settings. + OR install the Transliteration module to help fix the characters. + + + FILE SYSTEM CACHE + ----------------- + The cached files are stored (by default) in the cache/normal directory under your + Drupal installation directory. The Drupal pages' URL paths are translated + into file system names in the following manner: + + http://example.com/ + => cache/normal/example.com/index_.html + + http://example.com/about + => cache/normal/example.com/about_.html + + http://example.com/about/staff + => cache/normal/example.com/about/staff_.html + + http://example.com/node/42 + => cache/normal/example.com/node/42_.html + + You'll note that the directory path includes the Drupal site name, enabling + support for multi-site Drupal installations. + + + HOW BOOST WORKS + --------------- + Once Boost has been installed and enabled, page requests by anonymous + visitors will be cached as static HTML pages in the server's file system. + Periodically (when the Drupal cron runs) stale or expired pages + (i.e. files or pages exceeding the maximum cache lifetime setting) + will be purged, allowing them to be recreated the first time that the + next anonymous visitor requests that page again. If the Cron Crawler + is enabled, the files and pages will be regenerated automatically. + + New rewrite rules are added to the .htaccess file supplied with Drupal, + directing the web server to try and fulfill page requests by anonymous + visitors first and foremost from the static page cache, and to only pass the + request through to Drupal if the requested page is not cacheable or hasn't yet + been cached. + + + DISPATCH MECHANISM + ------------------ + For each incoming page request, the new Apache mod_rewrite directives in + .htaccess will check if a cached version of the requested page should be + served as per the following simple rules: @@ -200,48 +288,60 @@ -IMPORTANT NOTES ---------------- -* To check whether you got a static or dynamic version of a page, look at - the very end of the page's HTML source. You have the static version if the - last line looks like this: - -* If your Drupal URL paths contain non-ASCII characters, you may have to - tweak your locate settings on the server in order to ensure the URL paths - get correctly translated into directory paths on the file system. You can also - turn off the ASCII filter under Cache -> Advanced on the performance >> boost page. -* Drupal's core stats is supported. Configure the "Popular content" block, but - then disable it. Place the "Boost: AJAX core statistics" in its place. If ajax - stats are loading too slowly, copy stats/boost_stats.php to your webroot and - enable "Cache Statistics Block". The cache gets updated on cron runs. - - -LIMITATIONS ------------ -* Only anonymous visitors will be served cached versions of pages; - authenticated users will get dynamic content. This will limit the - usefulness of this module for those community sites that require user - registration and login for active participation. -* In contrast to Drupal's built-in caching, static caching will lose any - additional HTTP headers set for an HTML page by a module. This is unlikely - to be problem except for some very specific modules and rare use cases. -* Web server software other than Apache is not supported at the moment. - Adding Lighttpd support would be desirable but is not a high priority for - the author at present (see TODO.txt). (Note that while the LiteSpeed web - server has not been specifically tested by the author, it may, in fact, - work, since they claim to support .htaccess files and to have mod_rewrite - compatibility. Feedback on this would be appreciated.) - - -BUG REPORTS ------------ -Post feature requests and bug reports to the issue tracking system at: - - - - -CREDITS -------- -Developed and maintained by Arto Bendiken -Drupal 6.x maintained by Mike Carper -Ported to Drupal 6.x by Ben Lavender -Ported to Drupal 5.x by Alexander I. Grafov -Miscellaneous contributions by: Jacob Peddicord, Justin Miller, Barry -Jaspan. + LIMITATIONS + ----------- + * Only anonymous visitors will be served cached versions of pages; + authenticated users will get dynamic content. This will limit the + usefulness of this module for those community sites that require user + registration and login for active participation. + + * In contrast to Drupal's built-in caching, static caching will lose any + additional HTTP headers set for an HTML page by a module. This is unlikely + to be problem except for some very specific modules and rare use cases. + + * Web server software other than Apache is not supported at the moment. + Adding Lighttpd support would be desirable but is not a high priority for + the developer at present (see TODO.txt). (Note that while the LiteSpeed web + server has not been specifically tested by the developer, it may, in fact, + work, since they claim to support .htaccess files and to have mod_rewrite + compatibility. Feedback on this would be appreciated.) + + + HANDBOOK PAGES + -------------- + Boost handbook http://drupal.org/node/545664 + + Installation & Settings http://drupal.org/node/545908 + + Boost Tips & Tricks http://drupal.org/node/583264 + + FAQ & Future Features http://drupal.org/node/546134 + + Using & Blogging About Boost http://drupal.org/node/546834 + + + BOOST PROJECT & DRUPAL LINKS + ---------------------------- + Boost project page http://drupal.org/project/boost + + ** Post feature requests and bug reports: + Boost issue que http://drupal.org/project/issues/boost + + ** The Drupal 'post installation' forum: + Drupal Help Forum http://drupal.org/forum/22 + + ** The original blog post about Boost: + http://bendiken.net/2006/05/28/static-page-caching-for-drupal + + CREDITS + ------- + Originally Developed by Arto Bendiken(arto) + + Ported to Drupal 5.x by Alexander I. Grafov(axel) + + Ported to Drupal 6.x by Ben Lavender(bhuga) + + Miscellaneous contributions by Jacob Peddicord, Justin Miller & Barry Jaspan. + + 6.x Developer and Maintainer, Mike Carper(mikeytown2) of + + + END OF FILE + -----------