Setup Home Assistant matter-server as a container with macvlan

01_setup.md

Setup Home Assistant matter-server as a container with macvlan

Disclaimer

This guide glosses over a lot of network details and how ipv4 and ipv6 works. It works in my case but mistakes or other differences could lose you access to your server or cause other problems on your network. I advise to only use it if you have knowledge of linux and network. Use at your own risk

Only try this if have problems setting up your HA matter-server with the error CHIP Error 0x000000C1: Endpoint pool full with the official method (network_mode: host)

Guide

Define a local ipv6 subnet(Matter needs(!) ipv6 connectivity with mDNS support): e.g. fd4b:8c60:5ef3:d321::/64

Define IPv4 address for the matter-server(HA needs this address) and a second one for the bridge interface in your local network. e.g. if your subnet is 192.168.1.0/24

• Bridge interface: 192.168.1.99
• Matter server: 192.168.1.100

Choose a name for the bridge interface e.g. macvlan01. You also need the name of your servers network interface. e.g. enp5s0

Make sure to replace all addresses and names in the following commands with your corresponding values.

Create the bridge:
ip link add macvlan01 link enp5s0 type macvlan mode bridge

Set the ip address of the bridge:
ip addr add 192.168.1.99/32 dev macvlan01

Enable the bridge:
ip link set macvlan01 up

Add route for the ipv4 adress of the container:
ip route add 192.168.1.100/32 dev macvlan01

Add route for the ipv6 subnet:
ip route add fd4b:8c60:5ef3:d321::/64 dev macvlan01

If you have done the steps you can create the docker-compose.yml(see the example below) and start the server. In HA you add the matter integration with url ws://192.168.1.100:5580/ws

Related issues

• home-assistant-libs/python-matter-server#275
• project-chip/connectedhomeip#27007

02_example-docker-compose.yml

version: "3.6"
services:
  matter-server:
    image: ghcr.io/home-assistant-libs/python-matter-server:stable
    container_name: matter-server
    restart: unless-stopped
    #security_opt:
      # Needed for Bluetooth via dbus
      #- apparmor:unconfined
    volumes:
      - ./data:/data/
      #- /run/dbus:/run/dbus:ro
    networks:
      dockervlan:
        #the choosen ipv4 address (you have to set a static ip here, because docker does not use dhcp to allocate ip addresses, it chooses one from the subnet given below)
        ipv4_address: 192.168.1.100 
networks:
  dockervlan:
    driver: macvlan
    enable_ipv6: true
    driver_opts:
      parent: enp5s0
    ipam:
      config:
        - subnet: "192.168.1.0/24" # your ipv4 network 
          gateway: "192.168.1.1" # address of your ipv4 gateway/router
        - subnet: "fd4b:8c60:5ef3:d321::/64" #ipv6 subnet