Stage 6 - Docker Networking

Networking is where many beginners lose time, mostly because localhost changes meaning. Inside a container, localhost means that same container, not your laptop and not another container.

The localhost trap

Docker gives containers their own network namespace. That means a backend container that connects to localhost:5432 is looking for PostgreSQL inside itself. If PostgreSQL runs in another container, the backend should use the database container or service name on a shared network.

browser -> host:8080 -> container:80
api container -> db:5432
localhost inside api -> api itself

Bridge networks and ports

The default bridge network is enough for experiments, but user-defined bridge networks are better for projects. They provide DNS resolution by container name. You can say db:5432 instead of chasing container IP addresses.

Port mapping is a separate concept. -p 8080:80 means host port 8080 forwards traffic to container port 80. It is needed when the browser, host tools, or external clients must reach the container. Containers on the same network usually do not need host port mapping to talk to each other.

Two directions of traffic

There are two common traffic directions. Host-to-container traffic uses port mapping. Container-to-container traffic usually uses a Docker network and service names. Mixing those two models creates many confusing bugs.

If your browser opens localhost:8080, it talks to the host port. Docker forwards that traffic to a container port. If your API container connects to db:5432, it stays inside the Docker network and does not need a host port at all.

This distinction is why exposing a database port to the host is optional for container-to-container communication. You may expose it for a local GUI tool, but the API service can still use the internal service name.

Why custom networks help

User-defined bridge networks give cleaner DNS behavior than the default bridge. Containers can resolve each other by name, and you can isolate unrelated groups of containers.

For example, an application network can contain api, db, and redis. A separate experiment network can contain unrelated containers. This reduces accidental name collisions and makes diagrams easier to understand.

In Compose, this behavior is mostly automatic. Services in the same Compose project get a default network and can reach each other by service name.

Where network names make sense

Docker network names and service names make sense inside a Docker host. If two containers are on the same user-defined network, Docker can resolve names between them. Your browser outside Docker does not use that internal DNS.

This is why db:5432 can work from an API container, while your browser cannot open http://db:5432. The browser is on the host side, not inside the Docker network. For browser access, you need port mapping from host to container.

On a server, the same distinction applies. External users reach public host ports or a reverse proxy. Containers reach each other through Docker networks and service names.

Commands to run and inspect

Run these commands in a terminal on the machine where Docker is installed. For local learning, that is your laptop terminal. For a VPS, first connect to the server with SSH, then run the commands there. Do not paste commands blindly: run one command, inspect what changed, then run the next one.

docker network create app-net
docker run -d --name db --network app-net postgres:16
docker run --rm --network app-net alpine nslookup db
docker run -p 8080:8080 --network app-net app:dev

Reference table

Connection checklist

For every failed connection, write source, target, network, and port. Source is the process making the request. Target is the process receiving it. Network is the communication space between them. Port is where the target listens.

Most Docker networking bugs become obvious after this sentence: “from this container, I connect to that service name on that port.”

Checkpoint

Move on when you can explain why localhost inside a container is usually wrong for reaching another container, and when host port mapping is needed.

Practical networking exercise

Draw a failed connection as a sentence: “process A connects to host B on port C through network D.” If B is localhost, verify whose localhost it is. If C is a host port, verify whether the caller is the host or another container. This small sentence catches most mistakes before you start changing random Compose or Docker flags.