Docker Networking: Hostname vs Container Name, Port Mapping, and Bridge Networks

Hostname vs container name vs network alias

Three distinct identities in Docker networking:

| Identity | What it is | Set by | |---|---|---| | Container name | Docker's name for the container | --name flag or container_name: in Compose | | Hostname | What the container sees as its own hostname | --hostname flag, defaults to container ID | | Network alias | DNS name other containers use to reach this one | --network-alias or Compose aliases: |

In a Docker network, by default the container name is also registered as a DNS name. Other containers on the same network resolve it. The hostname only affects what the container sees internally (e.g., hostname command, HOSTNAME env var).

# docker-compose.yml
services:
  api:
    image: my-api
    container_name: api-container    # Docker's name
    hostname: api-service            # what the container thinks it's called
    networks:
      app-net:
        aliases:
          - api                      # other containers use "api" to reach this service

  web:
    image: my-web
    environment:
      API_URL: http://api:8080       # uses the network alias, not container name
    networks:
      - app-net

networks:
  app-net:
    driver: bridge

Port mapping: static vs dynamic

Port mapping exposes a container port to the host. The host port can be:

services:
  app:
    image: my-app
    ports:
      - "8080:80"    # static: host port 8080 → container port 80
      - "0:80"       # dynamic: OS assigns available host port → container port 80
      - "80"         # equivalent to "0:80" — shorthand for dynamic mapping

Static port mapping (8080:80): only one container can bind to host port 8080. Running two instances of the same service on the same host requires different host ports.

Dynamic port mapping (0:80): the OS assigns an available ephemeral port. Multiple containers can run the same service on the same host. Find the assigned port:

docker inspect container-id \
  --format '{{range $p, $conf := .NetworkSettings.Ports}}{{$p}} -> {{(index $conf 0).HostPort}}{{"\n"}}{{end}}'

# or
docker port container-id 80

Dynamic port mapping in ECS bridge mode

ECS requires dynamic port mapping when running multiple tasks of the same service on a single EC2 instance. If you use a static host port (e.g., 8080:80), only one task can run per instance because host port 8080 is already taken.

resource "aws_ecs_task_definition" "app" {
  family       = "app"
  network_mode = "bridge"

  container_definitions = jsonencode([{
    name  = "app"
    image = "my-app:latest"
    portMappings = [{
      containerPort = 80
      hostPort      = 0       # dynamic — ECS assigns an available host port
      protocol      = "tcp"
    }]
  }])
}

With hostPort = 0, ECS assigns a random host port (typically in the 32768-65535 range) when the task starts. The ALB target group uses instance IP + dynamic port — the ECS service registration handles updating the target group automatically.

# Create a user-defined network
docker network create app-network

# Containers on the same network find each other by name
docker run -d --name postgres --network app-network postgres:16
docker run -d --name api --network app-network \
  -e DB_HOST=postgres \   # resolves by container name
  my-api:latest

services:
  web:
    networks: [frontend]
  api:
    networks: [frontend, backend]
  db:
    networks: [backend]

networks:
  frontend:
  backend: