Networks

Each container gets its own network namespace and an address on a Docker network. A network here is a virtual switch on the host that containers attach to, so containers on the same one can talk to each other directly.

Create your own network and you get something extra: name resolution. Docker runs a resolver for user-defined networks that maps container names to their addresses. The API container asks for db, and Docker answers with the address of the container named db.

That is why a connection string inside a container reads Host=db rather than a numeric address. Addresses change every time a container is recreated. The name does not.

# A network of your own — this is what brings name resolution
docker network create employees-net

# The database. No published port: only the API needs to reach it
docker run -d --name db --network employees-net \
  -v employees-db-data:/var/lib/postgresql/data \
  -e POSTGRES_PASSWORD=local-dev-placeholder \
  -e POSTGRES_DB=employees \
  postgres:16

# The API, on the same network, addressing the database by container name
docker run -d --name employees-api --network employees-net -p 8080:8080 \
  -e "ConnectionStrings__Employees=Host=db;Port=5432;Database=employees;Username=postgres;Password=local-dev-placeholder" \
  anvi/employees-api:1.4.0

# Prove the name resolves from inside the API container
docker exec employees-api getent hosts db

# Who is attached, and with which addresses
docker network inspect employees-net

• docker network create makes a user-defined bridge network. The default bridge that containers join automatically does not resolve container names, which is the single most useful reason to create your own.
• The database has no -p. It does not need one — traffic between containers on a shared network never goes through the host's ports. Publishing 5432 would only be for tools running on your machine.
• Host=db in the connection string is the container name. Docker resolves it on this network, so the API does not need to know or care what address the database ended up with.
• getent hosts db prints the resolved address from inside the container. It separates two questions that otherwise get confused: is the name resolving, and is the database accepting connections?
• docker network inspect lists the attached containers. If a container is missing from that list, it was started without --network and is on the default bridge instead.

A container can be attached to more than one network, and that is how you keep services apart deliberately. Put the frontend and the API on one network, the API and the database on another, and the frontend has no network path to the database at all. It is a boundary the configuration enforces rather than one everybody agrees to respect.

Two published ports on the host and two containers on a shared network are separate paths to the same service. Understanding which path a request is taking answers most connectivity questions before you start changing anything.