modules/cdn/README.txt

$Id$

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.
URLs must be rewritten to be able to actually serve the files from a CDN.

It provides two modes: basic and advanced.

In basic mode, only "Origin Pull" CDNs are supported. These are CDNs that only
require you to replace the domain name (and possibly base path) with another
domain name. The CDN will then automatically fetch (pull) the files from your
server (the origin).

In advanced mode, you must install and configure the daemon I wrote as part of
my bachelor thesis: File Conveyor [1]. This allows for much more advanced
setups: files can be processed before they are synced and your CDN doesn't
*have* to support Origin Pull, any push method is fine. Push always uses
transfer protocols, either well-established ones (e.g. FTP) or custom ones
(e.g. Amazon S3 and Mosso CloudFiles). It is thanks to this abstraction layer
that it can be used for *any* CDN, thereby avoiding vendor lock-in.
- File Conveyor includes "transporters" for FTP, Amazon S3, Amazon CloudFront
  and Mosso CloudFiles.
- File Conveyor also allows for any kind of automatic file processing. It
  includes "processors" for: image optimization (using a combination of
  ImageMagick, pngcrush, jpegtran and gifsicle), CSS minification (YUI
  Compressor), JS minification (YUI Compressor and/or Google Closure
  Compiler), and so on. It's also very easy to add your own processors.

Note:
"Origin Pull" means the CDN pulls files from the origin server (i.e. the
Drupal web server). That's where its name comes from. Amazon S3, CloudFiles
and CacheFly are all examples of Push CDNs. The first two have custom
protocols, the latter uses FTP. These don't automatically pull files from your
server (the origin server), but you have to push the files manually (or using
a script of some sort, or my daemon) to the CDN. Other CDNs, such as
SimpleCDN, offer both pull- and push-functionality.

This module was written as part of the bachelor thesis [1] of Wim Leers at
Hasselt University [3].

[1] http://fileconveyor.org/
[2] http://wimleers.com/tags/bachelor-thesis
[3] http://uhasselt.be/


Supported CDNs
--------------
- Basic mode: any Origin Pull CDN.
- Advanced mode: any Origin Pull CDN and any push CDN that supports FTP.
  Support for other transfer protocols is welcomed and encouraged: your
  patches are welcome! Amazon S3, Amazon CloudFront and Mosso CloudFiles are
  also supported.


Installation
------------
1) Apply the Drupal core patch (patches/drupal6.patch). Instructions can be
   found at http://drupal.org/patch/apply.

2) Place this module directory in your "modules" folder (this will usually be
   "sites/all/modules/"). Don't install your module in Drupal core's "modules"
   folder, since that will cause problems and is bad practice in general. If
   "sites/all/modules" doesn't exist yet, just create it.

3) Enable the module.

4) Visit "admin/settings/cdn" to learn about the various settings.

5) If you want to use advanced mode, install and configure the daemon first.
   You can install it by performing an svn checkout from
     svn://wimleers.com/school/bachelor-thesis/code/daemon
   Then follow the instructions in the included INSTALL.txt and README.txt.
   Use the config.xml file that is included in this module and modify it to
   comply with your setup and to suit your needs.

6) Go to admin/reports/status. The CDN integration module will report its
   status here. If you've enabled advanced mode and have set up the daemon,
   you will see some basic stats here as well, and you can check here to see
   if the daemon is currently running.


When using multiple servers: picking a specific one based on some criteria
--------------------------------------------------------------------------
For this purpose, you can implement the cdn_advanced_pick_server() function:
  /**
   * Implementation of cdn_advanced_pick_server().
   */
  function cdn_advanced_pick_server($servers_for_file) {
    // The data that you get - one nested array per server from which the file
    // can be served:
    //   $servers_for_file[0] = array('url' => 'http://cdn1.com/image.jpg', 'server' => 'cdn1.com')
    //   $servers_for_file[1] = array('url' => 'http://cdn2.net/image.jpg', 'server' => 'cdn2.net')

    $which = your_logic_to_pick_a_server();

    // Return one of the nested arrays.
    return $servers_for_file[$which];
  }

So to get the default behavior (pick the first server found), one would write:
  /**
   * Implementation of cdn_advanced_pick_server().
   */
  function cdn_advanced_pick_server($servers_for_file) {
    return $servers_for_file[0];
  }


Supporting the CDN integration module in your modules
-----------------------------------------------------
It's very easy to support the CDN integration module in your module. Simply
create a variable function, e.g.:
  $file_create_url = (module_exists('cdn')) ? 'file_create_url' : 'url';

Then create all file URLs using this variable function. E.g.
  $file_url = $file_create_url(drupal_get_path('module', 'episodes') .'/lib/episodes.js');


Author
------
Wim Leers ~ http://wimleers.com/

This module was written as part of the bachelor thesis of Wim Leers at
Hasselt University.
1	wimleers	1.19	$Id$
2	wimleers	1.6
3			Description
4			-----------
5			The aim of this module to provide easy Content Delivery Network integration
6	wimleers	1.19	for Drupal sites. Obviously it has to patch Drupal core to rewrite the URLs.
7			URLs must be rewritten to be able to actually serve the files from a CDN.
8	wimleers	1.6
9	wimleers	1.19	It provides two modes: basic and advanced.
10	wimleers	1.6
11	wimleers	1.19	In basic mode, only "Origin Pull" CDNs are supported. These are CDNs that only
12			require you to replace the domain name (and possibly base path) with another
13			domain name. The CDN will then automatically fetch (pull) the files from your
14			server (the origin).
15
16			In advanced mode, you must install and configure the daemon I wrote as part of
17	wimleers	1.20	my bachelor thesis: File Conveyor [1]. This allows for much more advanced
18			setups: files can be processed before they are synced and your CDN doesn't
19			have to support Origin Pull, any push method is fine. Push always uses
20			transfer protocols, either well-established ones (e.g. FTP) or custom ones
21			(e.g. Amazon S3 and Mosso CloudFiles). It is thanks to this abstraction layer
22			that it can be used for any CDN, thereby avoiding vendor lock-in.
23			- File Conveyor includes "transporters" for FTP, Amazon S3, Amazon CloudFront
24			and Mosso CloudFiles.
25			- File Conveyor also allows for any kind of automatic file processing. It
26			includes "processors" for: image optimization (using a combination of
27			ImageMagick, pngcrush, jpegtran and gifsicle), CSS minification (YUI
28			Compressor), JS minification (YUI Compressor and/or Google Closure
29			Compiler), and so on. It's also very easy to add your own processors.
30
31			Note:
32			"Origin Pull" means the CDN pulls files from the origin server (i.e. the
33			Drupal web server). That's where its name comes from. Amazon S3, CloudFiles
34			and CacheFly are all examples of Push CDNs. The first two have custom
35			protocols, the latter uses FTP. These don't automatically pull files from your
36			server (the origin server), but you have to push the files manually (or using
37			a script of some sort, or my daemon) to the CDN. Other CDNs, such as
38			SimpleCDN, offer both pull- and push-functionality.
39	wimleers	1.19
40			This module was written as part of the bachelor thesis [1] of Wim Leers at
41			Hasselt University [3].
42
43	wimleers	1.20	[1] http://fileconveyor.org/
44			[2] http://wimleers.com/tags/bachelor-thesis
45			[3] http://uhasselt.be/
46	wimleers	1.19
47
48			Supported CDNs
49			--------------
50			- Basic mode: any Origin Pull CDN.
51			- Advanced mode: any Origin Pull CDN and any push CDN that supports FTP.
52			Support for other transfer protocols is welcomed and encouraged: your
53	wimleers	1.20	patches are welcome! Amazon S3, Amazon CloudFront and Mosso CloudFiles are
54			also supported.
55	wimleers	1.7
56
57	wimleers	1.6	Installation
58			------------
59	wimleers	1.19	1) Apply the Drupal core patch (patches/drupal6.patch). Instructions can be
60			found at http://drupal.org/patch/apply.
61	wimleers	1.6
62	wimleers	1.19	2) Place this module directory in your "modules" folder (this will usually be
63			"sites/all/modules/"). Don't install your module in Drupal core's "modules"
64			folder, since that will cause problems and is bad practice in general. If
65			"sites/all/modules" doesn't exist yet, just create it.
66
67			3) Enable the module.
68
69			4) Visit "admin/settings/cdn" to learn about the various settings.
70
71			5) If you want to use advanced mode, install and configure the daemon first.
72			You can install it by performing an svn checkout from
73			svn://wimleers.com/school/bachelor-thesis/code/daemon
74			Then follow the instructions in the included INSTALL.txt and README.txt.
75			Use the config.xml file that is included in this module and modify it to
76			comply with your setup and to suit your needs.
77
78			6) Go to admin/reports/status. The CDN integration module will report its
79			status here. If you've enabled advanced mode and have set up the daemon,
80			you will see some basic stats here as well, and you can check here to see
81			if the daemon is currently running.
82
83
84			When using multiple servers: picking a specific one based on some criteria
85			--------------------------------------------------------------------------
86			For this purpose, you can implement the cdn_advanced_pick_server() function:
87			/**
88			* Implementation of cdn_advanced_pick_server().
89			*/
90			function cdn_advanced_pick_server($servers_for_file) {
91			// The data that you get - one nested array per server from which the file
92			// can be served:
93			// $servers_for_file[0] = array('url' => 'http://cdn1.com/image.jpg', 'server' => 'cdn1.com')
94			// $servers_for_file[1] = array('url' => 'http://cdn2.net/image.jpg', 'server' => 'cdn2.net')
95
96			$which = your_logic_to_pick_a_server();
97
98			// Return one of the nested arrays.
99			return $servers_for_file[$which];
100			}
101
102			So to get the default behavior (pick the first server found), one would write:
103			/**
104			* Implementation of cdn_advanced_pick_server().
105			*/
106			function cdn_advanced_pick_server($servers_for_file) {
107			return $servers_for_file[0];
108			}
109
110
111			Supporting the CDN integration module in your modules
112			-----------------------------------------------------
113			It's very easy to support the CDN integration module in your module. Simply
114			create a variable function, e.g.:
115			$file_create_url = (module_exists('cdn')) ? 'file_create_url' : 'url';
116	wimleers	1.6
117	wimleers	1.19	Then create all file URLs using this variable function. E.g.
118			$file_url = $file_create_url(drupal_get_path('module', 'episodes') .'/lib/episodes.js');
119	wimleers	1.6
120
121			Author
122			------
123	wimleers	1.19	Wim Leers ~ http://wimleers.com/
124	wimleers	1.6
125	wimleers	1.19	This module was written as part of the bachelor thesis of Wim Leers at
126			Hasselt University.