modules/cdn/README.txt

// $Id: README.txt,v 1.14 2008/01/21 21:45:31 wimleers Exp $

Description
-----------
The aim of this module to provide easy Content Delivery Network integration
for Drupal sites. Obviously it has to patch Drupal core to rewrite the URLs,
not only to serve them from another domain, but also to make the filenames
unique.

It has synchronization plugins, so it allows you to use any protocol or
algorithm to synchronize your files. Currently however, only one plugin is
available: FTP. Since proper usage of a CDN demands unique filenames for each
version of a file, we can optimize a lot: to validate a file on the CDN while
synchronizing, we must only know if it 1) exists and 2) has the correct size.

Which files and directories should be synchronized can be configured very
precisely. Consult the README for details about that.

The FTP synchronization plugin allows you to use a $15 per month CDN (thus
making CDNs accessible to /a lot/ of Drupal users) with no effort after the
installation!
For those who know of the infamous YSlow test: if you install and configure
this module and apply the core patch that also adds Javascript aggregation,
you will score 98. Almost the maximum! The remainder of points is due to the
lack Javascript minification (compression).

This module was developed for http://driverpacks.net/.


Aren't CDN's so expensive only big companies can afford them?
-------------------------------------------------------------
Not anymore (in order of best price-value ratio):

1) CacheFly, http://cachefly.com/, starts at USD 15 for 30 GB per month

2) Influxis, http://influxis.com/, starts at USD 10 for 1 GB per month


Installation
------------
1) Place this module in your modules directory (this will usually be
"sites/all/modules/").

2) Enable the module.

3) Apply the Drupal core patch. See below.

4) Apply the theme patch to every theme. See below.

5) Read how to configure the CDN synchronization filters. See below.

6) Configure the $conf array in settings.php See below.

7) Copy cdn_cron.php to your Drupal root directory.

8) Configure cdn_cron.php like Drupal's cron.php. See http://drupal.org/cron.

9) Go to admin/logs/status. If the CDN integration module is installed
correctly or not, it will report so here.


Usage
-----
When the module is installed properly (see step 9 of the installation), you
can check the site-wide statistics at admin/settings/cdn. At that same page,
you can enable the per-page statistics as well. This will show the number of
files served from the CDN at the bottom of each page, as well as a list of
files that haven't been synchronized to the CDN yet, to users with the
"administer site configuration" permission.


Applying the Drupal core patch
------------------------------
You *must* apply this patch! It has been created against Drupal 5.5.

First, change the directory to the Drupal root directory.

You can apply the included Drupal core patch like this:
  patch -p0 < d5_file_url_rewrite.patch

To undo the patch:
  patch -p0 -R < d5_file_url_rewrite.patch

Note: there is also a patch that combines the CDN integration core patch with
the JS aggregation. It's included in this module because if you apply both
patches separately, you will get a conflict. This patch also sets the default
location for drupal.js and jquery.js to the footer of the page, and defaults
calls to drupal_add_js() to the footer as well.


Applying the theme patch
------------------------
You *must* apply this patch to *every* theme that's being used on your website!

Repeat this process for every theme: first, change the directory to the
directory of the theme. Applying the patch is identical to the example above,
only with a different filename.


Setting up CDN synchronization filters
--------------------------------------
First of all: each filter works *recursively*! Now, the explanations:
- paths: This is an array of paths (each path being relative to the Drupal
         root directory) on which this filter should be applied.
- pattern: Regular expression that will be used to filter the files in each
           directory. Like the $mask parameter in file_scan_directory().
- ignored_dirs: Array of directories that should be ignored in each directory.
                Like the $nomask parameter in file_scan_directory().
- unique: Determines how the uniqueness will be applied. You can set it to
          'filename', which will alter the filename, or 'common parent
          directory', which will alter the path of the file. The latter is
          strongly recommended for themes, since it will not break URLs in
          CSS files.
- unique_method: The method that should be used to generate unique filenames.
                 Currently supported: 'none' (no unique filename!), 'mtime'
                 (the file's mtime property), 'md5' (md5 hash of the file) or
                 'md5 of mtimes' (md5 hash of the concatenated mtimes of a set
                 of files). This last option is only available if you have set
                 the unique property to 'common parent directory'.


Configuring the $conf array in settings.php
-------------------------------------------
This is my configuration:

$conf = array(
  // Configure Drupal core's file URL rewriting ability. If any of the
  // functions listed here fails, Drupal will default to its own ("normal")
  // file URL rewriting function.
  'file_url_rewrite' => array(
    'cdn_file_url', // List the CDN module's URL rewrite function as the preferred server.
  ),

  // CDN integration module settings.
  'cdn_url' => 'http://wimleers.cachefly.com/wimleers.com',
  'cdn_sync_filters' => array(
    // Add all Javascript, CSS, image and flash files from the most common
    // directories in Drupal.
    0 => array(
      'paths' => array('misc', 'profiles', 'modules', 'sites/all/modules', 'sites/default/modules'),
      'pattern' => '.*\.(ico|js|css|gif|png|jpg|jpeg|svg|swf)$',
      'ignored_dirs' => array('CVS'),
      'unique' => 'filename',
      'unique_method' => 'mtime',
    ),

    // We want to add *everything* in the files directory. Except for the
    // files in the CSS and JS directory, because they need other treatment:
    // we assume that files in this directory don't change, so we can use
    // non-unique filenames, resulting in nicer filenames when they're
    // downloaded.
    1 => array(
      'paths' => array('sites/wimleers.com/files'),
      'pattern' => '.*',
      'ignored_dirs' => array('CVS', 'css', 'js'),
      'unique_method' => 'none',
    ),

    // Add all files in the files/css directory, *but* update the URLs in the
    // files. This is only necessary if we use CSS aggregation.
    2 => array(
      'paths' => array('sites/wimleers.com/files/css'),
      'pattern' => '.*',
      'ignored_dirs' => array('CVS'),
      'unique' => 'filename',
      'unique_method' => 'mtime',
      'update_urls_in_files' => TRUE,
    ),

    // Add all files in the files/js directory. This is only necessary if we
    // use JS aggregation.
    3 => array(
      'paths' => array('sites/wimleers.com/files/js'),
      'pattern' => '.*',
      'ignored_dirs' => array('CVS'),
      'unique' => 'filename',
      'unique_method' => 'mtime',
    ),

    // Add all Javascript, CSS, image and font files from our themes. But
    // make sure the URLs don't break when CSS aggregation is disabled, by
    // using the "common parent directory" unique level and the "md5 of mtimes"
    // uniqueness method. We can revert to normal values if we have CSS
    // aggregation enabled.
    4 => array(
      'paths' => array('sites/default/themes/garland-customized'),
      'pattern' => '.*\.(js|css|gif|png|jpg|jpeg|otf)$', // We *include* css files, because some (e.g. fix-ie.css) are not included in the aggregation.
      'ignored_dirs' => array('CVS'),
      'unique' => 'common parent directory',
      'unique_method' => 'md5 of mtimes',
    ),
  ),
  'cdn_sync_method' => 'ftp',
  'cdn_sync_method_settings' => array(
    'host' => 'ftp.cachefly.com',
    'remote_path' => 'wimleers.com',
    'port' => 21,
    'user' => 'user',
    'pass' => 'pass',
  ),
);


Author
------
Wim Leers

* mail: work@wimleers.com
* website: http://wimleers.com/work

The author can be contacted for paid customizations of this module as well as
Drupal consulting, development and installation.
1	wimleers	1.15	// $Id: README.txt,v 1.14 2008/01/21 21:45:31 wimleers Exp $
2	wimleers	1.6
3			Description
4			-----------
5			The aim of this module to provide easy Content Delivery Network integration
6			for Drupal sites. Obviously it has to patch Drupal core to rewrite the URLs,
7			not only to serve them from another domain, but also to make the filenames
8			unique.
9
10			It has synchronization plugins, so it allows you to use any protocol or
11			algorithm to synchronize your files. Currently however, only one plugin is
12			available: FTP. Since proper usage of a CDN demands unique filenames for each
13			version of a file, we can optimize a lot: to validate a file on the CDN while
14			synchronizing, we must only know if it 1) exists and 2) has the correct size.
15
16			Which files and directories should be synchronized can be configured very
17			precisely. Consult the README for details about that.
18
19			The FTP synchronization plugin allows you to use a $15 per month CDN (thus
20	wimleers	1.9	making CDNs accessible to /a lot/ of Drupal users) with no effort after the
21	wimleers	1.6	installation!
22			For those who know of the infamous YSlow test: if you install and configure
23			this module and apply the core patch that also adds Javascript aggregation,
24			you will score 98. Almost the maximum! The remainder of points is due to the
25			lack Javascript minification (compression).
26
27			This module was developed for http://driverpacks.net/.
28
29
30	wimleers	1.7	Aren't CDN's so expensive only big companies can afford them?
31			-------------------------------------------------------------
32			Not anymore (in order of best price-value ratio):
33
34			1) CacheFly, http://cachefly.com/, starts at USD 15 for 30 GB per month
35
36			2) Influxis, http://influxis.com/, starts at USD 10 for 1 GB per month
37
38
39	wimleers	1.6	Installation
40			------------
41			1) Place this module in your modules directory (this will usually be
42			"sites/all/modules/").
43
44			2) Enable the module.
45
46			3) Apply the Drupal core patch. See below.
47
48			4) Apply the theme patch to every theme. See below.
49
50			5) Read how to configure the CDN synchronization filters. See below.
51
52			6) Configure the $conf array in settings.php See below.
53
54			7) Copy cdn_cron.php to your Drupal root directory.
55
56			8) Configure cdn_cron.php like Drupal's cron.php. See http://drupal.org/cron.
57
58			9) Go to admin/logs/status. If the CDN integration module is installed
59			correctly or not, it will report so here.
60
61
62			Usage
63			-----
64			When the module is installed properly (see step 9 of the installation), you
65			can check the site-wide statistics at admin/settings/cdn. At that same page,
66			you can enable the per-page statistics as well. This will show the number of
67			files served from the CDN at the bottom of each page, as well as a list of
68			files that haven't been synchronized to the CDN yet, to users with the
69			"administer site configuration" permission.
70
71	wimleers	1.1
72			Applying the Drupal core patch
73			------------------------------
74	wimleers	1.8	You must apply this patch! It has been created against Drupal 5.5.
75	wimleers	1.1
76			First, change the directory to the Drupal root directory.
77
78			You can apply the included Drupal core patch like this:
79	wimleers	1.15	patch -p0 < d5_file_url_rewrite.patch
80	wimleers	1.1
81			To undo the patch:
82	wimleers	1.15	patch -p0 -R < d5_file_url_rewrite.patch
83	wimleers	1.1
84	wimleers	1.5	Note: there is also a patch that combines the CDN integration core patch with
85			the JS aggregation. It's included in this module because if you apply both
86	wimleers	1.15	patches separately, you will get a conflict. This patch also sets the default
87			location for drupal.js and jquery.js to the footer of the page, and defaults
88			calls to drupal_add_js() to the footer as well.
89	wimleers	1.5
90	wimleers	1.1
91			Applying the theme patch
92			------------------------
93			You must apply this patch to every theme that's being used on your website!
94
95			Repeat this process for every theme: first, change the directory to the
96			directory of the theme. Applying the patch is identical to the example above,
97			only with a different filename.
98
99
100	wimleers	1.6	Setting up CDN synchronization filters
101			--------------------------------------
102			First of all: each filter works recursively! Now, the explanations:
103	wimleers	1.2	- paths: This is an array of paths (each path being relative to the Drupal
104			root directory) on which this filter should be applied.
105	wimleers	1.6	- pattern: Regular expression that will be used to filter the files in each
106	wimleers	1.2	directory. Like the $mask parameter in file_scan_directory().
107	wimleers	1.6	- ignored_dirs: Array of directories that should be ignored in each directory.
108			Like the $nomask parameter in file_scan_directory().
109	wimleers	1.2	- unique: Determines how the uniqueness will be applied. You can set it to
110			'filename', which will alter the filename, or 'common parent
111			directory', which will alter the path of the file. The latter is
112			strongly recommended for themes, since it will not break URLs in
113			CSS files.
114			- unique_method: The method that should be used to generate unique filenames.
115	wimleers	1.12	Currently supported: 'none' (no unique filename!), 'mtime'
116			(the file's mtime property), 'md5' (md5 hash of the file) or
117			'md5 of mtimes' (md5 hash of the concatenated mtimes of a set
118			of files). This last option is only available if you have set
119			the unique property to 'common parent directory'.
120	wimleers	1.2
121
122	wimleers	1.1	Configuring the $conf array in settings.php
123			-------------------------------------------
124	wimleers	1.2	This is my configuration:
125	wimleers	1.1
126			$conf = array(
127	wimleers	1.15	// Configure Drupal core's file URL rewriting ability. If any of the
128			// functions listed here fails, Drupal will default to its own ("normal")
129			// file URL rewriting function.
130	wimleers	1.14	'file_url_rewrite' => array(
131			'cdn_file_url', // List the CDN module's URL rewrite function as the preferred server.
132			),
133	wimleers	1.15
134			// CDN integration module settings.
135	wimleers	1.2	'cdn_url' => 'http://wimleers.cachefly.com/wimleers.com',
136	wimleers	1.1	'cdn_sync_filters' => array(
137	wimleers	1.6	// Add all Javascript, CSS, image and flash files from the most common
138			// directories in Drupal.
139	wimleers	1.2	0 => array(
140			'paths' => array('misc', 'profiles', 'modules', 'sites/all/modules', 'sites/default/modules'),
141	wimleers	1.12	'pattern' => '.*\.(ico\|js\|css\|gif\|png\|jpg\|jpeg\|svg\|swf)$',
142	wimleers	1.3	'ignored_dirs' => array('CVS'),
143	wimleers	1.2	'unique' => 'filename',
144			'unique_method' => 'mtime',
145			),
146	wimleers	1.6
147			// We want to add everything in the files directory. Except for the
148	wimleers	1.13	// files in the CSS and JS directory, because they need other treatment:
149			// we assume that files in this directory don't change, so we can use
150			// non-unique filenames, resulting in nicer filenames when they're
151			// downloaded.
152	wimleers	1.2	1 => array(
153			'paths' => array('sites/wimleers.com/files'),
154			'pattern' => '.*',
155	wimleers	1.13	'ignored_dirs' => array('CVS', 'css', 'js'),
156			'unique_method' => 'none',
157			),
158
159			// Add all files in the files/css directory, but update the URLs in the
160			// files. This is only necessary if we use CSS aggregation.
161			2 => array(
162			'paths' => array('sites/wimleers.com/files/css'),
163			'pattern' => '.*',
164			'ignored_dirs' => array('CVS'),
165			'unique' => 'filename',
166			'unique_method' => 'mtime',
167			'update_urls_in_files' => TRUE,
168			),
169
170			// Add all files in the files/js directory. This is only necessary if we
171			// use JS aggregation.
172			3 => array(
173			'paths' => array('sites/wimleers.com/files/js'),
174			'pattern' => '.*',
175			'ignored_dirs' => array('CVS'),
176			'unique' => 'filename',
177			'unique_method' => 'mtime',
178	wimleers	1.2	),
179	wimleers	1.6
180			// Add all Javascript, CSS, image and font files from our themes. But
181			// make sure the URLs don't break when CSS aggregation is disabled, by
182			// using the "common parent directory" unique level and the "md5 of mtimes"
183			// uniqueness method. We can revert to normal values if we have CSS
184			// aggregation enabled.
185	wimleers	1.13	4 => array(
186	wimleers	1.2	'paths' => array('sites/default/themes/garland-customized'),
187	wimleers	1.10	'pattern' => '.\.(js\|css\|gif\|png\|jpg\|jpeg\|otf)$', // We include* css files, because some (e.g. fix-ie.css) are not included in the aggregation.
188	wimleers	1.3	'ignored_dirs' => array('CVS'),
189	wimleers	1.2	'unique' => 'common parent directory',
190			'unique_method' => 'md5 of mtimes',
191			),
192	wimleers	1.1	),
193			'cdn_sync_method' => 'ftp',
194			'cdn_sync_method_settings' => array(
195			'host' => 'ftp.cachefly.com',
196	wimleers	1.2	'remote_path' => 'wimleers.com',
197	wimleers	1.1	'port' => 21,
198			'user' => 'user',
199			'pass' => 'pass',
200			),
201			);
202	wimleers	1.6
203
204			Author
205			------
206			Wim Leers
207
208			* mail: work@wimleers.com
209			* website: http://wimleers.com/work
210
211			The author can be contacted for paid customizations of this module as well as
212			Drupal consulting, development and installation.