$Id: README.txt,v 1.36 2010-10-06 18:50:35 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. URLs must be rewritten to be able to actually serve the files from a CDN. It provides two modes: "Origin Pull" and "File Conveyor". In "Origin Pull" mode, only "Origin Pull" CDNs are supported (hence the naem). These are CDNs that only require you to replace the domain name with another domain name. The CDN will then automatically fetch (pull) the files from your server (the origin). In "File Conveyor" mode, you must install and configure the File Conveyor daemon I wrote as part of my bachelor thesis[1]. This allows for much more advanced setups: files can be processed (optimized!) 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 Rackspace 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 Rackspace 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. To serve images generated by the ImageCache module from a CDN, you must apply a patch to the ImageCache module, because it uses its own custom function to generate file URLs. 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, Rackspace 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 File Conveyor) to the CDN. Other CDNs, such as MaxCDN, offer both pull- and push-functionality. For more details, see the "Key Properties of a CDN" article [2]. [1] http://fileconveyor.org/ [2] http://wimleers.com/article/key-properties-of-a-cdn Supported CDNs -------------- - Origin Pull mode: any Origin Pull CDN. - File Conveyor 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 Rackspace CloudFiles are also supported. Installation ------------ 1) Apply the Drupal core patch (patches/drupal6.patch). Instructions can be found at http://drupal.org/patch/apply. However, a quick reminder: a) Change the directory to the root directory of your Drupal core: cd /htdocs/example.com b) Copy the patch to this directory cp /htdocs/example.com/sites/all/modules/cdn/patches/drupal6.patch . c) Apply the patch: patch -p0 < drupal6.patch This patch effectively backports hook_file_url_alter() from Drupal 7 to Drupal 6. See the notes about this backport if you're interested in the details or want to use it in your own module. NOTE: Pressflow users don't have to apply the Drupal core patch; Pressflow already includes this patch! 2) Apply the ImageCache patch (patches/imagecache.patch), if you want to serve images generated by the ImageCache module from a CDN. This is a separate patch because it uses its own custom function to generate file URLs. 3) 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. 4) Enable the module. 5) Visit "admin/settings/cdn" to learn about the various settings. 6) If you want to use File Conveyor mode, install and configure the File Conveyor first. You can download it at http://fileconveyor.org/ 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. Note: the CDN integration module requires PDO extension for PHP to be installed, as well as the PDO SQLite driver. 7) Go to admin/reports/status. The CDN module will report its status here. If you've enabled File Conveyor mode and have set up File Conveyor daemon, you will see some basic stats here as well, and you can check here to see if File Conveyor is currently running. You can also see here if you've applied the patches correctly! Notes on the backport of hook_file_url_alter() for Drupal 6 ----------------------------------------------------------- An identical backport is impossible because in Drupal 7, there's the new File API which uses PHP stream wrappers. It doesn't make sense to backport the entire new File API. - Issue for Drupal 7 core patch: http://drupal.org/node/499156 - The backport of hook_file_url_alter() is based on the patch *before* stream wrapper support went in, i.e. the patch in this comment: http://drupal.org/node/499156#comment-1866878 http://drupal.org/files/issues/cdn-integration-499156-62.patch - Documentation for hook_file_url_alter() for Drupal 7: http://api.drupal.org/api/function/hook_file_url_alter/7 - For analogous documentation for the Drupal 6 backport, see the included patches/hook_file_url_alter.php When using multiple servers: picking a specific one based on some criteria -------------------------------------------------------------------------- For this purpose, you can implement the cdn_pick_server() function: /** * Implementation of cdn_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_pick_server(). */ function cdn_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'); When your module already uses file_create_url() (either because it supports user-uploaded content or generates files), then there is nothing that you have to do. It is recommended though to include the file_directory_path() in the $path you're passing. I.e., this is supported, but not recommended and even deprecated in Drupal 7 core file_create_url('test.jpg'); This will return "sites/default/files/test.jpg" (assuming that you've configured "sites/default/files" to be your files directory, i.e. the value that file_directory_path() returns). But it's recommended to do the following instead, since that will make porting to Drupal 7 easier: file_create_url(file_directory_path() . '/test.jpg); When images generated by ImageCache appear to be broken ------------------------------------------------------- You're likely using Varnish and an Origin Pull CDN. Try configuring your Push CDN to access the non-Varnish port (i.e. the port of the regular web server), typically port 8080. Not all CDNs support this though. Related issue: http://drupal.org/node/862880 Author ------ Wim Leers ~ http://wimleers.com/ Version 1 of this module (for Drupal 6) was written as part of the bachelor thesis of Wim Leers at Hasselt University. http://wimleers.com/tags/bachelor-thesis http://uhasselt.be/