host.docker.internal DNS lookup causes 15s delay in offline environments

[luzik]

In environments without internet access and without a DNS resolver (fully offline setups), the use of socket.gethostbyname("host.docker.internal") causes a 15-second delay on every request due to DNS resolution timeout. This is particularly problematic when DEBUG = True is required during development or internal deployments.

Details:
I encountered this issue in a system that must remain completely offline (air-gapped). There is no DNS resolver available, and thus, any DNS lookup (such as for host.docker.internal) results in a timeout of ~15 seconds. The following code snippet demonstrates the issue:

    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
        # up the IP address of the docker host.
        # This is not guaranteed to work.
        docker_ip = (
            # Convert the last segment of the IP address to be .1
            ".".join(socket.gethostbyname("host.docker.internal").rsplit(".")[:-1])
            + ".1"
        )

This logic gives no way to avoid the DNS lookup if DEBUG = True. The delay occurs on every request, making development/debugging extremely painful in such setups.

Additionally, tools like the Django Debug Toolbar exacerbate the issue by triggering this DNS lookup repeatedly, which compounds the delay.

Suggested Solution:
Introduce a configurable way to bypass the host.docker.internal resolution in known offline environments. Perhaps a try-except with a timeout or a setting that disables Docker IP detection entirely.

Environment:

Offline setup (no DNS resolver, no internet)

Docker-based deployment

Django (with Debug Toolbar in development)

[matthiask]

Thanks for your report!

If the environment is completely air-gapped (and therefore untrusted outsiders cannot ever access it) can't you add the known IP addresses of people accessing the service to the INTERNAL_IPS setting?

You should also be able to use a IP range list, see #1929

If the REMOTE_ADDR in INTERNAL_IPS check succeeds, you shouldn't ever hit the DNS resolver below.

Alternatively, you should be able to circumvent the check by using something like

# Don't use this in production environments accessible to the internet
DEBUG_TOOLBAR_CONFIG = {"SHOW_TOOLBAR_CONFIG": lambda request: DEBUG}

... or something similar.

[luzik]

Thanks for the response!

Yes, the Debug Toolbar is enabled only for my development machine, and I don’t experience any issues with it personally.

The problem arises for other users accessing the application — those who should not have access to the toolbar. Even though they never see the toolbar, the request still hits the code path with socket.gethostbyname("host.docker.internal"), resulting in a ~15s delay per request in an offline environment.

This creates a poor user experience in air-gapped environments, where any unnecessary DNS lookup causes major slowdowns.

[matthiask]

You should be able to solve this by using something like:

# Don't use this in production environments accessible to the internet
DEBUG_TOOLBAR_CONFIG = {"SHOW_TOOLBAR_CONFIG": lambda request: DEBUG and request.META.get("REMOTE_ADDR") == "127.0.0.1"}

We want to keep the Docker IP check in there because it is one less hurdle for people to jump over when setting up the project, or at least that's the thinking behind it.

[luzik]

Did you mean SHOW_TOOLBAR_CALLBACK ?

[matthiask]

Oh, yes. Sorry for that.

[luzik]

Thanks, that workaround works perfectly — clean and effective!

In my humble opinion though, adding a DNS lookup (host.docker.internal) to every Django request — even conditionally — might not be the best way to solve the Docker detection issue.

Hunting down this issue took quite a bit of time and effort, so perhaps a clearer mention in the docs or a toggle to disable the Docker check altogether could help others avoid the same pain.

Thanks again for your help!
Feel free to close this issue.

[matthiask]

Good to hear! I added the documentation label because we should probably re-check the documentation and mention this somewhere.

Additionally, I am getting the impression that asking the DNS resolver upon each request maybe doesn't actually make a lot of sense. We could maybe do the DNS resolving once per server startup while also printing a message to the console mentioning that we're doing this to make this behavior more discoverable.

Something like:

The debug toolbar is trying to resolve the IP of host.docker.internal to make it work automatically in Docker environments...

... and then print the IP on success (success! 10.0.0.1) or print a failure message (DNS resolving failed, not in a Docker environment) if it fails.

That's just me thinking out loud. I think it would be a good idea to add something like this but I'm not the only one with opinions, luckily.

[tim-schilling]

@matthiask I wonder if we should have docker folks opt-in during the installation?

[matthiask]

@tim-schilling How would such an opt-in check work? Using a setting?

I think I was sceptical about the autoconfiguration at the start, but something like #2118 seems like a good compromise to me: If it works then great, if not people only have to wait once per server startup and they are even informed about it.

Otherwise: maybe I'm imagining things but I recall a discussion about adding variants of the show_toolbar callback.

[dr-rompecabezas]

I did not experience the 15-second delay in my testing, but I am not entirely confident I have set up the proper testing environment. See #2118 (comment).

[luzik]

In my env I found it by using tcpdump. Django host was sending dns lookups for host.docker.internal, and resolver is configured in that way, where it do not replay at all to the non internal domains

[matthiask]

As discussed on the djangonauts call:

We are currently impacting people negatively who aren't using Docker at all and we shouldn't do that.

The way to go would be to introduce a new toolbar callback, something like "debug_toolbar.middleware.show_toolbar_with_docker", and document that here:
https://django-debug-toolbar.readthedocs.io/en/latest/installation.html#configure-internal-ips

The logic to autodetect the docker gateway IP should be moved to the new callback. The IP doesn't have to be cached, so the complexity from #2118 including the setting_changed handler can be dropped for a more straightforward implementation.