Docker networking confuses people because the defaults are unintuitive and the mental model isn't obvious from the CLI. A container can reach the internet by default, but two containers on the same host can't reach each other unless they're on the same network. Port publishing doesn't work the way most people expect on Linux hosts. Container-to-container DNS just works in Docker Compose but not when you run containers manually. Understanding why requires knowing a bit about how Docker uses Linux networking primitives.
This guide covers each Docker network driver, how DNS works inside containers, port publishing mechanics, and how Docker Compose handles multi-container networking.
Network drivers overview
Docker's networking system is pluggable — different drivers implement different networking behaviors. The built-in drivers are:
- bridge — the default for containers on a single host
- host — container shares the host's network namespace
- overlay — multi-host networking for Docker Swarm or Compose with multiple hosts
- macvlan — assigns a MAC address to each container so it appears as a physical device on the network
- none — disables networking entirely
- ipvlan — similar to macvlan but operates at Layer 3
Bridge networking: the default
When you run a container without specifying a network, Docker attaches it to the docker0 bridge network. This is a virtual Ethernet bridge — a software switch that forwards packets between container network interfaces and the host's physical interface.
Each container gets a virtual Ethernet pair (veth): one end is placed inside the container's network namespace as eth0, the other end is attached to docker0 on the host. The container gets an IP from Docker's private subnet (typically 172.17.0.0/16).
# View the default bridge network docker network inspect bridge # Containers on the default bridge can reach the internet # via NAT rules that docker manages in iptables/nftables # But they CANNOT reach each other by name — only by IP docker run -d --name app1 nginx docker run -it --rm busybox ping app1 # This FAILS docker run -it --rm busybox ping 172.17.0.2 # This works
The default bridge network has two important limitations: containers can't resolve each other by name, and all containers on it can communicate with each other by IP (no isolation). Both problems are solved by user-defined bridge networks.
User-defined bridge networks
Creating a custom bridge network gives you DNS-based service discovery and network isolation:
# Create a custom bridge network docker network create my-app-network # Containers on the same user-defined network can resolve each other by name docker run -d --name database --network my-app-network postgres docker run -d --name api --network my-app-network my-api-image # From inside the api container: # ping database ← works # curl database:5432 ← works
Docker's embedded DNS server (at 127.0.0.11 inside containers) handles name resolution for user-defined networks. It maps container names and network aliases to their current IPs. When a container is restarted and gets a new IP, the DNS entry updates automatically.
Containers can also be connected to multiple networks simultaneously:
docker network connect frontend-network api docker network connect backend-network api # api can now communicate with containers on both networks
Host networking
With --network host, the container shares the host's network namespace. It doesn't get its own IP — it uses the host's IP directly. Port bindings are not needed because the container's ports are the host's ports.
docker run --network host nginx # nginx is now listening on the HOST's port 80, not a container port
This eliminates the overhead of network address translation and can provide meaningfully better throughput for high-performance networking workloads. However, it also means:
- No port isolation — if two containers try to bind the same port, one fails
- No network namespace isolation — the container can see all host interfaces
- Port publishing (
-p) flags are ignored; they have no effect with host networking
Host networking is useful for monitoring agents (that need to see all network traffic on the host), high-performance proxies, and cases where the NAT overhead of bridge networking is measurably impactful. It doesn't work on macOS or Windows Docker Desktop because those run Docker inside a Linux VM — the "host" network is the VM's network, not your Mac's.
Port publishing
Port publishing (-p host_port:container_port) maps a port on the host to a port in the container's network namespace. Docker does this by adding iptables rules that DNAT (Destination NAT) incoming traffic on the host port to the container's IP and port.
docker run -p 8080:80 nginx # Traffic arriving at host:8080 is forwarded to the container's port 80 docker run -p 127.0.0.1:8080:80 nginx # Bind only to localhost — not accessible from other hosts docker run -p 80 nginx # Docker picks a random ephemeral host port; docker port80 shows it
A subtle point: -p 8080:80 binds on all interfaces (0.0.0.0:8080) by default. This means if your firewall is open, the port is accessible from outside the host. Always specify the bind address for sensitive ports: -p 127.0.0.1:8080:80.
Docker's iptables rules can interact unexpectedly with firewall software like ufw. Docker modifies iptables directly, and ufw's FORWARD chain rules don't apply to Docker's DOCKER-USER chain. A container with a published port may be accessible from outside the host even if ufw blocks that port. The fix is to add rules to the DOCKER-USER chain, not to ufw's INPUT or FORWARD chains.
Overlay networking for multi-host setups
Overlay networks span multiple Docker hosts. They're the networking layer for Docker Swarm services and can also be used standalone with Docker Compose when running across multiple hosts.
An overlay network uses VXLAN encapsulation: packets between containers on different hosts are wrapped in UDP packets and sent over the physical network. From the container's perspective, other containers are on the same flat network regardless of which host they're running on.
# Overlay networks require Swarm mode to be initialized docker swarm init docker network create \ --driver overlay \ --attachable \ my-overlay-network # Services on this network can reach each other by service name # regardless of which Swarm node they're running on
Each overlay network gets a private subnet (default /24). Docker maintains a distributed key-value store (using Raft consensus within Swarm) to coordinate IP assignments and routing across nodes.
The --attachable flag allows standalone containers (not Swarm services) to be connected to the overlay network. Without it, only Swarm services can join.
DNS inside containers
Every container has /etc/resolv.conf with a nameserver entry. For user-defined networks, this points to Docker's embedded DNS at 127.0.0.11. For the default bridge network or host networking, it points to the host's DNS resolver.
# Inside a container on a user-defined network: cat /etc/resolv.conf # nameserver 127.0.0.11 # options ndots:0 # Verify DNS is working nslookup database # resolves to the database container's IP nslookup google.com # external DNS also resolves via 127.0.0.11 → forwarded to host resolver
Docker's embedded DNS serves several record types:
- A records for container names and network aliases
- A records for service names in Swarm (round-robin across all task IPs)
- SRV records for Swarm services (used by DNS-based load balancers)
Network aliases allow multiple containers to share the same DNS name, creating a simple round-robin load balancer:
docker run -d --network my-net --network-alias web nginx docker run -d --network my-net --network-alias web nginx # DNS for "web" now round-robins between both containers
Docker Compose networking
Docker Compose automatically creates a user-defined bridge network for each project and connects all services to it. Services can reach each other by service name.
services:
api:
image: my-api
# No port publishing needed for internal communication
depends_on:
- database
database:
image: postgres
environment:
POSTGRES_PASSWORD: secret
nginx:
image: nginx
ports:
- "80:80" # Only nginx needs to publish to the host
depends_on:
- api
In this setup: api reaches database at hostname database:5432. nginx reaches api at api:8080. Only nginx is accessible from outside Docker.
Compose also supports multiple networks for isolation:
services:
frontend:
networks: [frontend]
api:
networks: [frontend, backend] # bridge between networks
database:
networks: [backend]
networks:
frontend:
backend:
frontend can reach api. api can reach database. frontend cannot reach database directly — it has no network in common.
External networks
Compose can connect services to a network created outside the Compose project:
networks:
shared-monitoring:
external: true
name: monitoring-network
This is useful for a monitoring stack (Prometheus, Grafana) in one Compose project that needs to scrape targets from other projects.
Macvlan and ipvlan
Macvlan assigns each container a unique MAC address and connects it directly to a physical network interface. The container appears as a separate physical device on the network and can get an IP from a DHCP server or a static assignment within the physical subnet.
docker network create \ --driver macvlan \ --subnet 192.168.1.0/24 \ --gateway 192.168.1.1 \ --opt parent=eth0 \ my-macvlan-network docker run --network my-macvlan-network --ip 192.168.1.10 nginx
Macvlan is useful for containers that need to be reachable at a fixed IP on the physical network without port publishing — legacy applications that require specific IP addresses, network monitoring tools, or applications that need to be accessible from VLAN-isolated segments.
The limitation: macvlan interfaces can't communicate with their parent interface by default. A container on a macvlan network can talk to other hosts on the physical network, but not to the Docker host itself. This is a Linux kernel limitation with macvlan.
Debugging container networking
Container can't reach external hosts. Check that IP forwarding is enabled on the host (sysctl net.ipv4.ip_forward should be 1). Check iptables for a MASQUERADE rule in the POSTROUTING chain: iptables -t nat -L POSTROUTING. If Docker was recently reinstalled, iptables rules may have been lost.
Two containers can't reach each other. Check they're on the same user-defined network. The default bridge network doesn't do DNS. Run docker network inspect <network> to see which containers are connected.
Published port isn't accessible from outside the host. Check the host firewall. Note that Docker may have bypassed ufw by writing directly to iptables — check iptables -L DOCKER. Also verify the container is actually listening on the port: docker exec <container> ss -tlnp.
DNS resolution fails inside container. Verify you're on a user-defined network (not the default bridge). Check /etc/resolv.conf inside the container. Try nslookup 127.0.0.11 to test if Docker's DNS is reachable. Also check that the --dns flag isn't overriding the default nameserver.
Visualizing how Docker Compose services connect to each other — which services share networks and which are isolated — helps catch misconfigured networking before deploying. InfraSketch parses Docker Compose files and maps services and their network relationships as a diagram.