Docker Networking Explained: Bridge, Host, and Macvlan

Why Networking Matters

Docker networking is one of the most misunderstood aspects of containerization. Choose the wrong network mode, and your services might not communicate. Choose the right one, and everything just works.

Let's demystify the three main Docker network modes and help you choose the right one for each use case.

Bridge Network (Default)

Bridge is Docker's default network mode. It creates an isolated network for your containers, with Docker acting as a virtual router between containers and the host.

# Default bridge network
services:
  web:
    image: nginx:1.25
    ports:
      - "80:80"  # Map host port to container port

  api:
    image: myapi:1.0
    # No ports - only accessible within Docker network

  db:
    image: postgres:15
    # Internal only - web and api can reach it by hostname "db"

How It Works:

• Containers get private IP addresses (172.17.0.x range)
• Containers can reach each other by service name
• Port mapping required for external access
• NAT handles traffic between container and host networks

Best For:

• Most homelab applications
• Multi-container applications
• When you need network isolation
• Development environments

Host Network

Host mode removes network isolation entirely. The container shares the host's network stack directly, meaning no port mapping needed - the container uses host ports directly.

services:
  pihole:
    image: pihole/pihole:latest
    network_mode: host
    # No ports section needed - uses host ports directly
    environment:
      WEBPASSWORD: 'admin'

How It Works:

• Container uses host's IP address
• No NAT or port mapping overhead
• Container sees all host network interfaces
• Best network performance possible

Best For:

• Network-intensive applications
• Services that need to bind many ports (Pi-hole)
• When you need host network discovery
• Performance-critical applications

Warning: Host mode reduces security isolation. Only use when necessary.

Macvlan Network

Macvlan gives containers their own MAC address, making them appear as physical devices on your network. They get IP addresses from your router's DHCP, just like any other device.

# First, create the macvlan network
docker network create -d macvlan \
  --subnet=192.168.1.0/24 \
  --gateway=192.168.1.1 \
  -o parent=eth0 \
  my_macvlan

# Then use it in compose
services:
  homeassistant:
    image: homeassistant/home-assistant:latest
    networks:
      my_macvlan:
        ipv4_address: 192.168.1.50
    volumes:
      - ./config:/config

networks:
  my_macvlan:
    external: true

How It Works:

• Container gets its own MAC address
• Appears as a separate device on the network
• Gets IP from your network's DHCP or static assignment
• Other devices can reach it directly

Best For:

• Home Assistant (needs network discovery)
• Services requiring multicast/broadcast
• When you need a "real" IP on your LAN
• IoT integrations

Custom Bridge Networks

Docker Compose automatically creates a custom bridge network for your services. You can also create your own for better organization:

services:
  frontend:
    image: nginx:1.25
    networks:
      - frontend

  backend:
    image: myapi:1.0
    networks:
      - frontend
      - backend

  database:
    image: postgres:15
    networks:
      - backend

networks:
  frontend:
  backend:

This creates network isolation - the frontend can't directly reach the database, only the backend can.

Network Mode Comparison

| Feature          | Bridge      | Host        | Macvlan     |
|------------------|-------------|-------------|-------------|
| Isolation        | Good        | None        | Good        |
| Port Mapping     | Required    | Not needed  | Not needed  |
| Performance      | Good        | Best        | Good        |
| Own IP Address   | Docker IP   | Host IP     | LAN IP      |
| Use Case         | Most apps   | Network apps| IoT, HA     |

Troubleshooting Tips

• Use docker network inspect to see which containers are connected
• Check DNS resolution with docker exec container ping other-container
• Macvlan containers can't reach the host by default - create a macvlan interface on the host if needed
• Use docker network prune to clean up unused networks

Choose Wisely

For most homelab services, the default bridge network works perfectly. Use host mode for network-intensive services like Pi-hole. Reserve macvlan for services that truly need to appear as separate devices on your network, like Home Assistant.