Issue #1780860: also truncate boost_cache_relationships in update_6127
[project/boost.git] / 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  -----------