Added a section to deployment docs about configuring serving of user uploaded files (#7553)

CHANGELOG.txt

@@ -41,6 +41,7 @@ Changelog
  * Change webmaster to website administrator in the admin (Naomi Morduch Toubman)
  * Added documentation for creating custom submenus in the admin menu (Sævar Öfjörð Magnússon)
  * Choice blocks in StreamField now show label rather than value when collapsed (Jérôme Lebleu)
+ * Added documentation to clarify configuration of user-uploaded files (Cynthia Kiser)
  * Fix: Accessibility fixes for Windows high contrast mode; Dashboard icons colour and contrast, help/error/warning blocks for fields and general content, side comment buttons within the page editor, dropdown buttons (Sakshi Uppoor, Shariq Jamil, LB (Ben Johnston), Jason Attwood)
  * Fix: Rename additional 'spin' CSS animations to avoid clashes with other libraries (Kevin Gutiérrez)
  * Fix: `default_app_config` deprecations for Django >= 3.2 (Tibor Leupold)

docs/advanced_topics/deploying.rst

@@ -31,6 +31,8 @@ On other PAASs and IAASs
 
 We know of Wagtail sites running on `Heroku <https://spapas.github.io/2014/02/13/wagtail-tutorial/>`_, Digital Ocean and elsewhere. If you have successfully installed Wagtail on your platform or infrastructure, please :doc:`contribute </contributing/index>` your notes to this documentation!
 
+.. _deployment_tips:
+
 Deployment tips
 ~~~~~~~~~~~~~~~
 
@@ -41,11 +43,19 @@ As with all Django projects, static files are not served by the Django applicati
 
 The JavaScript and CSS files used by the Wagtail admin frequently change between releases of Wagtail - it's important to avoid serving outdated versions of these files due to browser or server-side caching, as this can cause hard-to-diagnose issues. We recommend enabling :class:`~django.contrib.staticfiles.storage.ManifestStaticFilesStorage` in the ``STATICFILES_STORAGE`` setting - this ensures that different versions of files are assigned distinct URLs.
 
+User Uploaded Files
++++++++++++++++++++
+
+Wagtail follows :doc:`Django's conventions for managing uploaded files <django:topics/files>`. So by default, Wagtail uses Djangos's built-in ``FileSystemStorage`` class which stores files on your site's server, in the directory specified by the ``MEDIA_ROOT`` setting. Alternatively, Wagtail 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 <https://docs.djangoproject.com/en/stable/ref/settings/#std:setting-DEFAULT_FILE_STORAGE>`_ setting in conjunction with an add-on package such as `django-storages <https://django-storages.readthedocs.io/>`_.
+
+When using ``FileSystemStorage``, image urls are constructed starting from the path specified by the ``MEDIA_URL``. In most cases, you should configure your web server to serve image files directly (without passing through Django/Wagtail). When using one of the cloud storage backends, images urls go directly to the cloud storage file url. If you would like to serve your images from an separate asset server or CDN, you can :ref:`configure the image serve view <image_serve_view_redirect_action>` to redirect instead.
+
+Document serving is controlled by the :ref:`WAGTAILDOCS_SERVE_METHOD <wagtaildocs_serve_method>` method. When using ``FileSystemStorage``, documents are stored in a ``documents`` subdirectory within your site's ``MEDIA_ROOT``. If all your documents are public, you can set the ``WAGTAILDOCS_SERVE_METHOD`` to ``direct`` and configure your web server to serve the files itself. However, if you use  Wagtail's :ref:`Collection Privacy settings <collection_privacy_settings>` to restrict access to some or all of your documents, you may or may not want to configure your web server to serve the documents directly. The default setting is ``redirect`` which allows Wagtail to perform any configured privacy checks before offloading serving the actual document to your web server or CDN. This means that wagtail constructs document links that pass thorough Wagtail, but the final url in the user's browser is served directly by your web server. If a user bookmarks this url, they will be able to access the file without passing through Wagtail's privacy checks. If this is not acceptable, you may want to set the ``WAGTAILDOCS_SERVE_METHOD`` to ``serve_view`` and configure your web server so it will not serve document files itself. If you are serving documents from the cloud and need to enforce privacy settings, you should make sure the documents are not publically accessible using the cloud service's file url.
 
 Cloud storage
 +++++++++++++
 
-Wagtail follows :doc:`Django's conventions for managing uploaded files <django:topics/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 <https://docs.djangoproject.com/en/stable/ref/settings/#std:setting-DEFAULT_FILE_STORAGE>`_ setting in conjunction with an add-on package such as `django-storages <https://django-storages.readthedocs.io/>`_. 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, original image files need to be read back whenever a new resized rendition is created, and documents may be configured to be served through a Django view in order to enforce permission checks (see :ref:`WAGTAILDOCS_SERVE_METHOD <wagtaildocs_serve_method>`).
+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, original image files need to be read back whenever a new resized rendition is created, and documents may be configured to be served through a Django view in order to enforce permission checks (see :ref:`WAGTAILDOCS_SERVE_METHOD <wagtaildocs_serve_method>`).
 
 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 ``False``.
 

docs/editor_manual/documents_images_snippets/collections.rst

@@ -25,6 +25,8 @@ ______________________________________
 
 .. image:: ../../_static/images/collections_edit_img_view.png
 
+.. _collection_privacy_settings:
+
 Privacy settings
 ________________
 
@@ -36,5 +38,8 @@ ________________
 
 .. image:: ../../_static/images/collections_privacy_overlay.png
 
+Permissions set on a collection apply to that collection and all collections below it in the hierarchy. Therefore, if you make the 'root' collection private, all documents in the site will be private. Permissions set on other collections apply to that collection only.
+
+
 .. Note::
-    Permissions set on a collection apply to that collection and all collections below it in the hierarchy. So if you make the 'root' collection private, all documents on the site will be private.
+    Although privacy settings are added to a collection, they are only enforced for documents within the collection. Privacy settings do not apply to images.

docs/reference/settings.rst

@@ -349,7 +349,7 @@ You can use it to specify or override the widgets to use in the admin form.
 
   WAGTAILDOCS_SERVE_METHOD = 'redirect'
 
-Determines how document downloads will be linked to and served. Normally, requests for documents are sent through a Django view, to perform permission checks (see :ref:`image_document_permissions`) and potentially other housekeeping tasks such as hit counting. To fully protect against users bypassing this check, it needs to happen in the same request where the document is served; however, this incurs a performance hit as the document then needs to be served by the Django server. In particular, this cancels out much of the benefit of hosting documents on external storage, such as S3 or a CDN.
+Determines how document downloads will be linked to and served. Normally, requests for documents are sent through a Django view, to perform privacy checks (see :ref:`collection_privacy_settings`) and potentially other housekeeping tasks such as hit counting. To fully protect against users bypassing this check, it needs to happen in the same request where the document is served; however, this incurs a performance hit as the document then needs to be served by the Django server. In particular, this cancels out much of the benefit of hosting documents on external storage, such as S3 or a CDN.
 
 For this reason, Wagtail provides a number of serving methods which trade some of the strictness of the permission check for performance:
 

docs/releases/2.16.md

@@ -47,6 +47,7 @@ As part of a [wider redesign](https://github.com/wagtail/wagtail/discussions/773
  * Change webmaster to website administrator in the admin (Naomi Morduch Toubman)
  * Added documentation for creating custom submenus in the admin menu (Sævar Öfjörð Magnússon)
  * Choice blocks in StreamField now show label rather than value when collapsed (Jérôme Lebleu)
+ * Added documentation to clarify configuration of user-uploaded files (Cynthia Kiser)
 
 ### Bug fixes