How containers find each other
A Docker network with the bridge driver is a bridge on the host (docker0 for the default network,
br-<id> for the rest) plus its own subnet: 172.17.0.0/16, 172.18.0.0/16 and onward in order. A container
gets an address in it, and after a recreate the address may be different. That’s why neighbors are reached
by name.
Names are answered by the DNS built into Docker: in every container on a user-defined network it listens on
127.0.0.11 (nameserver 127.0.0.11 in the container’s /etc/resolv.conf). It knows the container name,
the compose service name and aliases — but only for neighbors on the network: from another network the name
db won’t resolve. The default bridge network, where docker run without --network lands, has no built-in
DNS at all: a neighbor is visible there only by address.
For each stack, compose creates a <project>_default network and puts every service without its own
networks: list on it. The project name is the stack directory name (The compose project name), so
a stack in /opt/umami gets the umami_default network.
Neighbors don’t need published ports: on one network a container sees all of the other’s ports. ports: is
only for access from the host and the outside, and Docker opens it past the firewall (Docker ports bypass the input chain).
Which network for what
| Network | What it gives | When to use it |
|---|---|---|
default bridge |
an address and internet access; no names | a one-off docker run --rm |
the stack network <project>_default |
neighbors by service name; compose creates and removes it with the stack | everything inside one stack |
your own shared one, external: true in compose |
neighbors from different stacks; the stack neither creates nor removes it | the proxy and the services behind it — the proxy network |
internal: true |
neighbors by name, no way out | a database, a cache — anything that only talks to its own |
network_mode: host |
the whole host network, no ports: needed; the host firewall treats it like a regular program |
the service needs the host network: device discovery over mDNS, hundreds of ports |
On a server with Traefik, a stack ends up laid out like this:
network proxy — shared per server, created once
├── traefik ports 80 and 443 published on the host
├── umami on two networks: Traefik reaches it here
└── memos
network umami_internal — internal: true, the umami stack only
├── umami DATABASE_URL=…@db:5432
└── db no ports on the host, no internet access
Setup
The example is an Umami stack with Postgres in /opt/umami on a server that already runs Traefik
(A service over HTTPS). The compose snippets below show only what concerns networks.
See which networks already exist
docker network ls --format '{{.Name}}\t{{.Driver}}' # bridge bridge # host host # none nullDocker always has these three.
hostis the host’s own network,noneis a container with no network, onlylo. Everything else in the list was created by us or by compose.Create a shared network for the proxy
sudo docker network create proxyOnce per server. Compose neither creates nor removes such a network:
docker compose downin any stack, even Traefik’s, leaves it alone, and the other services on it stay where they are.Connect the service to the shared network
services: umami: networks: [proxy, internal] labels: - "traefik.enable=true" - "traefik.docker.network=proxy" networks: proxy: external: trueexternal: true— compose looks for an existing network with this name and doesn’t add the project prefix.traefik.docker.networkis needed as soon as a service has more than one network. Without it, Traefik takes the container’s address from any of them — and if it took the address on the internal network, where Traefik itself isn’t, the request hangs untilGateway Timeout. The label holds the network name in Docker, as indocker network ls. If the compose key is different (traefik_proxy:withname: proxy), the label still saysproxy.Lock the database into an internal network
services: umami: environment: - DATABASE_URL=postgresql://umami:${DB_PASSWORD}@db:5432/umami networks: [proxy, internal] db: image: postgres:16-alpine networks: [internal] networks: proxy: external: true internal: internal: trueA network with
internal: truehas no way out:umamireaches the database by the namedb, while no packet from the database itself will get to the internet — it doesn’t need to. The database has noports:: its port5432is visible to a network neighbor anyway.Compose names the network
umami_internal: it adds the project name to the key from the file.A service’s
networks:list replaces thedefaultnetwork rather than adding to it. So for every service, list all the networks it should be on (networks replaces default).Bring the stack up and check names from inside the network
cd /opt/umami docker compose up -d docker run --rm --network umami_internal alpine ping -c1 -W2 db # PING db (172.19.0.2): 56 data bytes # 64 bytes from 172.19.0.2: seq=0 ttl=64 time=0.104 msA throwaway container on the same network finds
dbby service name: the name works across the whole network, not just inside the stack. Your subnet will differ — Docker hands them out in order.
A service on the host itself
Sometimes the program runs on the host and a container talks to it: Ollama on the host and a web UI for it in
a container. 127.0.0.1 inside the container is the container itself, so give it a name for the host:
services:
open-webui:
extra_hosts:
- "host.docker.internal:host-gateway"
Docker substitutes the address of the docker0 bridge for host-gateway, usually 172.17.0.1, and the
container goes to http://host.docker.internal:11434. A service that listens only on 127.0.0.1 won’t answer
on that address: Ollama does exactly that by default and needs OLLAMA_HOST=0.0.0.0.
The host firewall closes such a port to the outside: a program on the host itself, unlike a published Docker
port, receives packets through input. A request from a container to the host is incoming for the firewall
too, so ufw with default deny incoming drops it as well until there’s a rule
sudo ufw allow from 172.16.0.0/12 to any port 11434. 172.16.0.0/12 covers Docker’s default subnets,
172.17–172.31. Check from another computer that the port is closed from the outside (A model on your own hardware,
“How to check”).
If it doesn’t work
A container can’t find its neighbor: could not translate host name "db" to address or getaddrinfo ENOTFOUND db
- Cause
- They’re on different networks. Often because the service got a
networks:list and left thedefaultnetwork, where the database stayed (networks replaces default). - Fix
- See who’s on the network:
docker network inspect umami_internal --format '{{range .Containers}}{{.Name}} {{end}}'. Put both services on one network.
Containers started with docker run; the neighbor answers by IP, but by name — bad address
- Cause
- Without
--networka container lands on the defaultbridgenetwork, which has no built-in DNS. - Fix
- Create your own network and run with
--network, or move the launch to compose: it creates the stack’s network itself.
network proxy declared as external, but could not be found
- Cause
- Compose doesn’t create a network with
external: true: it’s created once per server. - Fix
sudo docker network create proxy, thendocker compose up -dagain.
The service is on two networks, and Traefik returns Gateway Timeout — always or after a recreate
- Cause
- Without the
traefik.docker.networklabel, Traefik takes the container’s address from any of its networks and may pick the address on the internal one, which Traefik itself isn’t connected to. - Fix
- Add the label
traefik.docker.network=proxy. The value is the network name fromdocker network ls, not the key from compose.
A host service doesn’t open from the container at 127.0.0.1
- Cause
127.0.0.1inside a container is the container itself: it has its own network and its ownlo.- Fix
extra_hosts: ["host.docker.internal:host-gateway"]and the addresshost.docker.internal. The host service listens on0.0.0.0; ufw closes it from the outside and lets the Docker subnets in.
A new stack came up, and the server vanished for machines on the home or office network
- Cause
- The new Docker network got a subnet from
192.168.0.0/16, and it clashed with the network the server is reached from. - Fix
- Set your own address pool in
daemon.json(Docker subnet clashes with home network).
How to check
Which networks the container is on, and with which addresses:
docker inspect umami-umami-1 --format '{{range $k, $v := .NetworkSettings.Networks}}{{$k}} {{$v.IPAddress}}{{"\n"}}{{end}}'
# proxy 172.18.0.5
# umami_internal 172.19.0.3
Who’s on the shared network — Traefik and every service behind it:
docker network inspect proxy --format '{{range .Containers}}{{.Name}} {{end}}'
The database can’t reach the outside:
docker compose exec db wget -T 5 -q -O /dev/null https://example.org && echo "has access" || echo "no access"
# no access