From 047060486dd470bdd53fa2894ac7f84b8563b472 Mon Sep 17 00:00:00 2001
From: Jannis Leidel <jannis@leidel.info>
Date: Tue, 8 Mar 2011 22:44:19 +0100
Subject: [PATCH] Documented how to use django_compressor with remote storages
 such as Amazon S3 (thanks to Sean Brant for the inspiration), including
 staticfiles.

---
 docs/index.txt | 81 ++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 81 insertions(+)

diff --git a/docs/index.txt b/docs/index.txt
index 048faba..abe90c3 100644
--- a/docs/index.txt
+++ b/docs/index.txt
@@ -94,6 +94,87 @@ template tag simply returns exactly what it was given, to ease development.
 .. _memcached: http://memcached.org/
 .. _caching documentation: http://docs.djangoproject.com/en/1.2/topics/cache/#memcached
 
+Remote storages
+---------------
+
+In some cases it's useful to use a CDN_ for serving static files such as
+those generated by django_compressor. Due to the way django_compressor
+processes files, it requires the files to be processed (in the
+``{% compress %}`` block) to be available in a local file system cache.
+
+django_compressor provides hooks to automatically have compressed files
+pushed to a remote storage backend. Simply use set the COMPRESS_STORAGE_
+setting to a storage backend that saves the result to a remote service.
+
+So assuming your CDN is `Amazon S3`_, you can use the boto_ storage backend
+from the 3rd party app `django-storages`_. Some required settings are::
+
+    AWS_ACCESS_KEY_ID = 'XXXXXXXXXXXXXXXXXXXXX'
+    AWS_SECRET_ACCESS_KEY = 'XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX'
+    AWS_STORAGE_BUCKET_NAME = 'compressor-test'
+
+Next, you need to specify the new CDN base URL and update the URLs to the
+files in your templates which you want to compress::
+
+    COMPRESS_URL = "http://compressor-test.s3.amazon.com/"
+
+.. note::
+
+    For staticfiles just set ``STATIC_URL = COMPRESS_URL``
+
+The storage backend to save the compressed files needs to be changed, too::
+
+    COMPRESS_STORAGE = 'storages.backends.s3boto.S3BotoStorage'
+
+staticfiles
+^^^^^^^^^^^
+
+If you are using Django 1.3's staticfiles_ contrib app or the standalone
+app django-staticfiles_, you'll need to use a temporary filesystem cache
+for django_compressor to know which files to compress. Since staticfiles
+provides a management command to collect static files from various
+locations which uses a storage backend, this is where both apps can be
+integrated.
+
+First, make sure the COMPRESS_ROOT_ and STATIC_ROOT_ settings are equal
+since both apps need to look at the same directories when to do their job.
+
+Secondly, you need to create a subclass of the remote storage backend
+you want to use; below is an example of the boto S3 storage backend
+from django-storages::
+
+    from django.core.files.storage import get_storage_class
+    from storages.backends.s3boto import S3BotoStorage
+
+    class CachedS3BotoStorage(S3BotoStorage):
+        """
+        S3 storage backend that saves the files locally, too.
+        """
+        def __init__(self, *args, **kwargs):
+            super(CachedS3BotoStorage, self).__init__(*args, **kwargs)
+            self.local_storage = get_storage_class(
+                "compressor.storage.CompressorFileStorage")()
+
+        def save(self, name, content):
+            name = super(CachedS3BotoStorage, self).save(name, content)
+            self.local_storage._save(name, content)
+            return name
+
+Set your COMPRESS_STORAGE_ and STATICFILES_STORAGE_ settings to the
+dotted path of your custom cached storage backend,
+e.g. ``'mysite.storage.CachedS3BotoStorage'``.
+
+To have Django correctly render the URLs to your static files, set the
+``STATIC_URL`` setting to the same value as COMPRESS_URL_ (e.g.
+``"http://compressor-test.s3.amazon.com/"``).
+
+.. _CDN: http://en.wikipedia.org/wiki/Content_delivery_network
+.. _Amazon S3: https://s3.amazonaws.com/
+.. _boto: http://boto.cloudhackers.com/
+.. _django-storages: http://code.welldev.org/django-storages/
+.. _STATIC_ROOT: http://docs.djangoproject.com/en/dev/ref/settings/#std:setting-STATIC_ROOT
+.. _STATICFILES_STORAGE: http://docs.djangoproject.com/en/dev/ref/contrib/staticfiles/#std:setting-STATICFILES_STORAGE
+
 CSS Notes
 ---------