Node-RED Docker: Einrichtung für MQTT-Projekte

Node-RED in Docker zu betreiben, ergibt eine reproduzierbare Installation, die sich leicht aktualisieren, sichern und zwischen Maschinen umziehen lässt. In diesem Tutorial starten Sie das offizielle Node-RED-Docker-Image, halten Ihre Flows auf einem persistenten Volume, verwalten alles mit Docker Compose, ergänzen zusätzliche Nodes, übergeben Secrets sicher und verbinden den Container per TLS mit einem MQTT-Broker.

Warum Node-RED in Docker betreiben

Node-RED direkt mit npm zu installieren funktioniert gut, und unser Leitfaden Node-RED installieren beschreibt diesen Weg. Container bringen einige Vorteile, die zählen, sobald ein Flow echte Arbeit leistet:

Festgelegte Versionen. Sie wählen über den Image-Tag die exakte Node-RED- und Node.js-Version, ein Upgrade ist also eine bewusste Änderung.
Saubere Trennung. Alles, was Node-RED schreibt, liegt in einem Verzeichnis, /data, das Sie als Volume einbinden. Sichern Sie diesen einen Ordner, und Sie haben alles.
Einfaches Rollback. Bricht ein Upgrade einen Community-Node, wechseln Sie zurück zum vorherigen Tag.
Überall dieselbe Einrichtung. Eine Compose-Datei läuft identisch auf einem Laptop, einem Raspberry Pi mit 64-Bit-Betriebssystem oder einer Cloud-VM.

Das offizielle Image ist nodered/node-red auf Docker Hub. Tags wie latest, eine bestimmte Version wie 4.0.9 oder Varianten mit einer bestimmten Node.js-Version lassen Sie wählen, wie streng Sie festlegen. In Produktion legen Sie einen Versions-Tag fest statt latest.

Schnellstart mit docker run

Stellen Sie sicher, dass Docker installiert ist, und führen Sie aus:

docker volume create node_red_data

docker run -d \
  --name nodered \
  --restart unless-stopped \
  -p 1880:1880 \
  -e TZ=Europe/Istanbul \
  -v node_red_data:/data \
  nodered/node-red:latest

Öffnen Sie http://localhost:1880, und Sie haben einen funktionierenden Editor. Das wichtige Flag ist -v node_red_data:/data. Ohne es liegen Flows, installierte Nodes und Zugangsdaten in der beschreibbaren Schicht des Containers und verschwinden, wenn Sie den Container entfernen oder neu erstellen. TZ setzt die Zeitzone, damit Zeitstempel und Inject-Zeitpläne zu Ihrer Ortszeit passen; in Deutschland, Österreich und der Schweiz zum Beispiel Europe/Berlin, Europe/Vienna oder Europe/Zurich.

Nützliche Befehle für den Alltag:

docker logs -f nodered          # Node-RED-Log verfolgen
docker exec -it nodered bash    # Shell im Container
docker restart nodered          # nach Bearbeiten von settings.js neu starten

Die Richtlinie --restart unless-stopped startet Node-RED nach einem Absturz oder Host-Neustart automatisch wieder, nicht aber, wenn Sie es bewusst stoppen. Das ist für MQTT-Flows wichtig: Startet der Container neu, verbindet sich der Broker-Node selbstständig wieder und die Abonnements werden aus dem Flow wiederhergestellt, sodass sich ein Gateway nach einem Stromausfall erholt, ohne dass jemand eingreift. Kombinieren Sie das mit persistentem Speicher, wie im Folgenden beschrieben, damit die Flows nach dem Neustart auch die sind, die Sie deployt haben.

Named Volume oder Bind Mount

Sie können ein Named Volume einbinden, wie oben, oder einen Host-Ordner:

mkdir -p ~/node-red-data
sudo chown -R 1000:1000 ~/node-red-data
docker run -d --name nodered -p 1880:1880 -v ~/node-red-data:/data nodered/node-red:latest

Ein Bind Mount macht settings.js und flows.json vom Host aus leicht bearbeitbar und sicherbar. Der Haken sind die Berechtigungen: Der Container führt Node-RED als Benutzer mit der UID 1000 aus. Gehört der Host-Ordner root oder einem anderen Benutzer, kann Node-RED nicht schreiben, und Sie sehen EACCES-Fehler im Log. Das chown oben verhindert das.

	Named Volume	Bind Mount
Einrichtung	Nichts vorzubereiten	Ordner muss für UID 1000 beschreibbar sein
settings.js bearbeiten	Über `docker exec` oder einen Hilfscontainer	Direkt auf dem Host
Backups	`docker run --rm -v node_red_data:/data ...` mit tar	Jedes Datei-Backup-Werkzeug
Portabilität	Von Docker verwaltet	Sichtbarer Host-Pfad

Eine produktionsreife Docker-Compose-Datei

Für alles Langlebige beschreiben Sie den Container in Compose. Diese Datei legt das Image fest, persistiert Daten, setzt die Zeitzone und übergibt Secrets über eine Umgebungsdatei:

# docker-compose.yml
services:
  nodered:
    image: nodered/node-red:4.0.9
    container_name: nodered
    restart: unless-stopped
    ports:
      - "127.0.0.1:1880:1880"
    environment:
      - TZ=Europe/Istanbul
      - NODE_RED_CREDENTIAL_SECRET=${NODE_RED_CREDENTIAL_SECRET}
    volumes:
      - ./data:/data

# .env  (gleicher Ordner, diese Datei niemals committen)
NODE_RED_CREDENTIAL_SECRET=change-me-to-a-long-random-string

mkdir -p data && sudo chown -R 1000:1000 data
docker compose up -d

Zwei Details verdienen Beachtung. Erstens wird der Port nur auf 127.0.0.1 veröffentlicht, der Editor ist also vom Host, aber nicht aus dem Netzwerk erreichbar. Setzen Sie einen Reverse Proxy mit HTTPS davor, wenn Sie Fernzugriff brauchen, und lesen Sie Node-RED absichern, bevor Sie es exponieren. Zweitens wird das Credential Secret aus der Umgebung gelesen. Bearbeiten Sie data/settings.js und setzen Sie:

// data/settings.js
credentialSecret: process.env.NODE_RED_CREDENTIAL_SECRET,

Dieser Schlüssel verschlüsselt flows_cred.json. Lassen Sie ihn leer, erzeugt Node-RED einen Schlüssel und speichert ihn im Datenordner. Das funktioniert, bindet Ihre Zugangsdaten aber an genau diese eine Kopie. Mit einem expliziten Secret können Sie den Container überall neu aufbauen und Ihre Broker-Passwörter trotzdem entschlüsseln.

Zusätzliche Nodes im Container installieren

Nutzen Sie wie gewohnt Manage palette im Editor; Nodes werden in /data/node_modules installiert und überstehen das Neuerstellen des Containers, weil /data ein Volume ist. Als Skript geht es so:

docker exec -it nodered bash -c "cd /data && npm install @flowfuse/node-red-dashboard"
docker restart nodered

Für vollständig reproduzierbare Images bauen Sie ein eigenes Image, das Nodes zur Build-Zeit installiert:

# Dockerfile
FROM nodered/node-red:4.0.9
RUN npm install --no-audit --no-fund @flowfuse/node-red-dashboard node-red-contrib-modbus

Nodes, die nativen Code kompilieren, brauchen eventuell Build-Werkzeuge; die Image-Dokumentation auf nodered.org erklärt die verfügbaren Varianten und wie Sie diese ergänzen.

Den Container mit einem MQTT-Broker verbinden

Ein häufiger Fehler bei Node-RED in Docker ist, den MQTT-Node auf localhost zu richten. Im Container ist localhost der Container selbst, nicht Ihr Host. Verwenden Sie einen echten Hostnamen: einen Cloud-Broker, einen Servicenamen im selben Compose-Netzwerk oder host.docker.internal unter Docker Desktop.

Für einen ersten Test nutzen Sie den kostenlosen Öffentlichen MQTT-Broker. Setzen Sie im Broker-Config-Node den Server broker.connectmq.com, Port 1883 und eine eindeutige Client-ID wie nr-docker-4d2f. Abonnieren Sie connectmq/demo/4d2f/# und publizieren Sie vom Host aus (der öffentliche MQTT-Broker ist nur für Tests gedacht, alle Daten sind öffentlich lesbar):

mosquitto_pub -h broker.connectmq.com -p 1883 -i demo-host-4d2f \
  -t "connectmq/demo/4d2f/docker/test" -m '{"hello":"from host"}'

Für die Produktion wechseln Sie auf Ihren privaten Broker mit TLS. Setzen Sie als Server den Host Ihres ConnectMQ-Brokers, Port 8883, aktivieren Sie Use TLS und tragen Sie Benutzernamen, Passwort und Client-ID aus dem Portal ein. Weil das Image die Standard-CA-Zertifikate enthält, wird das Let's-Encrypt-Zertifikat ohne zusätzliche Konfiguration als vertrauenswürdig eingestuft. Die vollständige TLS-Anleitung finden Sie unter Node-RED, MQTT und TLS.

Diese Zugangsdaten geben Sie im Editor nur einmal ein. Node-RED speichert sie in flows_cred.json, verschlüsselt mit dem oben gesetzten Credential Secret, niemals im Klartext in flows.json. So können Sie die Flow-Datei teilen oder committen, ohne Ihr Broker-Passwort preiszugeben.

Checkliste für Upgrades und Backups

Sichern Sie vor jedem Upgrade den Datenordner oder das Volume.
Ändern Sie den Image-Tag in docker-compose.yml und führen Sie dann docker compose pull && docker compose up -d aus.
Beobachten Sie docker logs -f nodered auf Nodes, die nach dem Upgrade nicht laden.
Rollen Sie bei Bedarf zurück, indem Sie den vorherigen Tag wiederherstellen; der Datenordner bleibt unverändert.
Bauen Sie Nodes mit nativem Code nach einem Major-Versionswechsel von Node.js neu (npm rebuild in /data).
Halten Sie .env aus der Versionskontrolle heraus und speichern Sie sie in Ihrem Secrets-Manager.
Testen Sie gelegentlich Wiederherstellungen; ein Backup, das Sie nie wiederhergestellt haben, ist eine Vermutung.

Zeigt der MQTT-Node nach einem dieser Schritte "connecting", führt Sie der Leitfaden Node-RED MQTT verbindet nicht durch DNS-, Port-, TLS- und Client-ID-Probleme, die in Containern häufig sind.

Betreiben Sie Ihr Node-RED in Docker mit ConnectMQ

Container kümmern sich um Node-RED; ein verwalteter MQTT-Broker übernimmt die Messaging-Schicht, sodass Sie nicht auch noch einen Broker-Container betreiben und patchen müssen. ConnectMQ bietet TCP 1883, TLS 8883 und sicheres WebSocket 8084, MQTT 3.1.1 und 5.0 sowie ein Portal mit Live-Topic-Explorer, um zu prüfen, was Ihr Container publiziert. Registrieren Sie sich unter app.connectmq.com für den kostenlosen Serverless-Plan, ohne Kreditkarte, und fügen Sie die generierten Zugangsdaten in den Broker-Node ein. Einen breiteren Überblick über Hosting-Optionen bietet unser Leitfaden zum Cloud-MQTT-Broker, und das Node-RED-MQTT-Tutorial hilft beim Bau Ihrer ersten Flows.

Häufig gestellte Fragen

Wo speichert Node-RED in Docker seine Daten?

Alles, einschließlich Flows, Zugangsdaten, settings.js, Context und installierter Nodes, liegt im Container unter /data. Binden Sie es als Volume oder Bind Mount ein, damit es das Neuerstellen des Containers übersteht.

Warum kann sich mein Node-RED-Container nicht mit einem MQTT-Broker auf localhost verbinden?

In einem Container bezeichnet localhost den Container selbst. Verwenden Sie den echten Hostnamen des Brokers, einen Compose-Servicenamen oder host.docker.internal unter Docker Desktop.

Wie behebe ich Permission-denied-Fehler bei einem Bind Mount?

Der Container führt Node-RED als UID 1000 aus. Ändern Sie den Eigentümer des Host-Ordners mit sudo chown -R 1000:1000 <folder> und starten Sie den Container neu.

Kann ich Node-RED in Docker auf einem Raspberry Pi betreiben?

Ja. Das offizielle Image wird für ARM-Architekturen veröffentlicht, daher funktionieren dieselben Befehle und dieselbe Compose-Datei auf einem Raspberry Pi mit einem unterstützten Betriebssystem.

Node-RED in Docker für MQTT-Projekte betreiben