VPS Tutorials
Docker container cannot reach the host: names, host-gateway and listeners
Choose service names or host addresses correctly, configure host-gateway, inspect listeners and firewall paths, and distinguish port publication from outbound access.

The host's curl http://127.0.0.1:8000 works, but a containerized application gets Connection refused. Check the destination first: localhost in an ordinary bridge container means that container, not the VPS host.
For another container, normally use its service name on a shared network. For a service genuinely running on the host, inspect host.docker.internal and the host's listening address. This guide concerns ordinary Linux Docker Engine bridge networking; Docker Desktop, host mode and rootless deployments need their own implementation checks.
| Connection | Address to consider | Common mistake |
|---|---|---|
| app → backend on the same network | http://backend:8000 | localhost:8000 |
| app → API directly on the VPS host | Reachable host address or configured host alias | Container's 127.0.0.1 |
| VPS host → published container port | Host binding and published port | Confusing target and published ports |
| User's browser → VPS service | Public domain or authorized ingress | Docker-internal service name |
With a remote Docker context, the host is the daemon's machine, not the laptop running the CLI. Check docker context show before editing listeners or firewalls.
Compose networking provides service-name discovery on a common network, without depending on changing container IPs. Use the destination's internal listening port.
This connectivity demonstration publishes no public port. Its Python image is for testing, not a production deployment template:
services:
app:
image: python:3.14-alpine
command: ["python", "-c", "import time; time.sleep(3600)"]
environment:
BACKEND_URL: "http://backend:8000"
backend:
image: python:3.14-alpine
command: ["python", "-m", "http.server", "8000", "--bind", "0.0.0.0"]
Both services join the project's default network. backend listens on 8000; app uses backend:8000, without adding ports for their communication.
Run the example in a separate test directory, then check from app:
docker compose up -d
docker compose exec app python -c 'import os,urllib.request; print(urllib.request.urlopen(os.environ["BACKEND_URL"], timeout=5).status)'
It should report an HTTP status when the demonstration is running. Do not overwrite production or treat the temporary file server as an API. Different Compose projects have different default networks. For cross-project communication, join an appropriate shared network explicitly and avoid conflicting aliases.
If the API runs on the VPS itself, add an alias to the actual app service. This is another independent demonstration:
services:
app:
image: python:3.14-alpine
command: ["python", "-c", "import time; time.sleep(3600)"]
extra_hosts:
- "host.docker.internal:host-gateway"
environment:
BACKEND_URL: "http://host.docker.internal:8000"
It does not start a host API; your real service must provide port 8000. extra_hosts maps a name to an address. It does not create a service, change its listener or permit firewall traffic.
The daemon reference describes host-gateway. Its default relates to the default bridge and can be overridden in daemon configuration. Do not hard-code 172.17.0.1 for every VPS or assume a custom network's gateway is always this address.
The engine must support the special value. Successful Compose parsing does not prove the engine can create the mapping. Check engine and platform if unsupported; host-gateway is not a normal public DNS name.
In the original project, validate and update app:
docker compose config --quiet
docker compose up -d --no-deps app
Keep service, -f, environment-file and project options consistent. Check persistent mounts and backups first; no volume deletion is needed. Restart alone may not apply changed container settings; see Compose changes not applied.
On the host:
sudo ss -lntp '( sport = :8000 )'
ip -brief address
A service listening only on 127.0.0.1:8000 is usually unavailable through another host address on an ordinary bridge. A host alias does not forward host loopback ports onto the bridge.
Bind to a reachable host address within your intended access boundary and permit only necessary sources. If the service only supports loopback, use a controlled proxy or a different deployment arrangement. Do not expose a database on every interface and public port just to make this test pass.
The demonstration's Python container can separate name resolution from HTTP access:
docker compose exec app python -c 'import socket; print(socket.gethostbyname("host.docker.internal"))'
docker compose exec app python -c 'import os,urllib.request; print(urllib.request.urlopen(os.environ["BACKEND_URL"], timeout=5).status)'
If the real image lacks Python, use an existing diagnostic tool. A missing command is not a network failure. These are HTTP checks; database protocols need their own clients.
| Result | Investigate |
|---|---|
| Name does not resolve | Alias absent from current container, typo or different environment |
| Connection refused | No listener at that address, or active rejection |
| Timeout | Routes, filtering and service responsiveness |
| HTTP 401 or database authentication rejection | Server responded; check credentials and application settings |
Check listener, Docker network and host firewall together. A public port working does not prove bridge-origin traffic is allowed.
To reach the demonstration backend from the VPS host, merge this under backend:
services:
backend:
ports:
- "127.0.0.1:18000:8000"
It maps host loopback port 18000 to container port 8000; see port publishing. Merge it with the backend image configuration; the fragment alone is not a complete service.
Same-network app still uses backend:8000, not backend:18000. The host uses its published binding. Another ordinary bridge container cannot make a host-loopback binding on 18000 equivalent by substituting host-gateway.
app does not need ports merely to reach a host service. Keep incoming publication and outgoing access separate.
Docker Desktop supplies host.docker.internal with its host/VM networking arrangement. Do not assume the same default on Linux Engine or infer Linux topology from a Mac lacking docker0.
network_mode: host is a different design. The host driver shares the host network namespace instead of assigning a separate container network IP. It changes port conflicts and isolation; it is not a universal bridge troubleshooting patch, and original port-publishing assumptions no longer apply.
For a Nginx Proxy Manager container unable to reach a host program, check its backend destination with this address/listener/network sequence, then consult the Nginx Proxy Manager guide.
Confirm the request originates inside that container and reaches the intended host and port, then test the actual operation. Parsing, name resolution, TCP connectivity and successful authentication are separate milestones.
The source article parsed three configurations with Docker Compose 2.17.3: shared-network, host-gateway, and shared-network plus publishing fragment. The merged binding was 127.0.0.1:18000 to 8000; app still used backend:8000. The local Docker daemon was not running. These static checks do not prove working Linux bridge traffic, host-gateway or a production database connection.