Add show_toolbar_with_docker function for Docker IP handling

- Introduced a new function, show_toolbar_with_docker, to determine if the toolbar should be displayed when running inside Docker containers.
- Updated installation documentation to reference the new function for Docker configurations.
- Added a changelog entry for the new functionality.

Co-authored-by: Matthias Kestenholz <[email protected]>

Author: blingblin-g

debug_toolbar/middleware.py

@@ -31,6 +31,21 @@ def show_toolbar(request):
     if request.META.get("REMOTE_ADDR") in settings.INTERNAL_IPS:
         return True
 
+    # No test passed
+    return False
+
+
+def show_toolbar_with_docker(request):
+    """
+    Default function to determine whether to show the toolbar on a given page.
+    """
+    if not settings.DEBUG:
+        return False
+
+    # Test: settings
+    if request.META.get("REMOTE_ADDR") in settings.INTERNAL_IPS:
+        return True
+
     # Test: Docker
     try:
         # This is a hack for docker installations. It attempts to look

docs/changes.rst

@@ -6,6 +6,8 @@ Pending
 
 * Added support for checking if pytest as the test runner when determining
   if tests are running.
+* Added ``show_toolbar_with_docker`` function to check Docker host IP address
+  when running inside Docker containers.
 
 5.2.0 (2025-04-29)
 ------------------
@@ -46,6 +48,7 @@ Pending
 * Fix for exception-unhandled "forked" Promise chain in rebound window.fetch
 * Create a CSP nonce property on the toolbar ``Toolbar().csp_nonce``.
 
+
 5.0.1 (2025-01-13)
 ------------------
 * Fixing the build and release process. No functional changes.

docs/installation.rst

@@ -152,10 +152,11 @@ option.
 
 .. warning::
 
-    If using Docker, the toolbar will attempt to look up your host name
-    automatically and treat it as an allowable internal IP. If you're not
-    able to get the toolbar to work with your docker installation, review
-    the code in ``debug_toolbar.middleware.show_toolbar``.
+    If using Docker you can use
+    ``debug_toolbar.middleware.show_toolbar_with_docker`` as your
+    ``SHOW_TOOLBAR_CALLBACK`` which attempts to automatically look up the
+    Docker gateway IP and treat it as an allowable internal IP so that the
+    toolbar is shown to you.
 
 7. Disable the toolbar when running tests (optional)
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

tests/test_integration.py

@@ -15,7 +15,11 @@
 from django.test.utils import override_settings
 
 from debug_toolbar.forms import SignedDataForm
-from debug_toolbar.middleware import DebugToolbarMiddleware, show_toolbar
+from debug_toolbar.middleware import (
+    DebugToolbarMiddleware,
+    show_toolbar,
+    show_toolbar_with_docker,
+)
 from debug_toolbar.panels import Panel
 from debug_toolbar.toolbar import DebugToolbar
 
@@ -72,7 +76,8 @@ def test_show_toolbar_docker(self, mocked_gethostbyname):
         with self.settings(INTERNAL_IPS=[]):
             # Is true because REMOTE_ADDR is 127.0.0.1 and the 255
             # is shifted to be 1.
-            self.assertTrue(show_toolbar(self.request))
+            self.assertFalse(show_toolbar(self.request))
+            self.assertTrue(show_toolbar_with_docker(self.request))
         mocked_gethostbyname.assert_called_once_with("host.docker.internal")
 
     def test_not_iterating_over_INTERNAL_IPS(self):

tests/test_integration_async.py

@@ -11,7 +11,11 @@
 from django.test.utils import override_settings
 
 from debug_toolbar.forms import SignedDataForm
-from debug_toolbar.middleware import DebugToolbarMiddleware, show_toolbar
+from debug_toolbar.middleware import (
+    DebugToolbarMiddleware,
+    show_toolbar,
+    show_toolbar_with_docker,
+)
 from debug_toolbar.panels import Panel
 from debug_toolbar.toolbar import DebugToolbar
 
@@ -59,7 +63,8 @@ async def test_show_toolbar_docker(self, mocked_gethostbyname):
         with self.settings(INTERNAL_IPS=[]):
             # Is true because REMOTE_ADDR is 127.0.0.1 and the 255
             # is shifted to be 1.
-            self.assertTrue(show_toolbar(self.request))
+            self.assertFalse(show_toolbar(self.request))
+            self.assertTrue(show_toolbar_with_docker(self.request))
         mocked_gethostbyname.assert_called_once_with("host.docker.internal")
 
     async def test_not_iterating_over_INTERNAL_IPS(self):