From ec8c3f5925bace86d57bf7c90849fa789e149940 Mon Sep 17 00:00:00 2001
From: Jeroen Schweitzer <jpmschweitzer@gmail.com>
Date: Thu, 26 Feb 2026 10:33:49 +0100
Subject: [PATCH] feat(home-assistant): switch to host networking and add
 Matter Server

- Switch HA from bridge to host networking for better device discovery
- Add python-matter-server container for Matter protocol support
- Both services share host network for mDNS/IPv6 multicast
- Update NPM forward hostname to use IP address
- Add Matter Server setup instructions

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
---
 stacks/home-assistant.yml | 55 ++++++++++++++++++++++++++++++++-------
 1 file changed, 45 insertions(+), 10 deletions(-)

diff --git a/stacks/home-assistant.yml b/stacks/home-assistant.yml
index 5ce364c..77703a7 100644
--- a/stacks/home-assistant.yml
+++ b/stacks/home-assistant.yml
@@ -1,7 +1,7 @@
 version: '3.8'
 
 # Home Assistant - Smart Home Automation Platform
-# Port: 8123 (Home Assistant default)
+# Ports: 8123 (Home Assistant), 5580 (Matter Server WebSocket)
 # GPU: No
 # Storage: SSD (config and database)
 
@@ -10,8 +10,7 @@ services:
     image: ghcr.io/home-assistant/home-assistant:stable
     container_name: home-assistant
     restart: unless-stopped
-    ports:
-      - "8123:8123"
+    network_mode: host
     volumes:
       # Config on SSD (includes database, automations, scripts)
       - /home/jpmschweitzer/docker-data/home-assistant/config:/config
@@ -19,8 +18,6 @@ services:
       - TZ=Europe/Amsterdam
     # Privileged mode for USB device access (Z-Wave, Zigbee dongles)
     privileged: true
-    networks:
-      - docker-dataplane
     healthcheck:
       test: ["CMD-SHELL", "curl -fSs http://localhost:8123/manifest.json || exit 1"]
       interval: 30s
@@ -32,10 +29,34 @@ services:
         limits:
           memory: 1G
 
-networks:
-  docker-dataplane:
-    external: true
-    name: docker-dataplane
+  matter-server:
+    image: ghcr.io/matter-js/python-matter-server:stable
+    container_name: matter-server
+    restart: unless-stopped
+    network_mode: host
+    security_opt:
+      - apparmor:unconfined
+    volumes:
+      # Matter fabric data on SSD (BACK UP before upgrades - contains device credentials)
+      - /home/jpmschweitzer/docker-data/matter-server/data:/data
+      # D-Bus socket for Bluetooth commissioning
+      - /run/dbus:/run/dbus:ro
+    environment:
+      - TZ=Europe/Amsterdam
+    healthcheck:
+      test: ["CMD-SHELL", "curl -fSs http://localhost:5580 || exit 1"]
+      interval: 30s
+      timeout: 10s
+      retries: 3
+      start_period: 60s
+    deploy:
+      resources:
+        limits:
+          memory: 512M
+
+# Note: Both services use network_mode: host for LAN device discovery (mDNS, SSDP, Matter)
+# Home Assistant reaches Matter Server at ws://localhost:5580/ws
+# Other containers should reach HA via http://192.168.86.149:8123
 
 # Setup Instructions:
 # 1. Create config directory:
@@ -64,7 +85,7 @@ networks:
 # NPM Configuration:
 # Domain: housekeeping.schweitz.net
 # Scheme: http
-# Forward Hostname/IP: home-assistant
+# Forward Hostname/IP: 192.168.86.149
 # Forward Port: 8123
 # Websockets Support: ENABLED (required for HA)
 # SSL: Let's Encrypt
@@ -77,3 +98,17 @@ networks:
 #     - 172.16.0.0/12
 #     - 192.168.0.0/16
 #     - 10.0.0.0/8
+#
+# Matter Server Setup:
+# 1. Create data directory:
+#    mkdir -p /home/jpmschweitzer/docker-data/matter-server/data
+#
+# 2. After deploying, connect from Home Assistant:
+#    Settings > Devices & Services > Add Integration > Matter
+#    Deselect "Install the official Matter Server app"
+#    Enter URL: ws://localhost:5580/ws
+#
+# 3. Commission devices via the HA Companion app (uses phone Bluetooth)
+#    or add --bluetooth-adapter 0 to the matter-server command for local BT
+#
+# Source: https://github.com/matter-js/python-matter-server