Docker / Images and container fundamentals / Lesson 6

Networks, DNS, listeners, and published ports

Trace traffic from a client through its network namespace to the intended listening process.

About 4 min readContent reviewed 2026-10-25

On this page

Lesson goals

Distinguish EXPOSE, application binding, and host publication.
Use service names and container ports for same-network communication.

Localhost belongs to the caller

Every normal container network namespace has its own loopback interface. localhost inside a worker means that worker, not its peer API and not automatically the host. Services on a suitable user-defined network can resolve each other through network-scoped names. Diagnose the caller's location first: a browser on the host and another container take different paths even when both requests conceptually target parcel-api.

Three port facts must agree

The application must listen on an address reachable through the container interface, typically 0.0.0.0:8080 in this fixture. EXPOSE 8080 records metadata only. A ports mapping publishes a host address and port to a container port. A mapping to container port 80 will not fix a process listening at 8080. Publishing on a broad host address can expose the service beyond the intended machine, so choose binding scope deliberately.

yaml A loopback-scoped teaching publication

services:
  api:
    image: parcel-api:lab
    ports:
      - "127.0.0.1:18080:8080"
    networks:
      - parcel-net
networks:
  parcel-net: {}

For the declared listener, a host client would use http://127.0.0.1:18080/. A peer on parcel-net would normally use http://api:8080/. The mapping does not make api:18080 the internal destination, and it does not promise access from another machine. Nothing is started by displaying this file.

Names follow network membership

Compose normally creates a project network and service-name discovery. Explicit networks can segment which services share connectivity. Do not hardcode a container IP discovered during one run; replacement can change that address while the service name remains the intended contract. A name resolving correctly proves only an address lookup, not that the target port is open, the application is ready, or the requested HTTP route exists.

bash Inspect publication and network membership separately

docker compose port api 8080
docker network inspect parcel-lab_parcel-net
docker container inspect parcel-api --format '{{json .NetworkSettings.Networks}}'

The project and container names are illustrative object identities, not guaranteed generated names; obtain actual names from the approved project. Port reports host publication, network inspect reports attached endpoints, and container inspection reports memberships. Record observations rather than inventing fixed IPs or assuming the client's current context owns these objects.

Classify the failure layer

A name-resolution error differs from connection refused, timeout, and HTTP 404. Refused commonly means the reached address has no accepting listener at that port; timeout can involve routing, filtering, or an unresponsive target. HTTP 404 proves an HTTP server answered but not that the correct application route was chosen. Check namespace, name, destination port, listener, publication, and route in that order before changing firewall rules.

Limit exposure to required consumers

Internal service communication usually needs a shared appropriate network rather than a published database port. Public entrypoints need a reviewed edge, transport security, authentication where required, and platform-specific firewall behavior. Docker network implementation differs between native Linux, rootless setups, Desktop VMs, and host networking. Document the target mode and verify it rather than assuming a laptop's successful request proves equivalent production exposure or isolation.

Common errors and fixes

Connection refused at localhost from a peer container.

Why it happens: The peer addressed its own loopback instead of the API service.
How to fix it: Use the API's network-scoped service name and actual container listener port.
Prevent it next time: Document request origins and internal versus host URLs separately.

The host mapping exists but the API is unreachable.

Why it happens: The application binds only container loopback or listens on another port.
How to fix it: Align application binding and target container port before altering exposure.
Prevent it next time: Treat listener configuration and publication as two independent checks.

A hardcoded container IP stops working after replacement.

Why it happens: Dynamic endpoint identity was mistaken for a stable service contract.
How to fix it: Use supported network-scoped service discovery and refresh connections appropriately.
Prevent it next time: Avoid persisting discovered container addresses in application configuration.

Check your understanding

1. Which destination should a same-network worker use for the example API?

Show worked solution

Use api:8080 because api is the Compose service name and 8080 is its container listener. 127.0.0.1:18080 is the host-facing publication for a host client. Confirm both services share the intended network; service-name spelling alone cannot bridge separate network membership.

2. Does an HTTP 404 justify opening another host port?