From 17b17003dade7fa570f56657306ccfdc167d76a8 Mon Sep 17 00:00:00 2001 From: Stefan Date: Tue, 27 Jan 2026 21:38:15 +0100 Subject: [PATCH 1/4] docs: add Matter bridge migration plan (matter-hub EOL) - Add migration guide: homeassistant/matter-migration.md - Document migration from t0bst4r/home-assistant-matter-hub to Luligu/matterbridge - Add EOL warning to README.md for Matter Hub service - Upstream project end-of-maintenance since January 2026 --- README.md | 2 +- homeassistant/matter-migration.md | 276 ++++++++++++++++++++++++++++++ 2 files changed, 277 insertions(+), 1 deletion(-) create mode 100644 homeassistant/matter-migration.md diff --git a/README.md b/README.md index 4248239..e61d862 100644 --- a/README.md +++ b/README.md @@ -21,7 +21,7 @@ A production-ready Docker Compose setup for self-hosted services on Raspberry Pi ### Home Automation - **Home Assistant** - Home automation hub - **Mosquitto** - MQTT broker for IoT devices -- **Matter Hub** - Matter protocol bridge +- **Matter Hub** - Matter protocol bridge ⚠️ *([Migration to Matterbridge planned](homeassistant/matter-migration.md) - upstream EOL)* - **Music Assistant** - Music aggregation service ### Media & Documents diff --git a/homeassistant/matter-migration.md b/homeassistant/matter-migration.md new file mode 100644 index 0000000..f723491 --- /dev/null +++ b/homeassistant/matter-migration.md @@ -0,0 +1,276 @@ +# Migration: home-assistant-matter-hub → Matterbridge + +> **Erstellt:** 2026-01-27 +> **Grund:** `t0bst4r/home-assistant-matter-hub` ist seit Januar 2026 End of Maintenance +> **Ziel:** `Luligu/matterbridge` mit `matterbridge-hass` Plugin + +## Übersicht + +| Aspekt | Alt (matter-hub) | Neu (matterbridge) | +|--------|------------------|-------------------| +| Image | `ghcr.io/t0bst4r/home-assistant-matter-hub:3.0.3` | `luligu/matterbridge:latest` | +| Matter Version | 1.3 | 1.4.2 | +| Konfiguration | `.env` Datei | Web-Frontend (Port 8283) | +| HA-Verbindung | Direkt (benötigt HA URL + Token) | WebSocket via Plugin | + +--- + +## Wichtig: Plugin-System verstehen + +> **Hinweis:** Das `matterbridge-hass` Plugin ist ein **Matterbridge Plugin**, KEIN Home Assistant Add-on! +> +> - Es wird im **Matterbridge Web-Frontend** installiert (Port 8283) +> - Es läuft **innerhalb** des Matterbridge Containers +> - Home Assistant bleibt **unverändert** – es stellt nur seine WebSocket API bereit +> - Funktioniert daher auch mit HA Docker (ohne Supervisor/Add-on Support) + +``` +┌─────────────────────────────────────────┐ +│ Matterbridge Container │ +│ ┌─────────────────────────────────┐ │ +│ │ matterbridge-hass Plugin │ │ ← Plugin läuft IN Matterbridge +│ │ (wird über Web-UI installiert)│ │ +│ └──────────────┬──────────────────┘ │ +└─────────────────┼───────────────────────┘ + │ WebSocket + ▼ +┌─────────────────────────────────────────┐ +│ Home Assistant Container │ ← Dein bestehender HA Docker +│ (unverändert, keine Plugins nötig) │ +└─────────────────────────────────────────┘ +``` + +--- + +## Voraussetzungen + +- [ ] Home Assistant Long-Lived Access Token erstellen +- [ ] Aktuelle Matter-Hub Konfiguration sichern (welche Entities sind exponiert?) +- [ ] Google Home App bereit zum Re-Pairing + +--- + +## Phase 1: Vorbereitung + +### 1.1 Home Assistant Token erstellen + +1. Home Assistant öffnen: `http://:8123` +2. Profil (unten links) → **Security** +3. **Long-Lived Access Tokens** → "Create Token" +4. Name: `matterbridge` +5. Token sicher speichern (wird nur einmal angezeigt!) + +### 1.2 Aktuelle Konfiguration dokumentieren + +```bash +# Matter-Hub Konfiguration anschauen +cat ~/docker/homeassistant/.env + +# Notiere dir: +# - Welche Domains/Entities sind exponiert? +# - Welche Filter sind aktiv? +``` + +### 1.3 Google Home: Altes Gerät entfernen + +1. Google Home App öffnen +2. Matter-Hub Bridge finden +3. Gerät entfernen (wichtig vor Migration!) + +--- + +## Phase 2: Matter-Hub stoppen + +```bash +cd ~/docker/homeassistant + +# Container stoppen (nicht löschen, falls Rollback nötig) +docker compose stop matter-hub + +# Optional: Logs sichern +docker logs matter-hub > matter-hub-backup.log 2>&1 +``` + +--- + +## Phase 3: Matterbridge installieren + +### 3.1 Docker Compose anpassen + +Ersetze in `docker-compose.yml` den `matter-hub` Service: + +```yaml + # ALT: matter-hub (auskommentiert für Rollback) + # matter-hub: + # image: ghcr.io/t0bst4r/home-assistant-matter-hub:3.0.3 + # container_name: matter-hub + # restart: unless-stopped + # network_mode: host + # env_file: + # - .env + # volumes: + # - $PWD/home-assistant-matter-hub:/data + + # NEU: Matterbridge + matterbridge: + image: luligu/matterbridge:latest + container_name: matterbridge + restart: unless-stopped + network_mode: host + volumes: + - ./matterbridge:/root/.matterbridge + - ./matterbridge-data:/root/Matterbridge + environment: + - TZ=Europe/Berlin +``` + +### 3.2 Verzeichnisse erstellen + +```bash +cd ~/docker/homeassistant +mkdir -p matterbridge matterbridge-data +``` + +### 3.3 Matterbridge starten + +```bash +docker compose up -d matterbridge + +# Logs prüfen +docker logs -f matterbridge +``` + +--- + +## Phase 4: Matterbridge konfigurieren + +### 4.1 Web-Frontend öffnen + +- URL: `http://:8283` +- Beim ersten Start wird ein QR-Code angezeigt (noch nicht scannen!) + +### 4.2 Home Assistant Plugin installieren + +1. Im Frontend: **Plugins** → Suche nach `matterbridge-hass` +2. **Install** klicken +3. Warten bis Installation abgeschlossen + +### 4.3 Plugin konfigurieren + +1. **Plugins** → `matterbridge-hass` → **Config** +2. Einstellungen: + +| Feld | Wert | +|------|------| +| **host** | `ws://:8123` | +| **token** | `` | +| **filterByArea** | Optional: Areas auswählen | +| **filterByLabel** | Optional: Labels auswählen | +| **whiteList** | Entities die exponiert werden sollen | +| **blackList** | Entities die NICHT exponiert werden sollen | + +3. **Save** und **Restart Plugin** + +### 4.4 Prüfen ob Entities geladen wurden + +- Frontend: **Devices** Tab +- Alle gewünschten Entities sollten sichtbar sein + +--- + +## Phase 5: Mit Google Home pairen + +### 5.1 QR-Code scannen + +1. Matterbridge Frontend: **Home** Tab +2. QR-Code wird angezeigt +3. Google Home App → **+** → **Gerät einrichten** → **Matter-fähiges Gerät** +4. QR-Code scannen + +### 5.2 Pairing abschließen + +- Google Home sollte die Bridge finden +- Alle Entities werden als Geräte angezeigt +- Räume zuweisen + +--- + +## Phase 6: Aufräumen + +### 6.1 Alten Matter-Hub Service entfernen + +Nach erfolgreicher Migration (ca. 1 Woche testen): + +```bash +cd ~/docker/homeassistant + +# Alte Daten löschen +rm -rf home-assistant-matter-hub + +# docker-compose.yml: Auskommentierten matter-hub Block entfernen +``` + +### 6.2 .env Datei bereinigen + +Entferne matter-hub spezifische Variablen aus `.env`: +- `HOME_ASSISTANT_URL` +- `HOME_ASSISTANT_ACCESS_TOKEN` +- `HAMH_*` Variablen + +--- + +## Rollback (falls nötig) + +Falls Probleme auftreten: + +```bash +cd ~/docker/homeassistant + +# Matterbridge stoppen +docker compose stop matterbridge + +# Matter-Hub wieder starten +docker compose start matter-hub + +# Google Home: Neu pairen mit alter Bridge +``` + +--- + +## Bekannte Einschränkungen + +### Apple Home (falls relevant) +- Robot Vacuum muss im "Server Mode" laufen +- RVC darf keine anderen Device-Types haben (Switches blacklisten) + +### Google Home +- Thermostat: Fahrenheit/Celsius Bug (Google-seitig) +- Workaround: Auf iPhone pairen, dann funktioniert Android + +--- + +## Nach der Migration + +### Dokumentation aktualisieren + +- [ ] `CLAUDE.md` aktualisieren (matter-hub → matterbridge) +- [ ] `docker-compose.yml` Kommentare anpassen +- [ ] Dependabot: Neues Image tracken lassen + +### Monitoring + +Matterbridge hat ein eigenes Frontend mit: +- Device Status +- Logs +- Plugin Management + +URL: `http://:8283` + +--- + +## Hilfreiche Links + +- [Matterbridge GitHub](https://github.com/Luligu/matterbridge) +- [matterbridge-hass Plugin](https://github.com/Luligu/matterbridge-hass) +- [Matterbridge Discord](https://discord.gg/QX58CDe6hd) +- [Docker README](https://github.com/Luligu/matterbridge/blob/main/README-DOCKER.md) From 1ac8e2511c986ea02c71a2691e75d885639dc39a Mon Sep 17 00:00:00 2001 From: Stefan Date: Wed, 28 Jan 2026 07:45:14 +0100 Subject: [PATCH 2/4] docs: Corrected path and adds correct volume def matter-hub --- README.md | 2 +- homeassistant/matter-migration.md | 8 ++++++-- 2 files changed, 7 insertions(+), 3 deletions(-) diff --git a/README.md b/README.md index e61d862..ef71f71 100644 --- a/README.md +++ b/README.md @@ -21,7 +21,7 @@ A production-ready Docker Compose setup for self-hosted services on Raspberry Pi ### Home Automation - **Home Assistant** - Home automation hub - **Mosquitto** - MQTT broker for IoT devices -- **Matter Hub** - Matter protocol bridge ⚠️ *([Migration to Matterbridge planned](homeassistant/matter-migration.md) - upstream EOL)* +- **Matter Hub** - Matter protocol bridge ⚠️ *([Migration to Matterbridge planned](./homeassistant/matter-migration.md) - upstream EOL)* - **Music Assistant** - Music aggregation service ### Media & Documents diff --git a/homeassistant/matter-migration.md b/homeassistant/matter-migration.md index f723491..bf4b55f 100644 --- a/homeassistant/matter-migration.md +++ b/homeassistant/matter-migration.md @@ -118,8 +118,10 @@ Ersetze in `docker-compose.yml` den `matter-hub` Service: restart: unless-stopped network_mode: host volumes: - - ./matterbridge:/root/.matterbridge - - ./matterbridge-data:/root/Matterbridge + volumes: + - ./Matterbridge:/root/Matterbridge # Mounts the Matterbridge plugin directory + - ./matterbridge-data:/root/.matterbridge # Mounts the Matterbridge storage directory + - ./mattercert:/root/.mattercert # Mounts the Matterbridge certificate directory environment: - TZ=Europe/Berlin ``` @@ -169,6 +171,8 @@ docker logs -f matterbridge | **whiteList** | Entities die exponiert werden sollen | | **blackList** | Entities die NICHT exponiert werden sollen | +> **Hinweis:** Wenn dein Home Assistant über HTTPS/SSL erreichbar ist (z. B. via Reverse Proxy oder öffentlicher URL), verwende im Feld **host** statt `ws://` unbedingt `wss://`, damit die WebSocket‑Verbindung funktioniert und verschlüsselt ist. + 3. **Save** und **Restart Plugin** ### 4.4 Prüfen ob Entities geladen wurden From c23297323f6a6d9e641931b4877544ba04a9ca8a Mon Sep 17 00:00:00 2001 From: Stefan Date: Tue, 3 Feb 2026 12:13:55 +0100 Subject: [PATCH 3/4] feat: Switched dependabot Updates to daily. --- .github/dependabot.yml | 18 ++++++------------ 1 file changed, 6 insertions(+), 12 deletions(-) diff --git a/.github/dependabot.yml b/.github/dependabot.yml index a029208..765357c 100644 --- a/.github/dependabot.yml +++ b/.github/dependabot.yml @@ -14,8 +14,7 @@ updates: - package-ecosystem: "docker-compose" directory: "/homeassistant" schedule: - interval: "weekly" - day: "sunday" + interval: "daily" time: "03:00" timezone: "Europe/Berlin" commit-message: @@ -25,8 +24,7 @@ updates: - package-ecosystem: "docker-compose" directory: "/paperless" schedule: - interval: "weekly" - day: "sunday" + interval: "daily" time: "03:00" timezone: "Europe/Berlin" commit-message: @@ -36,8 +34,7 @@ updates: - package-ecosystem: "docker-compose" directory: "/immich" schedule: - interval: "weekly" - day: "sunday" + interval: "daily" time: "03:00" timezone: "Europe/Berlin" commit-message: @@ -52,8 +49,7 @@ updates: - package-ecosystem: "docker-compose" directory: "/pihole" schedule: - interval: "weekly" - day: "sunday" + interval: "daily" time: "03:00" timezone: "Europe/Berlin" commit-message: @@ -63,8 +59,7 @@ updates: - package-ecosystem: "docker-compose" directory: "/freshrss" schedule: - interval: "weekly" - day: "sunday" + interval: "daily" time: "03:00" timezone: "Europe/Berlin" commit-message: @@ -74,8 +69,7 @@ updates: - package-ecosystem: "docker-compose" directory: "/teslamate" schedule: - interval: "weekly" - day: "sunday" + interval: "daily" time: "03:00" timezone: "Europe/Berlin" commit-message: From 7ae8efa2d336aa6bd5072e8cc35e5e2240cd4163 Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Tue, 3 Feb 2026 12:31:56 +0000 Subject: [PATCH 4/4] Initial plan