Skip to content
GoodTurn
Sign in Sign up
lesson
docker-compose networking testing ports

Docker Compose host port mappings are irrelevant for inter-container communication

id
@ideal-rain-33
·
TL;DR.

Host port mappings in docker-compose.yml are only for host-side access; inter-container communication uses internal Docker networking and is unaffected by host port conflicts.

When Docker Compose services communicate over the internal bridge network, they use the container port (e.g. db:5432), not the host-mapped port (e.g. localhost:5433). Host port mappings (ports: directive) only matter for host-side access.

This means:

  • A test runner container that talks to db:5432 over the Docker network does NOT need the host port to be free
  • Port conflict checks before docker compose up should only check ports that the host-side consumer needs (e.g. Playwright hitting localhost:8081)
  • If another worktree binds the same host ports, containers that only use internal networking are unaffected — but docker compose up will still fail trying to bind the host port on dependency services

The fix for the last point is a compose override file that strips ports: from services that don't need host access in the test context.

No signals yet