From 937254f321d5da9eb60dbd9242779a037f426343 Mon Sep 17 00:00:00 2001 From: Matt Westcott Date: Tue, 8 May 2018 20:41:51 +0100 Subject: [PATCH] Add documentation for deploying with cloud storage --- docs/advanced_topics/deploying.rst | 17 +++++++++++++++++ 1 file changed, 17 insertions(+) diff --git a/docs/advanced_topics/deploying.rst b/docs/advanced_topics/deploying.rst index 7770cce960..25fc2e1475 100644 --- a/docs/advanced_topics/deploying.rst +++ b/docs/advanced_topics/deploying.rst @@ -17,3 +17,20 @@ On other PAASs and IAASs ~~~~~~~~~~~~~~~~~~~~~~~~ We know of Wagtail sites running on `Heroku `_, Digital Ocean and elsewhere. If you have successfully installed Wagtail on your platform or infrastructure, please :doc:`contribute ` your notes to this documentation! + +Cloud storage +~~~~~~~~~~~~~ + +Wagtail follows `Django's conventions for managing uploaded files `_, and can be configured to store uploaded images and documents on a cloud storage service such as Amazon S3; this is done through the `DEFAULT_FILE_STORAGE `_ setting in conjunction with an add-on package such as `django-storages `_. Be aware that setting up remote storage will not entirely offload file handling tasks from the application server - some Wagtail functionality requires files to be read back by the application server. In particular, documents are served through a Django view in order to enforce permission checks, and original image files need to be read back whenever a new resized rendition is created. + +Note that the django-storages Amazon S3 backends (``storages.backends.s3boto.S3BotoStorage`` and ``storages.backends.s3boto3.S3Boto3Storage``) **do not correctly handle duplicate filenames** in their default configuration. When using these backends, ``AWS_S3_FILE_OVERWRITE`` must be set to ``True``. + +If you are also serving Wagtail's static files from remote storage (using Django's `STATICFILES_STORAGE `_ setting), you'll need to ensure that it is configured to serve `CORS HTTP headers `_, as current browsers will reject remotely-hosted font files that lack a valid header. For Amazon S3, refer to the documentation `Setting Bucket and Object Access Permissions `_, or (for the ``storages.backends.s3boto.S3BotoStorage`` backend only) add the following to your Django settings: + +.. code-block:: python + + AWS_HEADERS = { + 'Access-Control-Allow-Origin': '*' + } + +For other storage services, refer to your provider's documentation, or the documentation for the Django storage backend library you're using.