Home Assistant Docker macvlan Network Configuration

Running Home Assistant in host network mode in a Docker image has it’s issue when you have other services running as docker images on the same host. Here is how I set up my instance of Home Assistant to have access to my local network and to the other services running under Docker on the same host.

The Home Assistant documentation tells us to operate the docker image in host network mode. This is a sensible suggestion as many Home Assistant integrations need to access the local network to use ZeroConf, Universal Plug and Play (UPnP), or other methods to discover devices and services.

# home assistant in host network mode
version: '3'
services:
  homeassistant:
    container_name: homeassistant
    image: "ghcr.io/home-assistant/home-assistant:stable"
    volumes:
      - /PATH_TO_YOUR_CONFIG:/config
      - /etc/localtime:/etc/localtime:ro
    restart: unless-stopped
    privileged: true
    network_mode: host # <-- *** *** THIS *** ***

This works great as long as anyone you want to communicate with is on your local network. In my case, I also have Zigbee2MQTT and Mosquitto running as docker images on the same host. They do not run in host mode.

To put them all onto the same network, I created a new network in docker compose an put Zigbee2MQTT, Mosquitto, and Home Assistant onto that network.

# local network configuration
services:
  homeassistant:
    ...
    networks:
      - automation
    ...

  mqtt:
    ...
    networks:
      - automation
    ...

  zigbee2mqtt:
    ...
    networks:
      - automation
    ...

networks:
  automation: {}

This breaks many Home Assistant integrations as they now no longer can discover devices on the local network. To mitigate, I tried to bind necessary ports to the docker image. This quickly became futile as many integrations use a range of dynamic ports they promote to the devices. Also, the IP address they announce as call-back is that of the docker image.

The solution to the issue was to use a macvlan for my docker images and put them on my local network.

# macvlan network configuration
services:
  homeassistant:
    ...
    ports:
      - 8123:8123
    networks:
      lan:
        ipv4_address: 192.168.1.10
    ...

  mqtt:
    ...
    ports:
      - 1883:1883
      - 9001:9001
    networks:
      lan:
        ipv4_address: 192.168.1.15
    ...

  zigbee2mqtt:
    ...
    ports:
      - 8080:8080
    networks:
      lan:
        ipv4_address: 192.168.1.20
    ...

networks:
  lan:
    driver: macvlan
    driver_opts:
      parent: eth0
    ipam:
      config:
        - subnet: "192.168.1.0/24"
          ip_range: "192.168.1.8/29"
          gateway: "192.168.1.1"

Now the docker images get an IP address on the local network which they can announce to the devices as call-back address. All the docker images are also visible to each other, just as they were when they were in their own network group.

In addition, I can now add the docker images to my DHCP and DNS configurations. They are now known entities on the local network.