Docker Networking Without the Guesswork
· docker
Most developers learn Docker networking when it breaks. They run docker compose up, everything works and they move on, and then one container can’t talk to another and suddenly everyone is guessing ports like it’s a combination lock.
The root cause is usually boring, because somewhere along the way internal container traffic and host port mappings got mixed together. This post pulls the two apart, shows how containers find each other by name, and ends with a small web app and database wired up by hand.
What Is a Docker Network?
If you already know what a Docker network is, skip to the next section.
A Docker network is a virtual layer that wires containers together. Each container gets its own IP, its own hostname, and a direct line to every other container on the same network. Docker handles all of this quietly, which is genuinely useful until something breaks and you’re staring at Connection refused with no idea which port you’re supposed to hit.
Three details about it matter for everything that follows:
- Containers on the same user-defined network (Compose creates one for you) talk to each other by IP, by name or by alias. Docker’s built-in DNS resolves the names, so no
/etc/hostshacking is required. On the defaultbridgenetwork, containers can only reach each other by IP. - Nothing is exposed to the outside world by default, and you have to explicitly punch a hole. This is a good default, so treat it as a feature and not an obstacle.
- Name resolution inside a user-defined network just works. One container calls another by name, Docker resolves it, and traffic flows.
Internal Ports
Most tutorials gloss over the part that matters, which is that containers on the same network communicate using internal ports. An internal port is the port the application listens on inside the container, and that’s it.
Port mappings like -p 8080:3000 are irrelevant inside the network. Those mappings exist solely for traffic coming from outside (your browser, your host machine, the wider internet), and containers don’t use them.
If a container called app runs a service on port 3000, any other container on the same network reaches it at app:3000. Not at app:8080, and not at localhost:8080. Just app:3000.
Why does this trip people up? Because -p 8080:3000 looks like it’s defining the port. It is not. It defines a forwarding rule for external traffic and internal traffic never touches it.
DNS and Service Names
Docker runs an embedded DNS server for user-defined networks, and it resolves each container’s name to that container’s IP. You don’t configure this and you don’t install anything, it’s just there (but not on the default bridge network, which is why the examples here create their own network).
Name a container db and every other container on the network can resolve db as a hostname, so when you connect to db:5432 you’re talking to Postgres. Clean, tight, zero ceremony.
Sometimes the container name isn’t what you want downstream services to use, and aliases give you that flexibility:
docker run --network my-network --name db --network-alias primary-db mydatabaseNow the container answers to both db and primary-db, so it is the same container with two DNS entries. This is useful when you’re migrating names or running blue-green setups and you don’t want to rewire everything.
Docker Compose creates DNS entries from service names automatically, so look at a file like this:
services:
app:
image: myapp
db:
image: mydatabaseThe app container connects to the database at db:5432. There are no network aliases to configure and no IP addresses to hardcode because Compose just wires it up. This is the part that works so well people forget there’s a network underneath.
Port Forwarding
Everything above happens inside the Docker network. At some point you need the outside world to reach a container, because your browser needs to hit the web app or a monitoring tool needs to scrape metrics or whatever, and that’s what -p does:
docker run -p 8080:3000 mywebappThe second number, 3000, is the port the app listens on inside the container. The first number, 8080, is the port on the host that forwards traffic into the container. Hit http://localhost:8080, and Docker routes the request to port 3000 inside the container. The container has no idea the outside world thinks the port is 8080, it just sees traffic on 3000.
This is the split that matters. Inside the network, containers use the internal port (3000). Outside the network, the host and the internet use the mapped port (8080). Confuse these two and you’ll spend an afternoon debugging something that isn’t broken. Ask me how I know.
Docker Compose does the same thing with ports:
services:
web:
build: .
ports:
- "8080:3000"This maps port 3000 inside web to port 8080 on the host. But – and this is the part people miss – other containers on the same network still use web:3000. The port mapping is purely an external concern. Internal traffic doesn’t care about it. Won’t use it. Can’t use it.
Internal Versus External Access
Two worlds. Keep them separate in your head.
For internal access, containers on the same network use the container name (or alias) plus the internal port. If a web server in webapp listens on 3000, other containers reach it at webapp:3000. There is no port mapping and no host networking involved, just a name and a port.
For external access, the host or the internet needs two steps. First, map the container’s port to a host port (-p 8080:3000). Then access the service through the host port (http://localhost:8080).
So the entire model is that internal access is a name plus the internal port, and external access is the host plus the mapped port. If you remember nothing else, remember this split.
Putting It All Together
Enough theory, let’s wire up a web app that talks to a database, where the web app listens on port 5000 and the database listens on port 5432.
-
Create the network:
docker network create my-app-network -
Start the database:
docker run -d --network my-app-network --name db --network-alias primary-db mydatabaseThe database is reachable by name as
db:5432and by alias asprimary-db:5432. -
Start the web app:
docker run -d --network my-app-network --name webapp mywebapp -
The web app connects to the database at
db:5432orprimary-db:5432with no port mapping and no host involvement, so it is just two containers on the same network talking directly. -
Expose the web app externally. The container from step 3 already holds the name
webapp, so remove it first:docker rm -f webapp docker run -d -p 8080:5000 --network my-app-network --name webapp mywebappNow the outside world reaches the web app at
http://localhost:8080. The database stays hidden with no port mapping, no exposure and no attack surface, which is exactly how it should be.
The Model
Docker networking is simpler once you stop mixing up internal ports and external port mappings. Internal ports are for containers talking to containers, and port mappings are for the outside world talking to containers. DNS handles name resolution so you never hardcode an IP, and Compose automates the wiring so you rarely think about networks at all.
That’s the whole model. Most Docker networking bugs get less mysterious once you keep that split in your head.