Docker Networking (Part 1): How a Request Reaches Your Container
Docker networking from scratch: how a container gets its own network and IP, how traffic gets out and in, why the app must bind 0.0.0.0, how to keep nginx in front, and what really changes between bridge and host networking.
Docker series: 1. Docker: A Practical Approach Β· 2. Deployment in Practice Β· 3. Networking Part 1 Β· 4. Networking Part 2: Subnets, IP Collisions and the Default Bridge
π Table of Contents
- What problem Docker networking solves
- 1. A container has its own network
- 2. How the container is wired to the host: the bridge
- 3. The way out: outbound NAT
- 4. The way in: publishing ports
- 5. Why the app inside MUST bind
0.0.0.0 - 6. Putting it together: the full request chain
- 7. The other mode: host networking
- 8. Who manages what
- TL;DR
What problem Docker networking solves
A container is just a process on the host, but Docker deliberately isolates it, and that includes its network. The container gets its own network interfaces, its own IP address and even its own localhost. That isolation is useful (containers canβt trip over each otherβs ports), but it immediately raises three questions:
- What network does the container actually have? What is its IP, and where does it come from?
- How does it get out? Your app needs to call APIs, pull packages, go through the corporate proxy.
- How do requests get in? Users, or nginx on the host, need to reach the app inside.
Everything in this post answers one of those three. The running example is a real setup: a FastAPI app (uvicorn) in a container on an Ubuntu server, with nginx on the host in front of it. By the end youβll be able to follow a request hop by hop from the browser to the app, and know why each hop behaves the way it does.
1. A container has its own network
Linux has a feature called a network namespace: a separate, private copy of the network stack, with its own interfaces, IP addresses, routing table and ports. Docker puts every container (in the default mode) into its own namespace.
You can see it directly:
1
docker run --rm alpine ip addr
1
2
3
4
1: lo: <LOOPBACK,UP> ...
inet 127.0.0.1/8 scope host lo
2: eth0@if12: <BROADCAST,MULTICAST,UP> ...
inet 172.17.0.3/16 brd 172.17.255.255 scope global eth0
So inside the container there are (at least) two interfaces:
lo:127.0.0.1, reachable only from inside the containereth0: e.g.172.17.0.3, the containerβs address on the Docker network. This is how Dockerβs port forwarding reaches it.
The key idea of this whole post: the containerβs
127.0.0.1is not the hostβs127.0.0.1. There are two separate loopbacks. βlocalhostβ inside a container means βthis container onlyβ.
2. How the container is wired to the host: the bridge
A private network on its own is useless; it has to connect to something. By default Docker connects containers to a bridge, a virtual network switch living on the host:
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
Host
ββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ
β β
β ens192 (real NIC, host IP) β
β β² β
β β NAT β
β docker0 172.17.0.1 β virtual switch + gateway β
β β β β
β vethA vethB β virtual "cables" β
β β β β
β ββββββ΄ββββββ ββββββ΄ββββββ β
β β eth0 β β eth0 β β
β β172.17.0.2β β172.17.0.3β β each container's namespace β
β ββββββββββββ ββββββββββββ β
ββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ
docker0is the default bridge. It has an IP of its own (172.17.0.1), which is the gateway for the containers.- Each container is plugged in with a veth pair: a virtual cable with one end inside the container (seen as
eth0) and the other end on the host, attached todocker0. - Each container gets an IP from the bridgeβs subnet (
172.17.0.0/16by default).
You can see the host side of this with ip -br addr: docker0, plus one veth... per running container.
Where that
172.17.0.0/16subnet comes from, why Compose projects get their own bridges (br-xxxx) with other subnets, and how those subnets can collide with a corporate network, is the subject of Part 2.
Network modes at a glance
The bridge is the default, but not the only option:
| Mode | What the container gets | Typical use |
|---|---|---|
| bridge (default) | Own namespace, own IP on a Docker bridge, NAT to the outside | Almost everything |
| host | No own namespace: shares the hostβs network stack directly | Workaround when bridging is broken; raw network performance |
| none | Own namespace with only lo; no connectivity at all | Fully isolated jobs |
(Compose projects use a user-defined bridge, which is the same idea with its own subnet and built-in DNS by service name. Overlay and macvlan networks also exist, for multi-host and special cases, and arenβt needed here.)
Sections 3β6 are all about bridge mode. Host mode gets its own section at the end, because it changes almost every rule.
3. The way out: outbound NAT
When the app calls an external API, the packet leaves eth0 with source address 172.17.0.3. Nobody outside knows that private address, so on its way out through the hostβs real NIC Docker NATs it (source NAT / βmasqueradeβ): the source becomes the hostβs own IP. Replies come back to the host, and Linux translates them back to the container.
1
container 172.17.0.3 βββΆ docker0 βββΆ NAT: source = host IP βββΆ ens192 βββΆ outside
Two consequences worth remembering:
- The outside world only ever sees the hostβs IP, never container IPs.
- Because addresses are translated at the host, bridge subnets are local to each host. Two servers can use the same container subnet without conflict.
Docker sets this up automatically with iptables rules. You donβt configure anything for the way out.
4. The way in: publishing ports
The way in is the opposite problem: a request arrives at the hostβs IP, and has to be forwarded to a container IP that nobody outside can see. Thatβs what publishing a port does:
1
docker run -p 9090:8080 my-fastapi-image
-p HOST:CONTAINER β -p 9090:8080 means βhost port 9090 β container port 8080β. Docker installs a forwarding rule (destination NAT): anything arriving at host port 9090 is rewritten to 172.17.0.3:8080 and delivered through the bridge.
1
client βββΆ host:9090 βββΆ Docker forwards βββΆ 172.17.0.3:8080 (container eth0) βββΆ app
Under the hood there are two forwarders: iptables NAT rules for traffic arriving from the network, and a small
docker-proxyprocess for traffic from the host itself (e.g.127.0.0.1:9090). Thatβs whyss -tlnpon the host showsdocker-proxylistening on9090.
Which port does nginx point to?
nginxβs proxy_pass uses the HOST port, never the container port. nginx runs on the host, and on the host only 9090 exists. 8080 exists only inside the containerβs namespace.
1
2
3
location /api/ {
proxy_pass http://127.0.0.1:9090; # β published HOST port
}
5. Why the app inside MUST bind 0.0.0.0
Now the piece that trips everyone up. Docker forwards traffic to the containerβs IP (eth0), not its loopback. So what the app listens on decides whether the forwarded traffic finds anyone:
- App binds
127.0.0.1:8080β listens only on the containerβs loopback β forwarded traffic arrives oneth0β nobody listening β connection refused. The app looks βupβ but is unreachable. - App binds
0.0.0.0:8080β listens onloandeth0β forwarded traffic accepted β
1
2
3
4
5
6
container network namespace
ββββββββββββββββββββββββββββββββββββ
Docker NAT ββββΆ β eth0 172.17.0.3:8080 β
β β
β lo 127.0.0.1:8080 βββ app bound here only?
ββββββββββββββββββββββββββββββββββββ β eth0 has no listener β refused
1
CMD ["uvicorn", "app.main:app", "--host", "0.0.0.0", "--port", "8080"]
Classic symptom:
docker logsshowsUvicorn running on http://127.0.0.1:8080,docker psshows the container as Up, andcurl localhost:9090on the host givesconnection resetorempty reply. The app is fine. It just listens on the wrong interface.
localhost only makes sense for something that must never be reached from outside its own machine/namespace (e.g. a helper daemon).
Isnβt 0.0.0.0 insecure?
0.0.0.0 inside the container is normal and safe. Binding it inside the container doesnβt decide whatβs reachable from outside. That depends on:
- (a) the Docker port mapping (only published ports are exposed),
- (b) the host firewall,
- (c) nginx in front.
The real exposure is on the host side.
-p 9090:8080publishes on the hostβs0.0.0.0:9090, so itβs reachable from the network directly, bypassing nginx. Dockerβs iptables rules can also bypassufw: the forwarding from section 4 happens in rules that run beforeufwβs, so aufw deny 9090does not block a published port.
To force all traffic through nginx, bind the published port to the host loopback:
1
docker run -p 127.0.0.1:9090:8080 my-fastapi-image
1
2
ports:
- "127.0.0.1:9090:8080"
Now only nginx (on the same host) can reach it. Check what the host actually listens on:
1
2
3
ss -tlnp | grep 9090
# 0.0.0.0:9090 β reachable from the network
# 127.0.0.1:9090 β only from this host (nginx)
What if I run uvicorn without Docker?
1
uvicorn app.main:app --host 127.0.0.1 --port 8000
Here 127.0.0.1 is actually the better choice: nginx is on the same machine, so it can reach loopback, and nobody else can bypass nginx.
The rule flips in a container, because βsame machineβ for the container means βinside the containerβ (section 1: two separate loopbacks).
| Where the app runs | Bind to | Why |
|---|---|---|
| Directly on the host, behind nginx | 127.0.0.1 | nginx shares the loopback; no one can bypass nginx |
| Inside a container (bridge) | 0.0.0.0 | Docker forwards to the containerβs eth0; restrict exposure with 127.0.0.1: on the published port instead |
6. Putting it together: the full request chain
Every hop is now explained, so here is the whole path in one picture:
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
Internet / internal network
β
βΌ
βββββββββββββββββββββββββββββββββββ
β Host machine (Ubuntu) β
β β
β nginx (port 80) β β systemd-managed, pre-installed
β β proxy_pass to β
β β 127.0.0.1:<host port> β
β βΌ β
β Docker published port β β e.g. -p 127.0.0.1:9090:8080
β β forwards to β
β βΌ β
β βββββββββββββββββββββββββββ β
β β Container (172.17.0.3) β β
β β FastAPI on 0.0.0.0:8080 β β
β βββββββββββββββββββββββββββ β
βββββββββββββββββββββββββββββββββββ
- Request arrives at host port 80 β nginx.
- nginx matches
location /api/βproxy_pass http://127.0.0.1:9090(the published host port, section 4). - Docker forwards host
9090β container IP172.17.0.3port8080(section 4). - uvicorn inside the container, bound to
0.0.0.0:8080, accepts it (section 5). - Response travels back: container β Docker β nginx β browser.
When something breaks, walk the same chain and check each hop: is nginx pointing at the right host port? Is the port published (ss -tlnp)? Is the app bound to 0.0.0.0 (docker logs)?
7. The other mode: host networking
Everything above is bridge mode, Dockerβs default. Youβll meet host mode too, usually as a workaround when bridge networking is broken on a host (see Part 2).
What host networking actually does
network_mode: host (run) and --network=host (build) mean the same thing: the container/build shares the hostβs network stack directly. No docker0 bridge, no NAT, no private 172.17.x IP. The process uses the hostβs interfaces, IPs, and routing table as if it were a normal process on the machine. In terms of section 1: there is no separate namespace.
1
2
3
services:
my-app:
network_mode: host
So is it 9090 or 8080 now?
This appβs uvicorn binds 8080 inside the container. What the host sees depends on the mode:
| Mode | What happens | Reach the app at |
|---|---|---|
bridge (default, ports: "9090:8080") | Container has its own IP; Docker does NAT translating host 9090 β container 8080 | http://<host>:9090 |
host (network_mode: host) | No container IP, no NAT; app binds the hostβs real 8080 directly | http://<host>:8080 |
So:
- Bridge: app on
8080inside β Docker maps it β host exposes9090. The9090:8080line does that translation. - Host: the
9090:8080mapping is ignored; the app is on the hostβs8080.
This is official Docker behaviour. In host mode Docker even prints:
1
WARNING: Published ports are discarded when using host network mode
Docs: βif you run a container which binds to port 80 and you use
hostnetworking, the containerβs application is available on port 80 on the hostβs IP address β¦ port mapping doesnβt take effect, and the-p,--publish,-Pβ¦ options are ignored.β
To expose a different external port in host mode there is no mapping layer, so you must change the port the app itself binds, i.e. edit the uvicorn ... --port 8080 in the Dockerfile CMD (e.g. to --port 9090). Remember to update nginxβs proxy_pass to match.
In host mode, section 5βs rule flips back: the containerβs
127.0.0.1is the hostβs loopback. Binding127.0.0.1works with nginx on the same host, and0.0.0.0now means every host interface.
Why do people recommend bridge instead of just using host?
host is simpler and faster, but it removes the isolation that Docker exists to provide. bridge is the default for good reasons:
- Port isolation / no clashes. On
bridge, each container has its own IP, so ten containers can all listen on8080internally and you map them to different host ports (9090:8080,9091:8080, β¦). Onhost, theyβd all fight over the hostβs real8080. - Network isolation / security. A bridged container only sees what you expose. A host-networked container can see all host interfaces and loopback services (databases, admin ports) that were never meant to be reachable from a container β bigger attack surface.
- Portability.
bridgebehaves the same everywhere.hostnetworking is a Linux feature: on Docker Desktop for Mac/Windows it is only available as an opt-in setting in recent versions (4.34+), so donβt assume it behaves identically there. - Clean teardown. Bridged containers have self-contained virtual interfaces that vanish with the container. Host mode leaks nothing but offers no boundary either.
Rule of thumb: use
bridge(the default) in normal operation; reach forhostonly as a workaround when the bridge is broken/disabled, or when you specifically need raw host network performance or access.
Does host networking harm the host?
No. It does not modify the hostβs networking or create the risky docker0 subnet. It simply lets the container use the hostβs existing, already-working network. Thatβs why itβs the safe workaround when the bridge is disabled, unlike re-enabling the default bridge (which recreates 172.17.0.0/16 and can collide with corporate routing, see Part 2). The only trade-offs are the isolation losses listed above (shared ports, broader visibility), not host breakage.
8. Who manages what
On a shared or company-provisioned server, it helps to know which pieces are yours:
| Thing | Managed by | My responsibility? |
|---|---|---|
| nginx install + unit file | platform/provisioning, systemd | no |
nginx site config (sites-enabled/my-app) | me (with sudo) | yes |
| Docker container / uvicorn | me | yes |
Port alignment (proxy_pass β published port) | me | yes |
--host 0.0.0.0 in container | me | yes |
TL;DR
- A bridged container has its own network namespace: its own
eth0IP and its own127.0.0.1. - Out: Docker NATs container traffic to the hostβs IP. In: a published port (
-p HOST:CONTAINER) forwards host traffic to the containerβseth0. - nginx points at the host port. The app inside binds
0.0.0.0; binding127.0.0.1makes it unreachable. - Restrict exposure on the published port (
127.0.0.1:9090:8080), not inside the container. Donβt rely onufwfor published ports. - Host mode: no namespace, no NAT,
ports:ignored, the appβs own port is the host port.