Skip to content

ADR-003: host.docker.internal Uses Shared Network Gateway IP

Status

Accepted

Context

Docker's extra_hosts: host.docker.internal:host-gateway resolves to the docker0 bridge IP (172.255.255.1). On phil-app with Shorewall firewall, containers on custom bridge networks (192.168.x.x) cannot reach 172.255.255.1 — Shorewall's fw→dock OUTPUT chain only allows RELATED,ESTABLISHED traffic.

This affects any container that needs to reach a host-bound service (e.g., Prometheus scraping host.docker.internal:9101 for XFS quota metrics).

Decision

Instead of host-gateway, set host.docker.internal to the gateway IP of a shared network the container is already connected to.

Example for containers on prometheus-network (172.24.0.0/26):

extra_hosts:
  host.docker.internal: "172.24.0.1"

The gateway IP is the host's interface on that bridge — traffic stays within the same bridge, no cross-zone filtering applies.

Consequences

  • ✅ Works reliably with Shorewall without modifying firewall rules
  • ✅ Gateway IPs are stable (all networks statically defined in stack/.config/create-docker-networks.sh)
  • ✅ No Docker daemon configuration changes needed
  • ⚠️ Non-standard — new services must use the correct gateway IP for their network
  • ⚠️ Developers unfamiliar with the setup may use the default host-gateway and wonder why it fails
  • 🔗 See: services/network.md for network gateway IP reference table