↓Skip to main content
MINOSAUR

Home Assistant Docker 컨테이너에 Matter 적용하기

·700 words·4 mins
미뇽
Author
미뇽
안녕하세요! 기술로 세상을 이롭게 만들고 싶은 개발자 미뇽입니다.
Table of Contents

Matter는 mDNS나 Bluetooth 같은 저수준 네트워크 프로토콜을 사용해 기기를 발견하고 통신해야 하므로, Home Assistant 컨테이너는 Docker의 가상 네트워크가 아닌 호스트(서버)의 네트워크를 직접 사용해야 합니다.

이 가이드에서는 기존에 Traefik 리버스 프록시와 연동하여 사용하던 Home Assistant Docker 설정을 network_mode: host 로 변경하고, 이로 인해 발생하는 Traefik 연동 문제를 해결한 뒤, 최종적으로 Matter 서버를 설치하여 연동하는 전체 과정을 단계별로 안내합니다.

Home Assistant 네트워크 모드 변경 (host 모드 전환)
#

가장 먼저, Home Assistant가 Matter 기기들을 올바르게 인식할 수 있도록 docker-compose.yml 파일의 네트워크 설정을 변경합니다.

homeassistant/docker-compose.yml 파일을 열고 아래와 같이 수정하십시오.

# homeassistant/docker-compose.yml

version: '3'
services:
  homeassistant:
    container_name: homeassistant
    image: "ghcr.io/home-assistant/home-assistant:stable"
    devices:
      - /dev/hci0:/dev/hci0 # Bluetooth 장치
    volumes:
      - /home/kimminho/Services/homeassistant/config:/config
      - /etc/localtime:/etc/localtime:ro
      - /run/dbus:/run/dbus:ro
      - /var/run/dbus:/var/run/dbus:ro
    environment:
      - PUID=1000
      - PGID=1000
      - TZ=Asia/Seoul
    restart: unless-stopped
    privileged: true
    # ------------------ (수정된 부분) ------------------
    network_mode: host # 👈 [추가] 호스트 네트워크를 직접 사용하도록 설정
    # networks:        # 👈 [주석 또는 삭제] network_mode: host와 함께 사용할 수 없음
    #   - traefik-proxy
    # labels:          # 👈 [주석 또는 삭제] Traefik의 Docker 자동 감지 기능이 더 이상 작동하지 않음
    #   - "traefik.enable=true"
    #   - "traefik.http.routers.homeassistant.rule=Host(`ha.duckdns.org`)"
    #   - "traefik.http.routers.homeassistant.entrypoints=websecure"
    #   - "traefik.http.routers.homeassistant.tls=true"
    #   - "traefik.http.routers.homeassistant.tls.certresolver=letsencrypt"
    #   - "traefik.http.services.homeassistant.loadbalancer.server.port=8123"

# networks:            # 👈 [주석 또는 삭제] 서비스에서 사용하지 않으므로 전체 제거
#   traefik-proxy:
#     external: true

핵심 변경 사항은 network_mode: host를 추가하고, 기존의 networks와 labels 설정을 모두 제거(또는 주석 처리)하는 것입니다.

Traefik 연동 문제 해결 (수동 라우팅 설정)
#

network_mode: host를 사용하면 Home Assistant 컨테이너는 더 이상 Docker의 가상 네트워크에 속하지 않으므로, Traefik이 레이블을 통해 자동으로 감지할 수 없습니다.

이 문제를 해결하려면, Traefik에게 Home Assistant의 위치를 파일 기반의 동적 설정(Dynamic Configuration) 을 통해 수동으로 알려줘야 합니다.

Traefik 동적 설정 파일 생성
#

Traefik의 docker-compose.yml 파일이 있는 경로에 dynamic과 같은 폴더를 만들고, 그 안에 아래 내용으로 homeassistant.yml 파일을 생성합니다.

# traefik/dynamic/homeassistant.yml

http:
  routers:
    homeassistant:
      rule: "Host(`ha.duckdns.org`)"
      entryPoints:
        - websecure
      service: homeassistant
      tls:
        certResolver: letsencrypt

  services:
    homeassistant:
      loadBalancer:
        servers:
          # Home Assistant가 호스트 네트워크의 8123 포트를 사용하므로,
          # 서버의 실제 내부 IP와 포트를 직접 지정해줍니다.
          - url: "http://192.168.0.10:8123" # 👈 서버의 실제 내부 IP 주소로 변경

※ 주의: url 항목에는 Home Assistant가 실행 중인 서버의 내부 IP 주소를 정확히 입력해야 합니다.

Traefik 설정 파일 수정 (traefik.yml 및 docker-compose.yml)
#

Traefik이 파일 기반의 동적 설정을 읽도록 traefik.yml 파일에 providers 설정을 추가합니다.

# traefik/traefik.yml

# ... (기존 api, entrypoints, certificatesResolvers 등 설정) ...

providers:
  # Docker 레이블 감지 (기존 설정 유지)
  docker:
	exposedByDefault: false
	# ...

  # [추가] 파일 시스템 감지
  file:
	# 감시할 디렉토리를 컨테이너 내부 경로로 지정
	directory: /etc/traefik/dynamic
	# 변경 사항을 자동으로 감지할지 여부
	watch: true

traefik/docker-compose.yml 파일을 수정하여 2.1에서 생성한 dynamic 폴더를 컨테이너에 볼륨으로 연결합니다.

# traefik/docker-compose.yml

services:
  traefik:
	# ... (기존 설정) ...
	volumes:
	  - /var/run/docker.sock:/var/run/docker.sock:ro
	  - ./traefik.yml:/etc/traefik/traefik.yml:ro
	  - ./acme.json:/etc/traefik/acme.json
	  - ./dynamic:/etc/traefik/dynamic # 👈 [추가] dynamic 폴더를 컨테이너에 연결

Matter 서버 설치
#

이제 Home Assistant와 함께 동작할 공식 python-matter-server를 설치합니다. homeassistant/docker-compose.yml 파일을 다시 열고 services 항목에 matter-server를 추가합니다.

# homeassistant/docker-compose.yml

version: '3'
services:
  homeassistant:
    # ... (1단계에서 수정한 Home Assistant 설정) ...

  matter-server:
    # 공식 python-matter-server 이미지
    image: ghcr.io/home-assistant-libs/python-matter-server:8
    container_name: matter-server
    restart: unless-stopped
    # ------------------ (핵심 설정) ------------------
    # 호스트 네트워크를 직접 사용하여 mDNS, Bluetooth 등 사용
    network_mode: host
    volumes:
      # Matter 데이터(Fabric, 기기 정보)를 영속적으로 저장
      - ./matter-data:/data
      # 호스트의 DBus 시스템에 접근 허용 (Bluetooth 등에 필요)
      - /run/dbus:/run/dbus:ro
    # 저수준 네트워크 접근을 위한 권한
    privileged: true

matter-server가 사용할 데이터 폴더를 생성합니다.

# homeassistant 폴더 내에서 실행
mkdir matter-data

방화벽 설정 및 서비스 재시작
#

Matter 서버가 사용하는 5580번 포트를 방화벽에서 허용해 줍니다.

sudo ufw allow 5580
sudo ufw reload # 또는 disable 후 enable

지금까지 수정한 모든 설정을 적용하기 위해, traefik과 homeassistant 각 디렉토리에서 아래 명령어를 실행하여 컨테이너를 다시 시작합니다.

docker-compose up -d --force-recreate

설정이 완료되면 IP주소:5580에서 서버 동작을 확인할 수 있습니다.

Home Assistant에 Matter 연동
#

모든 서비스가 정상적으로 실행되면, Home Assistant 웹 UI에 접속합니다.

  1. [설정] > **[기기 및 서비스]**로 이동합니다.

  2. 아래와 같이 발견된 구성요소에 Matter가 자동으로 표시됩니다.

    |442x302

  3. [구성하기] 버튼을 누르면 잠시 후 Matter 서버가 Home Assistant에 성공적으로 추가됩니다.

마무리하며
#

축하합니다! 이제 여러분의 Home Assistant는 Matter 기기를 추가하고 제어할 모든 준비를 마쳤습니다. 비록 네트워크 모드 변경으로 인해 Traefik 설정을 수동으로 변경해야 하는 과정이 있었지만, 이를 통해 Matter의 강력한 기능을 Docker 환경에서도 안정적으로 활용할 수 있는 기반을 마련했습니다.

참조