keepcalculator

06 Numbers and Powers

Access Host Ports From a Docker Container

Card No. 06·72506 · Updated · Standard formula, shown below

This guide shows how to let a Docker container reach services running on the host machine’s network, such as a local database, API, or web server. You’ll learn the two main methods — using host.docker.internal and the host network mode — and how to choose between them. No prior Docker networking knowledge is required, but you should have Docker installed and be comfortable running basic commands.

What You’ll Need

  • Docker installed (Docker Desktop on Windows/macOS, or Docker Engine on Linux)
  • A host service running on a known port (e.g., MySQL on 3306)
  • Basic command-line access to your terminal or PowerShell

Step-by-Step

  1. Identify the host service and port. Confirm the service is listening on the host (e.g., localhost:5432 for PostgreSQL). Use netstat -an | grep 5432 (Linux/macOS) or netstat -an | findstr 5432 (Windows) to verify.
  2. Decide which method to use. The easiest and most portable is host.docker.internal, which works on Docker Desktop (Windows/macOS) and on Linux if you add a special flag. The alternative is the host network mode, which is Linux-only and gives the container direct access to the host’s network stack.
  3. For Docker Desktop (Windows/macOS): Run your container with --add-host=host.docker.internal:host-gateway (optional but recommended) and then use host.docker.internal as the hostname inside the container. For example, to connect to a PostgreSQL on the host: docker run -it --rm postgres:13 psql -h host.docker.internal -U myuser.
  4. For Linux with default bridge network: Start your container with --add-host=host.docker.internal:host-gateway. Then use host.docker.internal in your application’s connection string. Example: docker run --add-host=host.docker.internal:host-gateway myapp.
  5. Alternative: use the host network mode (Linux only). Run your container with --network host. This makes the container share the host’s network namespace, so localhost inside the container refers to the host. Example: docker run --network host myapp. This works only on Linux; on Windows/macOS it has limited support.
  6. Test the connection. Inside the container, use tools like curl, nc, or your application’s client to connect to the host service. For example, curl http://host.docker.internal:8080 or nc -zv host.docker.internal 3306.
  7. Update your application configuration. Replace any hardcoded localhost or 127.0.0.1 with host.docker.internal (or use the host network mode and keep localhost). This is often done via environment variables, e.g., DB_HOST=host.docker.internal.
  8. If the host service is bound only to 127.0.0.1, you may need to bind it to 0.0.0.0 as well. For example, start your database with --bind-address=0.0.0.0 (MySQL) or listen_addresses = '*' (PostgreSQL). This is a common gotcha.

Common Mistakes

  • Using localhost inside the container. In the default bridge network, localhost refers to the container itself, not the host. Always use host.docker.internal unless you’re on the host network.
  • Forgetting the --add-host flag on Linux. On Linux, host.docker.internal is not automatically added; without the flag, the name won’t resolve.
  • Host service bound only to 127.0.0.1. Many services default to listening only on the loopback interface, which the container cannot reach. Change the bind address to 0.0.0.0 or the Docker bridge IP.
  • Using host network mode on Docker Desktop. It does not work as expected on Windows/macOS; the container still runs inside a VM. Stick with host.docker.internal there.
  • Firewall blocking. Even if the service listens on all interfaces, a host firewall (like ufw or Windows Firewall) may block connections from Docker’s virtual network. Allow the port for the Docker subnet.

Tips

  • Prefer host.docker.internal for portability. It works across Docker Desktop and Linux (with the flag), so your app code stays the same.
  • Use environment variables for connection details. Set DB_HOST=host.docker.internal in your docker run command or docker-compose.yml to avoid hardcoding.
  • In docker-compose, add extra_hosts: - "host.docker.internal:host-gateway" to your service definition.
  • For development, consider using Docker Compose. It lets you define the network and host mapping clearly, making it easier for teammates.
  • Check the Docker bridge IP. If host.docker.internal fails, you can find the host’s IP on the Docker bridge (usually 172.17.0.1 on Linux) and use that directly.

Troubleshooting

  • Cannot resolve host.docker.internal. On Linux, ensure you added --add-host=host.docker.internal:host-gateway. On Docker Desktop, restart Docker if the name isn’t resolving.
  • Connection refused. Verify the host service is running and listening on the expected port. Check if it’s bound to 127.0.0.1 only; if so, change the bind address.
  • Timeout instead of refusal. A firewall is likely blocking the traffic. Temporarily disable the firewall (or add a rule) to test. On Linux, check iptables rules; on Windows, check Windows Defender Firewall.
  • Host network mode gives no internet. This is unusual; the host network should share the host’s connectivity. If DNS fails, check your host’s DNS settings.
  • Docker Desktop on Windows: still can’t connect. Ensure the service is listening on all interfaces (use netstat -an to see if it’s 0.0.0.0 or 127.0.0.1). Also, try using the host’s LAN IP instead of host.docker.internal.
  • Inside the container, curl is not installed. Use docker exec -it <container> sh and install curl or use wget. Alternatively, test with a language’s built-in tools (e.g., Python’s urllib).

Frequently Asked Questions

  • Can I use host.docker.internal on Linux without extra flags? No, on Linux you must add --add-host=host.docker.internal:host-gateway to your docker run command or extra_hosts in compose.
  • What is the difference between host.docker.internal and --network host? The former is a DNS name that resolves to the host’s IP from the container’s perspective, while the latter makes the container share the host’s network stack entirely, so localhost works but the container loses its own network namespace.
  • Does --network host work on Docker Desktop? On Windows and macOS, Docker Desktop runs containers in a VM, so host networking is not fully supported. It may work in some cases but is not reliable; use host.docker.internal instead.
  • Why does my container see the host’s service as localhost? Only when using --network host. In the default bridge network, localhost is the container itself.
  • Can I access a host port that is bound to 127.0.0.1? Not directly. You must change the service to bind to 0.0.0.0 or the Docker bridge IP, or use --network host (Linux only).
  • Is it safe to expose host services to Docker containers? Generally yes, but be aware that any container on the same Docker network can reach those ports. Use firewalls and only bind to the Docker bridge interface if you want to restrict access.

Related

Method: the standard formula for this calculation, rounded as each result states. See how the calculators work or report an error.

More cards in this drawer

The whole Numbers and Powers drawer →