README.txt

   1
   2  BOOST MODULE FOR DRUPAL 6.x
   3  ---------------------------
   4
   5  CONTENTS OF THIS README
   6  -----------------------
   7    * Description
   8    * Features
   9    * Requirements
  10    * Recommended Modules
  11    * Installation
  12    * System Check & Verify Functions
  13    * Boost Administrative and Stats Blocks
  14    * Configuration Tips
  15    * Important Notes & Troubleshooting
  16    * File System Cache
  17    * How Boost Works
  18    * Dispatch Mechanism
  19    * Limitations
  20    * Boost Handbook Links
  21    * Boost Project & Drupal Links
  22    * Credits
  23
  24
  25  DESCRIPTION
  26  -----------
  27  This module provides static page caching for Drupal 6.x websites.
  28  It provides a significant performance increase as well as
  29  scalability for sites that receive mostly anonymous traffic.
  30  Web pages load very fast from the cache instead of waiting on
  31  PHP and Drupal to serve them from the database. If the page is
  32  not found in the cache, then the request is passed to Drupal.
  33  The built-in crawler makes sure expired content is quickly
  34  regenerated to insure fast page loading at all times.
  35     The guy that is writing this could brag about Boost,
  36  but he will let you do that part. Enjoy!
  37
  38
  39  FEATURES
  40  --------
  41  *** This is a partial list, because it could take the whole page.
  42  * Fast page serving for anonymous visitors to your Drupal website.
  43  * Reduces web server load and increases your site's scalability.
  44  * On-demand page caching (static file created after first page request).
  45  * Uses cron run to trigger cleaning of cached files.
  46  * Built in crawler to automatically regenerate cached files.
  47  * Adjustable cache lifetimes for different parts of the website.
  48  * Supports HTML, XML, CSS, JavaScript, JSON/AJAX.
  49  * Injects HTML comment to provide easy verification of Boost.
  50  * Supports shared, VPS and dedicated hosting.
  51  * Supports sub-directory Installations.
  52  * Full support for multi-site Drupal installations.
  53
  54
  55  REQUIREMENTS
  56  ------------
  57  Boost is designed for Drupal 6.x served by Apache on any platform.
  58
  59  Drupal's clean URLs MUST be enabled and working properly.
  60
  61  If the cached files and pages must be cleared at their expired time,
  62  the cron run for Drupal must be correctly setup to execute more often than,
  63  or as often as the cache lifetime you specify in the settings.
  64
  65  Since the static page caching is implemented with mod_rewrite directives,
  66  Apache version 1.3 or 2.x with mod_rewrite enabled is required (if Drupal's
  67  clean URLs work for you, you're fine; if not, get them working first).
  68
  69  Other web servers, such as Lighttpd, are NOT officially supported at present.
  70  Lighttpd: http://drupal.org/node/150909
  71  Nginx: http://drupal.org/node/244072
  72
  73
  74  RECOMMENDED MODULES
  75  -------------------
  76     Path (Drupal Core)
  77
  78     Global Redirect     http://drupal.org/project/globalredirect
  79
  80     Transliteration     http://drupal.org/project/transliteration
  81
  82     Pathauto            http://drupal.org/project/pathauto
  83
  84     Token               http://drupal.org/project/token
  85
  86   Optional if cron configuration is not available on your server.
  87     Poormanscron 1.1 or 2.0     http://drupal.org/project/poormanscron
  88
  89   If enabled [x] Clear all cached pages referenced via CCK with a node...
  90     The node referrer module is recommended.
  91     Node Referrer       http://drupal.org/project/nodereferrer
  92
  93
  94  INSTALLATION
  95  ------------
  96   1. Goto: [Administer > Site configuration > Clean URLs] and ensure that
  97      Drupal's clean URLs are enabled and working correctly on your site.
  98
  99   2. Unzip and upload the module folder (as is) to the sites/all/modules
 100      folder in your Drupal installation directory.
 101
 102   3. Goto: [Administer > Site building > Modules] and enable the Boost
 103      module. You will find it in the section labeled "Caching".
 104
 105   4. Goto: [Administer > Site configuration > Performance > Boost settings]
 106      Specify the cache directory, which should be something like
 107      cache/normal/www.example.com (keeping the default directory is recommended)
 108      and must be writeable by the web server: you may need to create the
 109      directory, and set the permissions so it is writeable.
 110
 111      On the [Administer > Site configuration > Performance > Boost settings]
 112      page is the Default maximum cache lifetime setting. As cached pages are
 113      created, they are given an expire by date and time, which is the current
 114      date and time plus the maximum cache lifetime. These dates and times are
 115      checked on each cron run; and if a page is expired, the cache is cleared,
 116      and a new cached version will be created the next time the page is
 117      called upon by an anonymous user (including bots). The page will be
 118      regenerated by the Boost crawler if enabled on the Boost settings page.
 119
 120   5. IMPORTANT:
 121      --- This step is easy and required for Boost to work! ---
 122      Back up the original .htaccess file from your Drupal installation directory
 123      for safe keeping. Copy the custom generated htaccess rule from
 124      [Administer > Site configuration > Performance > htaccess rules generation]
 125      page and paste the rules into the Drupal htaccess file as shown below.
 126
 127        # RewriteBase /
 128      -------paste the rules right here--------
 129        # Rewrite URLs of the form 'x' to the form 'index.php?q=x'.
 130
 131      In the boost/htaccess/ folder, the default.txt file shows you
 132      the exact placement of the rules, in case your not sure.
 133
 134      The module package has 3 htaccess templates included in the Boost/htaccess
 135      folder (boosted1.txt, boosted2.txt and default.txt). These templates may
 136      be helpful in some cases and are good for reference. For the technically
 137      inclined, the difference between the two .htaccess templates is due
 138      to boosted1.txt relying on SERVER_NAME versus boosted2.txt using HTTP_HOST.
 139      There are valid use cases for both in more advanced multi-site installations.
 140
 141      Note: If you get "400 Bad Request" responses from Apache server, make sure
 142      you have configured RewriteBase as documented in
 143      http://drupalcode.org/viewvc/drupal/drupal/.htaccess?view=markup&pathrev=DRUPAL-6
 144      For example when using VirtualHost configurations it is necessary to define as:
 145      RewriteBase /
 146
 147   6. Goto: [Administer > Site configuration > Performance]
 148      Check and set the Drupal cache settings as desired.
 149
 150   7. Prepare robots.txt file for search engines.
 151      Add "Disallow: /boost_stats.php" to the robots.txt file as shown below.
 152
 153      # Files
 154      Disallow: /boost_stats.php
 155      Disallow: /CHANGELOG.txt
 156      .....
 157      .....
 158
 159
 160  SYSTEM CHECK AND VERIFY FUNCTIONS
 161  ---------------------------------
 162   1. Log out from Drupal (or use another browser) to browse around your site
 163      as the anonymous user. Ensure that static files are indeed being
 164      generated into the Boost cache directory you specified above (#4); and if
 165      you opt to use gzip, likewise check gzipped files are being generated in
 166      the directory you specified for this.
 167      The Administer > Performance > Boost settings page shows how many pages
 168      are cached by Boost.
 169
 170   2. Check the Drupal status page [Administer > Reports > Status report]
 171      for any errors or notices.
 172
 173   3. To check whether you have a cached or dynamic version of a page,
 174      look at the very end of the page's HTML source. You have the cached
 175      version if the last line looks like this:
 176  <!--Page cached by Boost @ 2009-08-11 06:19:58,expires @ 2009-08-11 09:19:58-->
 177
 178
 179  BOOST ADMINISTRATIVE AND STATS BLOCKS
 180  -------------------------------------
 181  There are 2 blocks that you can add to help with the administrative
 182  side (status, page configuration), and 1 block to support core stats.
 183
 184  Goto: (administer > Site building > Blocks > List) to place them.
 185
 186  The visibility of blocks can also be configured by role and page.
 187  On the Blocks list page, to the right of each block click 'configure'.
 188
 189
 190  * Status Block
 191    This block shows the current status of the page as far as Boost is
 192    concerned. It will state if the page is served 'live' or by 'Boost',
 193    the expiration of the page and has a Flush Page button to clear the
 194    page from the cache manually. The block only appears if your not user
 195    0 and provides useful information about PHP errors on the page.
 196
 197  * Page configuration Block
 198    This block allows the administrator to set pages individually.
 199    Including setting for maximum cache lifetime(select box), preemptive
 200    cache(on or off), scope(page ID, content type or content container).
 201
 202  * Stats Block
 203    Drupal's core stats is supported. Configure the "Popular content" block, but
 204    then disable it. Place the "Boost: AJAX core statistics" in its place. If ajax
 205    stats are loading too slowly, copy stats/boost_stats.php to your webroot and
 206    enable "Cache Statistics Block". The cache gets updated on cron runs.
 207
 208
 209  CONFIGURATION TIPS
 210  ------------------
 211  For the (i18n) and the (Domain) modules:
 212    Enable
 213     [x] Do not store the cache file path in the database
 214     [x] Flush all sites caches in this database (singe db, multi-site)
 215    Disable
 216     [ ] Only allow ASCII characters in path
 217
 218  Enable XML & AJAX/JSON caches
 219    Enable
 220     [x] Cache .xml & /feed
 221     [x] Cache ajax/json
 222
 223  To Use the Cron Crawler
 224    Enable
 225     [x] Overwrite the cached file if it already exits
 226     [x] Expire content in DB, do not flush file.
 227     [x] Enable the cron crawler
 228
 229
 230  IMPORTANT NOTES AND TROUBLESHOOTING
 231  -----------------------------------
 232  * If cron is not clearing the cache as expected.
 233    Set $base_url variable in /sites/default/settings.php (line 125 or so)
 234    so cron runs error free and clears the cache properly when invoked like
 235    'php /path/to/cron.php' or 'drush cron'. This should be something like
 236    http://www.example.com
 237
 238    Guide for editing settings.php
 239    http://drupal.org/node/367081#comment-1504894
 240
 241  * If your Drupal URL paths contain non-ASCII characters, you may have to
 242    tweak your locate settings on the server in order to ensure the URL paths
 243    get correctly translated into directory paths in the file system.
 244    You can also turn off the ASCII filter in the Boost Advanced Settings.
 245    OR install the Transliteration module to help fix the characters.
 246
 247
 248  FILE SYSTEM CACHE
 249  -----------------
 250  The cached files are stored (by default) in the cache/normal/ directory
 251  under your Drupal installation directory. The Drupal pages' URL paths
 252  are translated into file system names in the following manner:
 253
 254    http://example.com/
 255    => cache/normal/example.com/_.html
 256
 257    http://example.com/about
 258    => cache/normal/example.com/about_.html
 259
 260    http://example.com/about/staff
 261    => cache/normal/example.com/about/staff_.html
 262
 263    http://example.com/node/42
 264    => cache/normal/example.com/node/42_.html
 265
 266  You'll note that the directory path includes the Drupal site name, enabling
 267  support for multi-site Drupal installations.
 268
 269
 270  HOW BOOST WORKS
 271  ---------------
 272  Once Boost has been installed and enabled, page requests by anonymous
 273  visitors will be cached as static HTML pages in the server's file system.
 274  Periodically (when the Drupal cron runs) stale or expired pages
 275  (i.e. files or pages exceeding the maximum cache lifetime setting)
 276  will be purged, allowing them to be recreated the first time that the
 277  next anonymous visitor requests that page again. If the Cron Crawler
 278  is enabled, the files and pages will be regenerated automatically.
 279
 280  New rewrite rules are added to the .htaccess file supplied with Drupal,
 281  directing the web server to try and fulfill page requests by anonymous
 282  visitors first and foremost from the static page cache, and to only pass the
 283  request through to Drupal if the requested page is not cacheable or hasn't yet
 284  been cached.
 285
 286
 287  DISPATCH MECHANISM
 288  ------------------
 289  For each incoming page request, the new Apache mod_rewrite directives in
 290  .htaccess will check if a cached version of the requested page should be
 291  served as per the following simple rules:
 292
 293   1. First, we check that the HTTP request method being used is GET.
 294      POST requests are not cacheable, and are passed through to Drupal.
 295
 296   2. Since only anonymous visitors can benefit from the static page cache at
 297      present, we check that the page request doesn't include a cookie that
 298      is set when a user logs in to the Drupal site. If the cookie is
 299      present, we simply let Drupal handle the page request dynamically.
 300
 301   3. Now, for the important bit: we check whether we actually have a cached
 302      HTML file for the request URL path available in the file system cache.
 303      If we do, we direct the web server to serve that file directly and to
 304      terminate the request immediately after; in this case, Drupal (and
 305      indeed PHP) is never invoked, meaning the page request will be served
 306      by the web server itself at full speed.
 307
 308   4. If, however, we couldn't locate a cached version of the page, we just
 309      pass the request on to Drupal, which will serve it dynamically in the
 310      normal manner.
 311
 312
 313  LIMITATIONS
 314  -----------
 315  * Only anonymous visitors will be served cached versions of pages;
 316    authenticated users will get dynamic content. This will limit the
 317    usefulness of this module for those community sites that require user
 318    registration and login for active participation.
 319
 320  * In contrast to Drupal's built-in caching, static caching will lose any
 321    additional HTTP headers set for an HTML page by a module. This is unlikely
 322    to be problem except for some very specific modules and rare use cases.
 323
 324  * Web server software other than Apache is not supported at the moment.
 325    Adding Lighttpd support would be desirable but is not a high priority for
 326    the developer at present (see TODO.txt). (Note that while the LiteSpeed web
 327    server has not been specifically tested by the developer, it may, in fact,
 328    work, since they claim to support .htaccess files and to have mod_rewrite
 329    compatibility. Feedback on this would be appreciated.)
 330
 331
 332  HANDBOOK PAGES
 333  --------------
 334  Boost handbook                 http://drupal.org/node/545664
 335
 336  Installation & Settings        http://drupal.org/node/545908
 337
 338  Boost Tips & Tricks            http://drupal.org/node/583264
 339
 340  FAQ & Future Features          http://drupal.org/node/546134
 341
 342  Using & Blogging About Boost   http://drupal.org/node/546834
 343
 344
 345  BOOST PROJECT & DRUPAL LINKS
 346  ----------------------------
 347  Boost project page             http://drupal.org/project/boost
 348
 349  ** Post feature requests and bug reports:
 350  Boost issue que                http://drupal.org/project/issues/boost
 351
 352  ** The Drupal 'post installation' forum:
 353  Drupal Help Forum              http://drupal.org/forum/22
 354
 355  ** The original blog post about Boost:
 356  http://bendiken.net/2006/05/28/static-page-caching-for-drupal
 357
 358
 359  CREDITS
 360  -------
 361  Originally Developed by Arto Bendiken(arto) http://bendiken.net
 362
 363  Ported to Drupal 5.x by Alexander I. Grafov(axel) http://drupal.ru
 364
 365  Ported to Drupal 6.x by Ben Lavender(bhuga) http://bhuga.net
 366
 367  Miscellaneous contributions by Jacob Peddicord, Justin Miller & Barry Jaspan.
 368
 369  6.x Developer and Maintainer, Mike Carper(mikeytown2) of http://316solutions.net
 370
 371
 372  END OF FILE
 373  -----------