Added documentation and notes about S3 content headers

changes/notes.rst

@@ -78,6 +78,14 @@ Content-Security-Policy and additional security headers [manual action suggested
 To improve the security and reduce the attack surface in case of a successfull exploit, we suggest
 you add the following Content-Security-Policy to your nginx configuration.
 
+..note::
+    
+    If you are using an S3-compatible store to serve music, you will need to specify the URL of your S3 store in the ``media-src`` and ``img-src`` headers
+
+    .. code-block::
+    
+        add_header Content-Security-Policy "...img-src 'self' https://<your-s3-URL> data:;...media-src https://<your-s3-URL> 'self' data:";
+
 **On non-docker setups**, in ``/etc/nginx/sites-available/funkwhale.conf``::
 
     server {

deploy/docker.nginx.template

@@ -23,6 +23,9 @@ server {
 
     root /frontend;
 
+    # If you are using S3 to host your files, remember to add your S3 URL to the
+    # media-src and img-src headers (e.g. img-src 'self' https://<your-S3-URL> data:)
+
     add_header Content-Security-Policy "default-src 'self'; script-src 'self'; style-src 'self' 'unsafe-inline'; img-src 'self' data:; font-src 'self' data:; object-src 'none'; media-src 'self' data:";
     add_header Referrer-Policy "strict-origin-when-cross-origin";
 

deploy/docker.proxy.template

@@ -30,6 +30,10 @@ server {
     add_header Strict-Transport-Security "max-age=31536000";
 
     # Security related headers
+
+    # If you are using S3 to host your files, remember to add your S3 URL to the
+    # media-src and img-src headers (e.g. img-src 'self' https://<your-S3-URL> data:)
+
     add_header Content-Security-Policy "default-src 'self'; script-src 'self'; style-src 'self' 'unsafe-inline'; img-src 'self' data:; font-src 'self' data:; object-src 'none'; media-src 'self' data:";
 
     # compression settings

deploy/nginx.template

@@ -41,6 +41,9 @@ server {
     # HSTS
     add_header Strict-Transport-Security "max-age=31536000";
 
+    # If you are using S3 to host your files, remember to add your S3 URL to the
+    # media-src and img-src headers (e.g. img-src 'self' https://<your-S3-URL> data:)
+
     add_header Content-Security-Policy "default-src 'self'; script-src 'self'; style-src 'self' 'unsafe-inline'; img-src 'self' data:; font-src 'self' data:; object-src 'none'; media-src 'self' data:";
     add_header Referrer-Policy "strict-origin-when-cross-origin";
 

docs/admin/external-storages.rst

@@ -45,6 +45,12 @@ Replace the ``location /_protected/media`` block with the following::
         proxy_pass $1;
     }
 
+Add your S3 store URL to the ``img-src`` and ``media-src`` headers
+
+.. code-block:: shell
+
+    add_header Content-Security-Policy "...img-src 'self' https://<your-s3-URL> data:;...media-src https://<your-s3-URL> 'self' data:";
+
 Then restart Funkwhale and nginx.
 
 From now on, media files will be stored on the S3 bucket you configured. If you already
@@ -141,3 +147,22 @@ in your ``funkwhale.template`` under the ``location ~/_protected/media/(.+)`` se
      proxy_pass $1;
     }
 
+No Images or Media Loading
+^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+If you are serving media from an S3-compatible store, you may experience an issue where
+nothing loads in the front end. The error logs in your browser may show something like
+the following:
+
+.. code-block:: text
+
+    Content Security Policy: The page's settings blocked the loading of a resource at https://<your-s3-url> ("img-src")
+    Content Security Policy: The page's settings blocked the loading of a resource at https://<your-s3-url> ("media-src")
+
+This happens when your S3 store isn't defined in the ``Content-Security-Policy`` headers
+in your Nginx files. To resolve the issue, add the base URL of your S3 store to the ``img-src``
+and ``media-src`` headers and reload nginx.
+
+.. code-block:: shell
+
+    add_header Content-Security-Policy "...img-src 'self' https://<your-s3-URL> data:;...media-src https://<your-s3-URL> 'self' data:";