Beitragsbild: Zigbee2MQTT auf Proxmox LXC installieren

Zigbee2MQTT auf Proxmox LXC installieren

von

Einleitung

Wer sein Smart Home lokal und ohne Cloud betreiben will, kommt an Zigbee2MQTT kaum vorbei. Statt proprietärer Gateways bekommst du damit die volle Kontrolle über deine Zigbee-Geräte – komplett über MQTT integrierbar in Systeme wie ioBroker oder Home Assistant.

In diesem Beitrag zeige ich dir Schritt für Schritt, wie du zigbee2mqtt unter Proxmox LXC installieren kannst – bewusst ohne Community Script, dafür sauber und nachvollziehbar nach offizieller Doku.

Referenzen: Zigbee2MQTT Installation (Linux), Proxmox VE, MQTT.

Schnellnavigation

Voraussetzungen

  • Proxmox VE
  • Debian LXC Container (empfohlen)
  • Zigbee USB Stick (z. B. CC2652 / EFR32)
  • MQTT Broker (z. B. Eclipse Mosquitto)

Wichtig: Zigbee2MQTT spricht nicht „direkt“ mit ioBroker oder Home Assistant, sondern veröffentlicht alles über MQTT. Wenn du MQTT einmal verstanden hast, wird Zigbee2MQTT plötzlich sehr logisch. Eine gute Einstiegserklärung ist die offizielle Seite mqtt.org.

LXC Container erstellen

Empfohlene Einstellungen für Zigbee2MQTT (praxisnah und ausreichend):

  • Template: Debian
  • RAM: mindestens 512 MB (besser 1 GB)
  • CPU: 1–2 Kerne
  • Netzwerk: DHCP oder statisch

Warum LXC? Es ist deutlich schlanker als eine VM und für Dienste wie Zigbee2MQTT völlig ausreichend. Außerdem lassen sich Container sehr gut sichern, klonen und bei Bedarf neu aufsetzen.

USB-Stick in den Container durchreichen

Zuerst lassen wir uns stabile Gerätepfade anzeigen. Das ist besser als blind mit /dev/ttyUSB0 zu arbeiten (das kann sich nach Reboots ändern):

ls -l /dev/serial/by-id/

Was macht der Befehl? Er listet symbolische Links auf, die eindeutig auf deine seriellen Geräte zeigen. Perfekt, um Zigbee- und Z-Wave-Sticks auseinanderzuhalten.

Beispielausgabe (zwei Zigbee-Sticks und ein Z-Wave-Stick):

lrwxrwxrwx 1 root root 13 Mar 20 20:20 usb-ITead_Sonoff_Zigbee_3.0_USB_Dongle_Plus_0019...-if00-port0 -> ../../ttyUSB2
lrwxrwxrwx 1 root root 13 Mar  5 13:55 usb-ITead_Sonoff_Zigbee_3.0_USB_Dongle_Plus_9286...-if00-port0 -> ../../ttyUSB0
lrwxrwxrwx 1 root root 13 Mar 19 21:11 usb-SONOFF_SONOFF_ZWave_Dongle-PZG23_b841...-if00-port0 -> ../../ttyUSB1

Privileged vs Unprivileged

Ein privileged LXC hat es oft leichter beim Hardwarezugriff – aber das ist weniger sauber isoliert. Ein unprivileged LXC ist die bessere Standardwahl, kann aber je nach Setup etwas mehr Arbeit beim Durchreichen bedeuten.

Stick durchreichen per Proxmox GUI

Die bequemste Lösung: in Proxmox den Stick in der GUI auswählen und an den Container durchreichen. Das ist meist auch am wenigsten fehleranfällig. Dies geht einfach unter „Resources“.

Proxmox GUI: Dialog „Add: Device“ zum Durchreichen eines USB-Geräts in einen LXC-Container

Stick durchreichen per CLI

Alternativ (nerdig) per CLI auf dem Proxmox Host:

pct set <CTID> --dev0 path=/dev/ttyUSB2

Erklärung:

  • pct set: ändert die Konfiguration eines Containers
  • <CTID>: die Container-ID (z. B. 105)
  • --dev0: erstes durchgereichtes Gerät
  • path=/dev/ttyUSB2: Gerät, das durchgereicht wird

Zigbee2MQTT manuell installieren

Jetzt im LXC Container arbeiten. Ich teile die Installation bewusst in mehrere Blöcke, damit klar ist, was du da gerade tust.

1) System aktualisieren

apt update
apt upgrade -y

apt update aktualisiert die Paketlisten. apt upgrade -y installiert Updates automatisch (ohne Rückfragen).

2) Tools und Abhängigkeiten installieren

apt install -y curl git make g++ gcc libsystemd-dev

curl lädt Skripte/Dateien, git holt das Repository, make/gcc/g++ werden für native Abhängigkeiten benötigt. Details zu APT findest du in der offiziellen Debian-Doku: Debian Reference (APT).

3) Node.js LTS installieren

Zigbee2MQTT läuft auf Node.js. Wir installieren die LTS-Version (Langzeit-Support). Hintergrund zu LTS: Node.js Releases.

curl -fsSL https://deb.nodesource.com/setup_lts.x | bash -
apt install -y nodejs

Der erste Befehl bindet das NodeSource-Repo ein (für aktuelle LTS-Pakete), der zweite installiert Node.js.

4) pnpm aktivieren

Die Zigbee2MQTT-Doku nutzt mittlerweile pnpm. Das kommt über corepack (gehört zu Node.js). Referenz: Node.js Corepack.

corepack enable
corepack prepare pnpm@latest --activate

Damit steht pnpm als Paketmanager bereit.

5) Zigbee2MQTT herunterladen

Wir klonen das offizielle Repository. Projektseite: Koenkk/zigbee2mqtt.

mkdir -p /opt/zigbee2mqtt
git clone --depth 1 https://github.com/Koenkk/zigbee2mqtt.git /opt/zigbee2mqtt

--depth 1 lädt nur den aktuellen Stand (spart Zeit und Platz).

6) Abhängigkeiten installieren und Teststart

cd /opt/zigbee2mqtt
pnpm install --frozen-lockfile

pnpm install --frozen-lockfile installiert exakt die Versionen aus dem Lockfile – reproduzierbar und stabil.

pnpm start

Das startet Zigbee2MQTT im Vordergrund. Ideal zum ersten Test, bevor du einen Service draus machst.

Konfiguration verstehen

Die zentrale Datei ist:

nano /opt/zigbee2mqtt/data/configuration.yaml

Minimalbeispiel (bewusst klein, aber funktional):

homeassistant:
  enabled: false

mqtt:
  base_topic: zigbee2mqtt
  server: mqtt://localhost:1883

serial:
  port: /dev/ttyUSB0

frontend:
  enabled: true
  port: 8080

Wichtig: Bei mqtt.server muss das Schema stimmen. Also z. B. mqtt://192.168.0.86:1883 – ohne mqtt:// wird Zigbee2MQTT gerne mal „kreativ“ und verbindet nicht. (Der Klassiker.)

Noch robuster als /dev/ttyUSB0 ist ein Pfad aus /dev/serial/by-id. Beispiel:

serial:
  port: /dev/serial/by-id/usb-ITead_Sonoff_Zigbee_3.0_USB_Dongle_Plus_0019...-if00-port0

Die komplette Konfig-Referenz findest du in der offiziellen Doku: Zigbee2MQTT Konfiguration.

Autostart als Service einrichten

Jetzt machen wir aus dem Teststart einen systemd-Service, damit Zigbee2MQTT automatisch beim Boot startet. Hintergrund zu systemd: freedesktop.org (systemd).

Optional: eigenen User anlegen (sauberer)

Statt als root laufen zu lassen, ist ein eigener Service-User die bessere Praxis:

adduser --system --group --home /opt/zigbee2mqtt zigbee2mqtt
chown -R zigbee2mqtt:zigbee2mqtt /opt/zigbee2mqtt

Das legt einen Systemuser an und setzt die passenden Rechte auf das Installationsverzeichnis.

Service-Datei erstellen

Zuerst prüfen, wo pnpm liegt (damit ExecStart garantiert stimmt):

which pnpm

Jetzt Service-Datei anlegen:

nano /etc/systemd/system/zigbee2mqtt.service

Inhalt (ersetze /usr/bin/pnpm ggf. durch das Ergebnis von which pnpm):

[Unit] Description=Zigbee2MQTT After=network.target [Service] WorkingDirectory=/opt/zigbee2mqtt ExecStart=/usr/bin/pnpm start Restart=always RestartSec=10 # Variante A (empfohlen): eigener User User=zigbee2mqtt Group=zigbee2mqtt # Variante B (wenn du es unbedingt willst): root # User=root [Install] WantedBy=multi-user.target

Service aktivieren und starten

systemctl daemon-reload
systemctl enable zigbee2mqtt
systemctl start zigbee2mqtt

daemon-reload lädt die neue Service-Datei ein, enable aktiviert Autostart, start startet sofort.

Status/Logs prüfen:

systemctl status zigbee2mqtt
journalctl -u zigbee2mqtt -n 200 --no-pager

Webinterface aufrufen

Wenn alles läuft, erreichst du Zigbee2MQTT unter:

http://<IP>:8080
  • Geräte anlernen
  • Logs einsehen
  • Konfiguration testen

Vergleich: Manuelle Installation vs Community Script

Community Script

Vorteile:

  • extrem schnell
  • wenig Setup-Aufwand
  • gut für „soll einfach laufen“

Nachteile:

  • weniger Kontrolle
  • schwerer zu debuggen, wenn’s klemmt
  • Updates können je nach Script/Struktur nerven

Manuell

Vorteile:

  • volle Kontrolle
  • besseres Verständnis
  • nah an der offiziellen Doku

Nachteile:

  • mehr Aufwand
  • Fehler durch Tippfehler möglich

Bonus: Typische Fehler

„not a git repository“

Passiert, wenn im Zielordner kein echtes Git-Repo liegt (z. B. Ordner manuell erstellt, aber nicht geklont). Lösung: sauber neu klonen statt mit halben Update-Skripten zu kämpfen.

Webinterface nicht erreichbar

Meist läuft der Service nicht oder der Port stimmt nicht. Prüfe systemctl status und die Logs via journalctl.

MQTT verbindet nicht

Klassiker: im mqtt.server fehlt das mqtt:// vor der IP/Hostname – oder Broker/Port sind falsch. Das sieht man sehr schnell im Log.

Fazit

Wenn du einfach nur „es soll laufen“ willst, reicht ein Community Script oft aus. Wenn du aber langfristig ein stabiles Setup willst, das du verstehst und sauber debuggen kannst, ist die manuelle Installation klar im Vorteil – gerade in Proxmox-Umgebungen mit mehreren Diensten.

Weiterlesen auf prokrastinerd.de

Wenn du gerade sowieso in Proxmox versackst: Als Einstieg lohnt sich meine Proxmox Anleitung. Für typische Stolperfallen gibt’s außerdem Proxmox und der OOM-Killer, Proxmox Backup failed – was tun? und meinen Erfahrungsbericht Proxmox Backup Server im Homelab. Wenn du eher am Bastel-/Homelab-Teil hängst: Proxmox NAS mit LXC einrichten, Proxmox VMs und Container auf ein ZFS Mirror Storage verschieben sowie Proxmox auf IPv6 umstellen. Und ja: Teamspeak Server unter Proxmox installieren existiert auch noch – Nostalgie darf sein.

Schreibe einen Kommentar