From 9efedd29982cd7f1abfade0436cb0acf3095ce6d Mon Sep 17 00:00:00 2001 From: Jon Dufresne Date: Tue, 3 Nov 2020 20:02:58 -0800 Subject: [PATCH] Document CORS errors and how to fix them Fixes #1396 --- docs/changes.rst | 9 ++++++++- docs/installation.rst | 37 +++++++++++++++++++++++++++++++++++++ 2 files changed, 45 insertions(+), 1 deletion(-) diff --git a/docs/changes.rst b/docs/changes.rst index 13766d80e..76a4fe1b4 100644 --- a/docs/changes.rst +++ b/docs/changes.rst @@ -85,7 +85,14 @@ Change log :attr:`Panel.scripts ` property. * Removed support for end of life Django 1.11. The minimum supported Django is now 2.2. - +* The Debug Toolbar now loads a `JavaScript module`_. Typical local development + using Django ``runserver`` is not impacted. However, if your application + server and static files server are at different origins, you may see CORS + errors in your browser's development console. See the "Cross-Origin Request + Blocked" section of the :doc:`installation docs ` for details + on how to resolve this issue. + +.. _JavaScript module: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Guide/Modules 2.2 (2020-01-31) ---------------- diff --git a/docs/installation.rst b/docs/installation.rst index 55add1620..87b964e12 100644 --- a/docs/installation.rst +++ b/docs/installation.rst @@ -110,3 +110,40 @@ need to be updated. This can be achieved, for example, by installing or updating the ``mailcap`` package on a Red Hat distribution, ``mime-support`` on a Debian distribution, or by editing the keys under ``HKEY_CLASSES_ROOT`` in the Windows registry. + +Cross-Origin Request Blocked +^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +The Debug Toolbar loads a `JavaScript module`_. Typical local development using +Django ``runserver`` is not impacted. However, if your application server and +static files server are at different origins, you may see `CORS errors`_ in +your browser's development console: + +.. code-block:: text + + Cross-Origin Request Blocked: The Same Origin Policy disallows reading the remote resource at http://localhost/static/debug_toolbar/js/toolbar.js. (Reason: CORS header ‘Access-Control-Allow-Origin’ missing). + +Or + +.. code-block:: text + + Access to script at 'http://localhost/static/debug_toolbar/js/toolbar.js' from origin 'http://localhost:8000' has been blocked by CORS policy: No 'Access-Control-Allow-Origin' header is present on the requested resource. + +To resolve, configure your static files server to add the +`Access-Control-Allow-Origin header`_ with the origin of the application +server. For example, if your application server is at ``http://example.com``, +and your static files are served by NGINX, add: + +.. code-block:: nginx + + add_header Access-Control-Allow-Origin http://example.com; + +And for Apache: + +.. code-block:: apache + + Header add Access-Control-Allow-Origin http://example.com + +.. _JavaScript module: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Guide/Modules +.. _CORS errors: https://developer.mozilla.org/en-US/docs/Web/HTTP/CORS/Errors/CORSMissingAllowOrigin +.. _Access-Control-Allow-Origin header: https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Access-Control-Allow-Origin